Skip to content

Commit 3ea4e0f

Browse files
mp911demp911de
committed
Update documentation.
See: spring-projects#4216
1 parent e9ac77c commit 3ea4e0f

File tree

3 files changed

+27
-92
lines changed

3 files changed

+27
-92
lines changed

‎spring-data-mongodb-distribution/pom.xml

+10-30
Original file line numberDiff line numberDiff line change
@@ -40,50 +40,30 @@
4040
<artifactId>exec-maven-plugin</artifactId>
4141
<executions>
4242
<execution>
43-
<id>generate-metrics-metadata</id>
44-
<phase>prepare-package</phase>
43+
<id>generate-docs</id>
44+
<phase>generate-resources</phase>
4545
<goals>
4646
<goal>java</goal>
4747
</goals>
4848
<configuration>
49-
<mainClass>io.micrometer.docs.metrics.DocsFromSources
50-
</mainClass>
51-
</configuration>
52-
</execution>
53-
<execution>
54-
<id>generate-tracing-metadata</id>
55-
<phase>prepare-package</phase>
56-
<goals>
57-
<goal>java</goal>
58-
</goals>
59-
<configuration>
60-
<mainClass>io.micrometer.docs.spans.DocsFromSources
61-
</mainClass>
49+
<mainClass>io.micrometer.docs.DocsGeneratorCommand</mainClass>
50+
<includePluginDependencies>true</includePluginDependencies>
51+
<arguments>
52+
<argument>${micrometer-docs-generator.inputPath}</argument>
53+
<argument>${micrometer-docs-generator.inclusionPattern}</argument>
54+
<argument>${micrometer-docs-generator.outputPath}</argument>
55+
</arguments>
6256
</configuration>
6357
</execution>
6458
</executions>
6559
<dependencies>
6660
<dependency>
6761
<groupId>io.micrometer</groupId>
68-
<artifactId>micrometer-docs-generator-spans</artifactId>
69-
<version>${micrometer-docs-generator}</version>
70-
<type>jar</type>
71-
</dependency>
72-
<dependency>
73-
<groupId>io.micrometer</groupId>
74-
<artifactId>micrometer-docs-generator-metrics</artifactId>
62+
<artifactId>micrometer-docs-generator</artifactId>
7563
<version>${micrometer-docs-generator}</version>
7664
<type>jar</type>
7765
</dependency>
7866
</dependencies>
79-
<configuration>
80-
<includePluginDependencies>true</includePluginDependencies>
81-
<arguments>
82-
<argument>${micrometer-docs-generator.inputPath}</argument>
83-
<argument>${micrometer-docs-generator.inclusionPattern}</argument>
84-
<argument>${micrometer-docs-generator.outputPath}</argument>
85-
</arguments>
86-
</configuration>
8767
</plugin>
8868
<plugin>
8969
<groupId>org.asciidoctor</groupId>

‎src/main/asciidoc/index.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1]
2323

2424
include::reference/introduction.adoc[leveloffset=+1]
2525
include::reference/mongodb.adoc[leveloffset=+1]
26+
include::reference/observability.adoc[leveloffset=+1]
2627
include::reference/client-session-transactions.adoc[leveloffset=+1]
2728
include::reference/reactive-mongodb.adoc[leveloffset=+1]
2829
include::reference/mongo-repositories.adoc[leveloffset=+1]
@@ -42,4 +43,3 @@ include::{spring-data-commons-docs}/repository-namespace-reference.adoc[leveloff
4243
include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[leveloffset=+1]
4344
include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1]
4445
include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1]
45-
include::reference/observability.adoc[leveloffset=+1]

‎src/main/asciidoc/reference/observability.adoc

+16-61
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,29 @@
11
:root-target: ../../../../target/
22

3-
[[observability]]
4-
== Observability metadata
5-
6-
include::{root-target}_conventions.adoc[]
7-
8-
include::{root-target}_metrics.adoc[]
9-
10-
include::{root-target}_spans.adoc[]
11-
12-
[[observability.registration]]
13-
== Observability Registration
3+
[[mongodb.observability]]
4+
== Observability
145

156
Spring Data MongoDB currently has the most up-to-date code to support Observability in your MongoDB application.
167
These changes, however, haven't been picked up by Spring Boot (yet).
178
Until those changes are applied, if you wish to use Spring Data MongoDB's flavor of Observability, you must carry out the following steps.
189

19-
. 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.
20-
. Your project must include *Spring Boot Actuator*.
21-
. Next you must add one of the following bean definitions based on whether you're using non-reactive or reactive Spring Data MongoDB.
10+
. 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.
2211
+
23-
.Registering a synchronous (non-reactive) MongoDB Micrometer setup
12+
.Registering MongoDB Micrometer customizer setup
2413
====
2514
[source,java]
2615
----
2716
@Bean
28-
MongoClientSettingsBuilderCustomizer mongoMetricsSynchronousContextProvider(Tracer tracer,
29-
ObservationRegistry registry) {
17+
MongoClientSettingsBuilderCustomizer mongoMetricsSynchronousContextProvider(ObservationRegistry registry) {
3018
return (clientSettingsBuilder) -> {
31-
clientSettingsBuilder.contextProvider( //
32-
MongoMetricsConfigurationHelper.synchronousContextProvider(tracer, registry));
19+
clientSettingsBuilder.contextProvider(ContextProviderFactory.create(registry))
20+
.addCommandListener(new MongoObservationCommandListener(registry));
3321
};
3422
}
3523
----
3624
====
3725
+
38-
.Registering a reactive MongoDB Micrometer setup
39-
====
40-
[source,java]
41-
----
42-
@Bean
43-
MongoClientSettingsBuilderCustomizer mongoMetricsReactiveContextProvider(ObservationRegistry registry) {
44-
return (clientSettingsBuilder) -> {
45-
clientSettingsBuilder.contextProvider( //
46-
MongoMetricsReactiveConfigurationHelper.reactiveContextProvider(registry));
47-
};
48-
}
49-
----
50-
====
51-
+
52-
IMPORTANT: ONLY add one of these two bean definitions!
53-
. Add the following bean definition to listen for MongoDB command events and record them with Micrometer.
54-
+
55-
.Registering to listen for MongoDB commands.
56-
====
57-
[source,java]
58-
----
59-
@Bean
60-
MongoClientSettingsBuilderCustomizer mongoObservationCommandListenerCustomizer(MongoDBContainer mongoDBContainer,
61-
MongoObservationCommandListener commandListener) {
62-
return (clientSettingsBuilder) -> clientSettingsBuilder //
63-
.addCommandListener(commandListener);
64-
}
65-
----
66-
====
67-
. Add the following bean definition to register Spring Data MongoDB's trace observation handler
68-
+
69-
.Registering
70-
====
71-
[source,java]
72-
----
73-
@Bean
74-
ObservationRegistryCustomizer<ObservationRegistry> mongoTracingHandlerCustomizer(
75-
MongoTracingObservationHandler handler) {
76-
return handler::register;
77-
}
78-
----
79-
====
26+
. Your project must include *Spring Boot Actuator*.
8027
. Disable Spring Boot's autoconfigured MongoDB command listener and enable tracing manually by adding the following properties to your `application.properties`
8128
+
8229
.Custom settings to apply
@@ -92,3 +39,11 @@ Be sure to add any other relevant settings needed to configure the tracer you ar
9239
====
9340

9441
This should do it! You are now running with Spring Data MongoDB's usage of Spring Observability's `Observation` API.
42+
43+
include::{root-target}_conventions.adoc[]
44+
45+
include::{root-target}_metrics.adoc[]
46+
47+
include::{root-target}_spans.adoc[]
48+
49+
See also https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/#mongodb[OpenTelemetry Semantic Conventions] for further reference.

0 commit comments

Comments
 (0)