mindol1004/spring-data-mongodb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation.

Browse Source 
See: #4216
This commit is contained in:
Mark Paluch
2022-10-20 16:42:17 +02:00
parent e9ac77c058
commit 3ea4e0f9dd
3 changed files with 37 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
spring-data-mongodb-distribution/pom.xml
View File

@@ -40,43 +40,13 @@
<artifactId>exec-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-metrics-metadata</id>
<phase>prepare-package</phase>
<id>generate-docs</id>
<phase>generate-resources</phase>
<goals>
<goal>java</goal>
</goals>
<configuration>
<mainClass>io.micrometer.docs.metrics.DocsFromSources
</mainClass>
</configuration>
</execution>
<execution>
<id>generate-tracing-metadata</id>
<phase>prepare-package</phase>
<goals>
<goal>java</goal>
</goals>
<configuration>
<mainClass>io.micrometer.docs.spans.DocsFromSources
</mainClass>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-docs-generator-spans</artifactId>
<version>${micrometer-docs-generator}</version>
<type>jar</type>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-docs-generator-metrics</artifactId>
<version>${micrometer-docs-generator}</version>
<type>jar</type>
</dependency>
</dependencies>
<configuration>
<mainClass>io.micrometer.docs.DocsGeneratorCommand</mainClass>
<includePluginDependencies>true</includePluginDependencies>
<arguments>
<argument>${micrometer-docs-generator.inputPath}</argument>
@@ -84,6 +54,16 @@
<argument>${micrometer-docs-generator.outputPath}</argument>
</arguments>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-docs-generator</artifactId>
<version>${micrometer-docs-generator}</version>
<type>jar</type>
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>

2
src/main/asciidoc/index.adoc
View File

@@ -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]

97
src/main/asciidoc/reference/observability.adoc
View File

@@ -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.
. 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 MongoDB Micrometer customizer setup
====
[source,java]
----
@Bean
MongoClientSettingsBuilderCustomizer mongoMetricsSynchronousContextProvider(ObservationRegistry registry) {
return (clientSettingsBuilder) -> {
clientSettingsBuilder.contextProvider(ContextProviderFactory.create(registry))
.addCommandListener(new MongoObservationCommandListener(registry));
};
}
----
====
+
. 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.
+
.Registering a synchronous (non-reactive) MongoDB Micrometer setup
====
[source,java]
----
@Bean
MongoClientSettingsBuilderCustomizer mongoMetricsSynchronousContextProvider(Tracer tracer,
ObservationRegistry registry) {
return (clientSettingsBuilder) -> {
clientSettingsBuilder.contextProvider( //
MongoMetricsConfigurationHelper.synchronousContextProvider(tracer, 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<ObservationRegistry> mongoTracingHandlerCustomizer(
MongoTracingObservationHandler handler) {
return handler::register;
}
----
====
. 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.