Skip to content

Commit 6e0832e

Browse files
mp911demp911de
committed
Refine reference documentation.
Include Micrometer partials instead of generating those. Include upgrading section with links to release notes. Closes #1328
1 parent 4d42cab commit 6e0832e

File tree

8 files changed

+114
-93
lines changed

8 files changed

+114
-93
lines changed

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

-90
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,6 @@
2222
<properties>
2323
<project.root>${basedir}/..</project.root>
2424
<dist.key>SDCASS</dist.key>
25-
26-
<!-- Observability -->
27-
<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/spring-data-cassandra/
28-
</micrometer-docs-generator.inputPath>
29-
<micrometer-docs-generator.inclusionPattern>.*</micrometer-docs-generator.inclusionPattern>
30-
<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/target/
31-
</micrometer-docs-generator.outputPath>
3225
</properties>
3326

3427
<build>
@@ -37,101 +30,18 @@
3730
<groupId>org.apache.maven.plugins</groupId>
3831
<artifactId>maven-assembly-plugin</artifactId>
3932
</plugin>
40-
<plugin>
41-
<groupId>org.codehaus.mojo</groupId>
42-
<artifactId>exec-maven-plugin</artifactId>
43-
<executions>
44-
<execution>
45-
<id>generate-docs</id>
46-
<phase>generate-resources</phase>
47-
<goals>
48-
<goal>java</goal>
49-
</goals>
50-
<configuration>
51-
<mainClass>io.micrometer.docs.DocsGeneratorCommand</mainClass>
52-
<includePluginDependencies>true</includePluginDependencies>
53-
<arguments>
54-
<argument>${micrometer-docs-generator.inputPath}</argument>
55-
<argument>${micrometer-docs-generator.inclusionPattern}</argument>
56-
<argument>${micrometer-docs-generator.outputPath}</argument>
57-
</arguments>
58-
</configuration>
59-
</execution>
60-
</executions>
61-
<dependencies>
62-
<dependency>
63-
<groupId>io.micrometer</groupId>
64-
<artifactId>micrometer-docs-generator</artifactId>
65-
<version>${micrometer-docs-generator}</version>
66-
<type>jar</type>
67-
</dependency>
68-
</dependencies>
69-
</plugin>
7033
<plugin>
7134
<groupId>org.asciidoctor</groupId>
7235
<artifactId>asciidoctor-maven-plugin</artifactId>
7336
</plugin>
7437
</plugins>
7538
</build>
7639

77-
<repositories>
78-
<repository>
79-
<id>spring-snapshots</id>
80-
<name>Spring Snapshots</name>
81-
<url>https://repo.spring.io/snapshot</url> <!-- For Snapshots -->
82-
<snapshots>
83-
<enabled>true</enabled>
84-
</snapshots>
85-
<releases>
86-
<enabled>false</enabled>
87-
</releases>
88-
</repository>
89-
<repository>
90-
<id>spring-milestones</id>
91-
<name>Spring Milestones</name>
92-
<url>https://repo.spring.io/milestone</url> <!-- For Milestones -->
93-
<snapshots>
94-
<enabled>false</enabled>
95-
</snapshots>
96-
</repository>
97-
<repository>
98-
<id>spring-release</id>
99-
<name>Spring Release</name>
100-
<url>https://repo.spring.io/release</url> <!-- For Releases -->
101-
<snapshots>
102-
<enabled>false</enabled>
103-
</snapshots>
104-
</repository>
105-
</repositories>
106-
10740
<pluginRepositories>
108-
<pluginRepository>
109-
<id>spring-snapshots</id>
110-
<name>Spring Snapshots</name>
111-
<url>https://repo.spring.io/snapshot</url> <!-- For Snapshots -->
112-
<snapshots>
113-
<enabled>true</enabled>
114-
</snapshots>
115-
<releases>
116-
<enabled>false</enabled>
117-
</releases>
118-
</pluginRepository>
119-
<pluginRepository>
120-
<id>spring-milestones</id>
121-
<name>Spring Milestones</name>
122-
<url>https://repo.spring.io/milestone</url> <!-- For Milestones -->
123-
<snapshots>
124-
<enabled>false</enabled>
125-
</snapshots>
126-
</pluginRepository>
12741
<pluginRepository>
12842
<id>spring-release</id>
12943
<name>Spring Release</name>
13044
<url>https://repo.spring.io/release</url> <!-- For Releases -->
131-
<snapshots>
132-
<enabled>false</enabled>
133-
</snapshots>
13445
</pluginRepository>
13546
</pluginRepositories>
136-
13747
</project>

‎src/main/asciidoc/index.adoc

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

2424
include::reference/introduction.adoc[leveloffset=+1]
25+
include::reference/upgrade.adoc[leveloffset=+1]
2526
include::reference/cassandra.adoc[leveloffset=+1]
2627
include::reference/observability.adoc[leveloffset=+1]
2728
include::reference/reactive-cassandra.adoc[leveloffset=+1]

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[[observability-conventions]]
2+
=== Observability - Conventions
3+
4+
Below you can find a list of all `GlobalObservabilityConventions` and `ObservabilityConventions` declared by this project.
5+
6+
.ObservationConvention implementations
7+
|===
8+
|ObservationConvention Class Name | Applicable ObservationContext Class Name
9+
|`org.springframework.data.cassandra.observability.DefaultCassandraObservationConvention`|`n/a`
10+
|===

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

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
[[observability-metrics]]
2+
=== Observability - Metrics
3+
4+
Below you can find a list of all metrics declared by this project.
5+
6+
[[observability-metrics-cassandra-query-observation]]
7+
==== Cassandra Query Observation
8+
9+
____
10+
Create an `io.micrometer.observation.Observation` for Cassandra-based queries.
11+
____
12+
13+
**Metric name** `spring.data.cassandra.query`. **Type** `timer` and **base unit** `seconds`.
14+
15+
Fully qualified name of the enclosing class `org.springframework.data.cassandra.observability.CassandraObservation`.
16+
17+
18+
19+
.Low cardinality Keys
20+
[cols="a,a"]
21+
|===
22+
|Name | Description
23+
|`db.cassandra.coordinator.dc`|
24+
|`db.cassandra.coordinator.id`|
25+
|`db.name`|Name of the Cassandra keyspace.
26+
|`db.operation`|The database operation.
27+
|`db.system`|Database system.
28+
|`net.peer.name`|Name of the database host.
29+
|`net.peer.port`|Logical remote port number.
30+
|`net.sock.peer.addr`|Cassandra peer address.
31+
|`net.sock.peer.port`|Cassandra peer port.
32+
|`net.transport`|Network transport.
33+
|`spring.data.cassandra.methodName`|The method name
34+
|`spring.data.cassandra.sessionName`|Cassandra session
35+
|===
36+
37+
.High cardinality Keys
38+
[cols="a,a"]
39+
|===
40+
|Name | Description
41+
|`db.cassandra.consistency_level`|
42+
|`db.cassandra.idempotence`|
43+
|`db.cassandra.page_size`|
44+
|`db.statement`|A key-value containing Cassandra CQL.
45+
|`spring.data.cassandra.node[%s].error`|A tag containing error that occurred for the given node. (since the name contains `%s` the final value will be resolved at runtime)
46+
|===
47+
48+

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

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
[[observability-spans]]
2+
=== Observability - Spans
3+
4+
Below you can find a list of all spans declared by this project.
5+
6+
[[observability-spans-cassandra-query-observation]]
7+
==== Cassandra Query Observation Span
8+
9+
> Create an `io.micrometer.observation.Observation` for Cassandra-based queries.
10+
11+
**Span name** `spring.data.cassandra.query`.
12+
13+
Fully qualified name of the enclosing class `org.springframework.data.cassandra.observability.CassandraObservation`.
14+
15+
16+
17+
.Tag Keys
18+
|===
19+
|Name | Description
20+
|`db.cassandra.consistency_level`|
21+
|`db.cassandra.coordinator.dc`|
22+
|`db.cassandra.coordinator.id`|
23+
|`db.cassandra.idempotence`|
24+
|`db.cassandra.page_size`|
25+
|`db.name`|Name of the Cassandra keyspace.
26+
|`db.operation`|The database operation.
27+
|`db.statement`|A key-value containing Cassandra CQL.
28+
|`db.system`|Database system.
29+
|`net.peer.name`|Name of the database host.
30+
|`net.peer.port`|Logical remote port number.
31+
|`net.sock.peer.addr`|Cassandra peer address.
32+
|`net.sock.peer.port`|Cassandra peer port.
33+
|`net.transport`|Network transport.
34+
|`spring.data.cassandra.methodName`|The method name
35+
|`spring.data.cassandra.node[%s].error`|A tag containing error that occurred for the given node. (since the name contains `%s` the final value will be resolved at runtime)
36+
|`spring.data.cassandra.sessionName`|Cassandra session
37+
|===
38+
39+
40+
41+

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

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
[[cassandra.introduction]]
12
= Introduction
23

34
This part of the reference documentation explains the core functionality offered by Spring Data for Apache Cassandra.

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

+3-3
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,10 @@ Also, registers `ObservationRequestTracker.INSTANCE` with the `CqlSessionBuilder
3232
<2> Wraps a CQL session object to observe reactive Cassandra statement execution.
3333
====
3434

35-
include::../../../../target/_conventions.adoc[]
35+
include::../observability/_conventions.adoc[]
3636

37-
include::../../../../target/_metrics.adoc[]
37+
include::../observability/_metrics.adoc[]
3838

39-
include::../../../../target/_spans.adoc[]
39+
include::../observability/_spans.adoc[]
4040

4141
See also https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/#cassandra[OpenTelemetry Semantic Conventions] for further reference.

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
include::../{spring-data-commons-docs}/upgrade.adoc[]
2+
3+
== What to Read Next
4+
5+
Once you’ve decided to upgrade your application, you can find detailed information regarding specific features in the rest of the document.
6+
You can find <<cassandra.migration,migration guides>> specific to major version migrations at the end of this document.
7+
8+
Spring Data's documentation is specific to that version, so any information that you find in here will contain the most up-to-date changes that are in that version.
9+
10+

0 commit comments

Comments
 (0)