diff --git a/docs/src/main/asciidoc/dev-services.adoc b/docs/src/main/asciidoc/dev-services.adoc index d668961c461e6..f997f451cf572 100644 --- a/docs/src/main/asciidoc/dev-services.adoc +++ b/docs/src/main/asciidoc/dev-services.adoc @@ -129,7 +129,7 @@ link:{neo4j-guide}#dev-services[Neo4j Guide]. The Infinispan Dev Service will be enabled when the `quarkus-infinispan-client` extension is present in your application, and the server address has not been explicitly configured. More information can be found in the -xref:infinispan-client.adoc#dev-services[Infinispan Guide]. +xref:infinispan-dev-services.adoc[Infinispan Dev Services Guide]. include::{generated-dir}/config/quarkus-infinispan-client-infinispan-client-dev-service-build-time-config.adoc[opts=optional, leveloffset=+1] diff --git a/docs/src/main/asciidoc/infinispan-client.adoc b/docs/src/main/asciidoc/infinispan-client.adoc index 051f350f5ec8e..4e68b44e224fc 100644 --- a/docs/src/main/asciidoc/infinispan-client.adoc +++ b/docs/src/main/asciidoc/infinispan-client.adoc @@ -6,7 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc = Infinispan Client include::_attributes.adoc[] :categories: data -:summary: Infinispan is an in memory data grid that allows running in a server outside of application processes. This extension provides functionality to allow the client that can connect to said server when running in Quarkus. +:summary: Infinispan is an in memory distributed data store and cache server that offers flexible deployment options and robust capabilities for storing, managing, and processing data. Infinispan is a distributed, in-memory key/value store that provides Quarkus applications with a highly configurable and independently scalable data layer. @@ -114,6 +114,10 @@ When you access the `/q/health/ready` endpoint of your application you will have This behavior can be disabled via the property `quarkus.infinispan-client.health.enabled`. +=== Tracing with OpenTelemetry +Infinispan supports instrumentation of the server via OpenTelemetry. Having the `quarkus-opentelemetry` extension will propagate +the traces from the Infinispan Client to the Server. +This behavior can be disabled via the property `quarkus.infinispan-client.tracing.propagation.enabled` === Creating caches from the client @@ -507,7 +511,10 @@ You need to register the generated Protobuf schemas with Infinispan Server to pe [TIP] ==== You can check the schemas that exist under the `Schemas` tab by logging into -Infinispan Console at `http://localhost:11222` +Infinispan Console at `http://SERVER_HOST:SERVER_PORT` (for example `http://localhost:11222`). + +Check the xref:infinispan-dev-services.adoc[Infinispan Dev Services Guide] to connect to the Infinispan +Dev Services server. ==== By default, Protobuf schemas generated this way will be registered by this extension when the client first connects. @@ -712,15 +719,7 @@ When you use the infinispan-client extension in dev mode or in test, Quarkus aut === Enabling / Disabling Dev Services for Infinispan -Dev Services for Infinispan is automatically enabled unless: - -- `quarkus.infinispan-client.devservices.enabled` is set to `false` -- the `quarkus.infinispan-client.hosts` is configured -- the `quarkus.infinispan-client.uri` is configured - -Dev Services for Infinispan relies on Docker to start the broker. -If your environment does not support Docker, you will need to start the broker manually, or connect to an already running broker. -You can configure the broker address using `quarkus.infinispan-client.hosts`. +NOTE: Learn more in the xref:infinispan-dev-services.adoc[Infinispan Dev Services guide]. == Shared server diff --git a/docs/src/main/asciidoc/infinispan-dev-services.adoc b/docs/src/main/asciidoc/infinispan-dev-services.adoc new file mode 100644 index 0000000000000..27d8f8aba7e65 --- /dev/null +++ b/docs/src/main/asciidoc/infinispan-dev-services.adoc @@ -0,0 +1,120 @@ +//// +This guide is maintained in the main Quarkus repository +and pull requests should be submitted there: +https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc +//// += Dev Services for Infinispan +include::_attributes.adoc[] +:categories: data +:summary: Start Infinispan automatically in dev and test modes. + +Quarkus supports a feature called Dev Services that allows you to create various datasources without any config. +If you have docker running and have not configured `quarkus.infinispan-client.hosts`, +Quarkus will automatically start an Infinispan container when running tests or dev mode, and automatically configure the connection. + +Available properties to customize the Infinispan DevService. + +include::{generated-dir}/config/quarkus-infinispan-client-config-group-dev-services-config.adoc[opts=optional, leveloffset=+1] + +When running the production version of the application, the Infinispan connection need to be configured as normal, +so if you want to include a production database config in your `application.properties` and continue to use Dev Services +we recommend that you use the `%prod.` profile to define your Infinispan settings. + +Dev Services for Infinispan relies on Docker to start the server. + +== Connecting to the running Infinispan Server + +You *don't need to configure anything in dev mode*. +The server will be running in a random port. +If you need a fixed port, then configure `quarkus.infinispan-client.devservices.port` property. + +[NOTE] +==== +The running Infinispan Server has authentication enabled and a user with full admin role. +The credentials of the user are *admin/password*. +==== + +=== Accessing to the Infinispan Server Console +Infinispan Server provides a web console that can be accessed with a browser: + +. Open the xref:dev-ui.adoc[Dev UI] +. You will see an *Infinispan Client* box. Click on *Web Console* and enter the credentials above. + +If your environment does not support Docker, you will need to spin up an Infinispan Server manually, or connect to an already running server. + +== Overriding the Infinispan Server Image + +The extension is updated regularly and the Dev Services will start the latest final version image of Infinispan. +Use `quarkus.infinispan-client.devservices.image-name` property to specify another image that fits your needs. + +== Enabling / Disabling Dev Services for Infinispan + +Dev Services for Infinispan is automatically enabled unless: + +- `quarkus.infinispan-client.devservices.enabled` is set to `false` +- the `quarkus.infinispan-client.server-list` is configured + +Dev Services for Infinispan relies on Docker to start the broker. +If your environment does not support Docker, you will need to start the broker manually, or connect to an already running broker. +You can configure the broker address using `quarkus.infinispan-client.server-list`. + +== Cross Site Replication +If you want run the Infinispan Server container with Cross Site Replication configuration, you need to provide a site name. + +[source,properties] +---- +quarkus.infinispan-client.devservices.site=NYC <1> +quarkus.infinispan-client.devservices.mcast-port=46666 <2> +---- + +<1> Provides a site name for your Infinispan cluster +<2> Eventually configure a mcastPort if you want to avoid creating a cluster with another container + +[INFO] +==== +Learn more about Cross Site Replication in the Infinispan Cross Site Replication link:https://infinispan.org/docs/stable/titles/xsite/xsite.html[documentation guide] +and in the Infinispan Cross Site Replication +link:https://infinispan.org/tutorials/simple/simple_tutorials.html#cross-site-replication_remote-cache-tutorials[simple code tutorial]. +==== + + +== Tracing with OpenTelemetry + +Infinispan supports instrumentation of the server via OpenTelemetry. Enable tracing setting `quarkus.infinispan-client.devservices.tracing.enabled` to true. +The default otlp exporter endpoint is `http://localhost:4317`. +If you are running Jaeger in a container as explained in the xref:opentelemetry.adoc[OpenTelemetry guide], since the containers +are running in the default network, Infinispan container won't have access to localhost. +You need to get the IP running the following command and configure the `quarkus.infinispan-client.devservices.tracing.exporter.otlp.endpoint` property. + +[source,bash] +---- +docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' jaeger +---- + +== Persistence layer for Infinispan + +Infinispan caches provide several features that need to connect to a persistence layer using a +particular SQL database driver such as persisting caches in a SQL database or off-loading database +tables or queries with SQL cache stores. + +Infinispan needs the SQL Java Driver depending on the database kind the application is using. +To spin up a container with a particular SQL driver, configure `quarkus.infinispan-client.devservices.artifacts`. + + +TIP: Learn more about persistence and SQL Cache Stores check the https://github.com/infinispan-demos/infinispan-sqlstore-demo[SQL Store Demo + Quarkus Demo] and +the https://infinispan.org/docs/stable/titles/configuring/configuring.html#persistence[Infinispan Persistence Documentation] guide. + + +== Shared server + +Most of the time you need to share the server between applications. +Dev Services for Infinispan implements a _service discovery_ mechanism for your multiple Quarkus applications running in _dev_ mode to share a single server. + +NOTE: Dev Services for Infinispan starts the container with the `infinispan` label which is used to identify the container. + +If you need multiple (shared) servers, you can configure the `quarkus.infinispan-client.devservices.service-name` attribute and indicate the server name. +It looks for a container with the same value, or starts a new one if none can be found. +The default service name is `infinispan`. + +Sharing is enabled by default in dev mode, but disabled in test mode. +You can disable the sharing with `quarkus.infinispan-client.devservices.shared=false` \ No newline at end of file diff --git a/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServiceProcessor.java b/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServiceProcessor.java index 43dfe64330fd8..fdb355c3f0a6f 100644 --- a/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServiceProcessor.java +++ b/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServiceProcessor.java @@ -206,6 +206,21 @@ public QuarkusInfinispanContainer(InfinispanDevServicesConfig config, } withUser(DEFAULT_USERNAME); withPassword(InfinispanDevServiceProcessor.DEFAULT_PASSWORD); + String command = ""; + if (config.site.isPresent()) { + command = "-c infinispan-xsite.xml -Dinfinispan.site.name=" + config.site.get(); + } + if (config.mcastPort.isPresent()) { + command = command + " -Djgroups.mcast_port=" + config.mcastPort.getAsInt(); + } + if (config.tracing.isPresent()) { + command = command + " -Dinfinispan.tracing.enabled=" + config.tracing.get(); + command = command + " -Dotel.exporter.otlp.endpoint=" + config.exporterOtlpEndpoint.get(); + command = command + " -Dotel.service.name=infinispan-server-service -Dotel.metrics.exporter=none"; + } + if (!command.isEmpty()) { + withCommand(command); + } config.artifacts.ifPresent(a -> withArtifacts(a.toArray(new String[0]))); } diff --git a/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServicesConfig.java b/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServicesConfig.java index e41d7272b7204..1ad58e8e86646 100644 --- a/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServicesConfig.java +++ b/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/devservices/InfinispanDevServicesConfig.java @@ -74,6 +74,42 @@ public class InfinispanDevServicesConfig { @ConfigItem public Optional> artifacts; + /** + * Add a site name to start the Infinispan Server Container with Cross Site Replication enabled (ex. lon). + * Cross Site Replication is the capability to connect two separate Infinispan Server Clusters that might run + * in different Data Centers, and configure backup caches to copy the data across the clusters with active-active + * or active-passive replication. + * See more about Cross Site Replication in the Infinispan Documentation + * https://infinispan.org/docs/stable/titles/xsite/xsite.html + * Configure {@link #mcastPort} to avoid forming a cluster with any other running Infinispan Server container. + */ + @ConfigItem + public Optional site; + + /** + * If you are running an Infinispan Server already in docker, if the containers use the same mcastPort they will form a + * cluster. + * Set a different mcastPort to create a separate cluster in Docker (e. 46656). + * A common use case in a local Docker development mode, is the need of having two different Infinispan Clusters + * with Cross Site Replication enabled. + * see + * https://github.com/infinispan/infinispan-simple-tutorials/blob/main/infinispan-remote/cross-site-replication/docker-compose/ + */ + @ConfigItem + public OptionalInt mcastPort; + + /** + * Runs the Infinispan Server container with tracing enabled. Traces are disabled by default + */ + @ConfigItem(name = "tracing.enabled", defaultValue = "false") + public Optional tracing; + + /** + * Sets Infinispan Server otlp endpoint. Default value is http://localhost:4317 + */ + @ConfigItem(name = "tracing.exporter.otlp.endpoint", defaultValue = "http://localhost:4317") + public Optional exporterOtlpEndpoint; + @Override public boolean equals(Object o) { if (this == o) diff --git a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java index ed542925fb323..15ea700883c3a 100644 --- a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java +++ b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java @@ -214,6 +214,9 @@ private ConfigurationBuilder builderFromProperties(Properties properties) { } } + properties.put(ConfigurationProperties.TRACING_PROPAGATION_ENABLED, + infinispanClientRuntimeConfig.tracingPropagationEnabled); + if (infinispanClientRuntimeConfig.clientIntelligence.isPresent()) { properties.put(ConfigurationProperties.CLIENT_INTELLIGENCE, infinispanClientRuntimeConfig.clientIntelligence.get()); } diff --git a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java index 0062fc4c0aeba..090a599424eab 100644 --- a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java +++ b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java @@ -194,6 +194,13 @@ public class InfinispanClientRuntimeConfig { @ConfigItem Optional> sslCiphers; + /** + * Whether a tracing propagation is enabled in case the Opentelemetry extension is present. + * By default the propagation of the context is propagated from the client to the Infinispan Server. + */ + @ConfigItem(name = "tracing.propagation.enabled", defaultValue = "true") + public boolean tracingPropagationEnabled; + /** * Configures caches from the client with the provided configuration. */