From 3ea4e0f9ddbae6422fe97a89d2dd0ca41d062d53 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Thu, 20 Oct 2022 16:42:17 +0200 Subject: [PATCH] Update documentation. See: #4216 --- spring-data-mongodb-distribution/pom.xml | 40 +++------- src/main/asciidoc/index.adoc | 2 +- .../asciidoc/reference/observability.adoc | 77 ++++--------------- 3 files changed, 27 insertions(+), 92 deletions(-) diff --git a/spring-data-mongodb-distribution/pom.xml b/spring-data-mongodb-distribution/pom.xml index 0412911f8..9529262e9 100644 --- a/spring-data-mongodb-distribution/pom.xml +++ b/spring-data-mongodb-distribution/pom.xml @@ -40,50 +40,30 @@ exec-maven-plugin - generate-metrics-metadata - prepare-package + generate-docs + generate-resources java - io.micrometer.docs.metrics.DocsFromSources - - - - - generate-tracing-metadata - prepare-package - - java - - - io.micrometer.docs.spans.DocsFromSources - + io.micrometer.docs.DocsGeneratorCommand + true + + ${micrometer-docs-generator.inputPath} + ${micrometer-docs-generator.inclusionPattern} + ${micrometer-docs-generator.outputPath} + io.micrometer - micrometer-docs-generator-spans - ${micrometer-docs-generator} - jar - - - io.micrometer - micrometer-docs-generator-metrics + micrometer-docs-generator ${micrometer-docs-generator} jar - - true - - ${micrometer-docs-generator.inputPath} - ${micrometer-docs-generator.inclusionPattern} - ${micrometer-docs-generator.outputPath} - - org.asciidoctor diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index e96d27503..2eb7f5432 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -23,6 +23,7 @@ include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1] include::reference/introduction.adoc[leveloffset=+1] include::reference/mongodb.adoc[leveloffset=+1] +include::reference/observability.adoc[leveloffset=+1] include::reference/client-session-transactions.adoc[leveloffset=+1] include::reference/reactive-mongodb.adoc[leveloffset=+1] include::reference/mongo-repositories.adoc[leveloffset=+1] @@ -42,4 +43,3 @@ include::{spring-data-commons-docs}/repository-namespace-reference.adoc[leveloff include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[leveloffset=+1] include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1] include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1] -include::reference/observability.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/reference/observability.adoc b/src/main/asciidoc/reference/observability.adoc index 37d4fdbbd..5d4679556 100644 --- a/src/main/asciidoc/reference/observability.adoc +++ b/src/main/asciidoc/reference/observability.adoc @@ -1,82 +1,29 @@ :root-target: ../../../../target/ -[[observability]] -== Observability metadata - -include::{root-target}_conventions.adoc[] - -include::{root-target}_metrics.adoc[] - -include::{root-target}_spans.adoc[] - -[[observability.registration]] -== Observability Registration +[[mongodb.observability]] +== Observability Spring Data MongoDB currently has the most up-to-date code to support Observability in your MongoDB application. These changes, however, haven't been picked up by Spring Boot (yet). Until those changes are applied, if you wish to use Spring Data MongoDB's flavor of Observability, you must carry out the following steps. -. First of all, you must opt into Spring Data MongoDB's configuration settings by adding the `@EnableMongoObservability` to either your `@SpringBootApplication` class or one of your configuration classes. -. Your project must include *Spring Boot Actuator*. -. Next you must add one of the following bean definitions based on whether you're using non-reactive or reactive Spring Data MongoDB. +. First of all, you must opt into Spring Data MongoDB's configuration settings by customizing `MongoClientSettings` through either your `@SpringBootApplication` class or one of your configuration classes. + -.Registering a synchronous (non-reactive) MongoDB Micrometer setup +.Registering MongoDB Micrometer customizer setup ==== [source,java] ---- @Bean -MongoClientSettingsBuilderCustomizer mongoMetricsSynchronousContextProvider(Tracer tracer, - ObservationRegistry registry) { +MongoClientSettingsBuilderCustomizer mongoMetricsSynchronousContextProvider(ObservationRegistry registry) { return (clientSettingsBuilder) -> { - clientSettingsBuilder.contextProvider( // - MongoMetricsConfigurationHelper.synchronousContextProvider(tracer, registry)); + clientSettingsBuilder.contextProvider(ContextProviderFactory.create(registry)) + .addCommandListener(new MongoObservationCommandListener(registry)); }; } ---- ==== + -.Registering a reactive MongoDB Micrometer setup -==== -[source,java] ----- -@Bean -MongoClientSettingsBuilderCustomizer mongoMetricsReactiveContextProvider(ObservationRegistry registry) { - return (clientSettingsBuilder) -> { - clientSettingsBuilder.contextProvider( // - MongoMetricsReactiveConfigurationHelper.reactiveContextProvider(registry)); - }; -} ----- -==== -+ -IMPORTANT: ONLY add one of these two bean definitions! -. Add the following bean definition to listen for MongoDB command events and record them with Micrometer. -+ -.Registering to listen for MongoDB commands. -==== -[source,java] ----- -@Bean -MongoClientSettingsBuilderCustomizer mongoObservationCommandListenerCustomizer(MongoDBContainer mongoDBContainer, - MongoObservationCommandListener commandListener) { - return (clientSettingsBuilder) -> clientSettingsBuilder // - .addCommandListener(commandListener); -} ----- -==== -. Add the following bean definition to register Spring Data MongoDB's trace observation handler -+ -.Registering -==== -[source,java] ----- -@Bean -ObservationRegistryCustomizer mongoTracingHandlerCustomizer( - MongoTracingObservationHandler handler) { - return handler::register; -} ----- -==== +. Your project must include *Spring Boot Actuator*. . Disable Spring Boot's autoconfigured MongoDB command listener and enable tracing manually by adding the following properties to your `application.properties` + .Custom settings to apply @@ -92,3 +39,11 @@ Be sure to add any other relevant settings needed to configure the tracer you ar ==== This should do it! You are now running with Spring Data MongoDB's usage of Spring Observability's `Observation` API. + +include::{root-target}_conventions.adoc[] + +include::{root-target}_metrics.adoc[] + +include::{root-target}_spans.adoc[] + +See also https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/#mongodb[OpenTelemetry Semantic Conventions] for further reference.