Refine reference documentation.
Include Micrometer partials instead of generating those. Include upgrading section with links to release notes. Closes #1328
This commit is contained in:
Mark Paluch
@@ -22,13 +22,6 @@
|
||||
<properties>
|
||||
<project.root>${basedir}/..</project.root>
|
||||
<dist.key>SDCASS</dist.key>
|
||||
|
||||
<!-- Observability -->
|
||||
<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/spring-data-cassandra/
|
||||
</micrometer-docs-generator.inputPath>
|
||||
<micrometer-docs-generator.inclusionPattern>.*</micrometer-docs-generator.inclusionPattern>
|
||||
<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/target/
|
||||
</micrometer-docs-generator.outputPath>
|
||||
</properties>
|
||||
|
||||
<build>
|
||||
@@ -37,36 +30,6 @@
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-assembly-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.codehaus.mojo</groupId>
|
||||
<artifactId>exec-maven-plugin</artifactId>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>generate-docs</id>
|
||||
<phase>generate-resources</phase>
|
||||
<goals>
|
||||
<goal>java</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<mainClass>io.micrometer.docs.DocsGeneratorCommand</mainClass>
|
||||
<includePluginDependencies>true</includePluginDependencies>
|
||||
<arguments>
|
||||
<argument>${micrometer-docs-generator.inputPath}</argument>
|
||||
<argument>${micrometer-docs-generator.inclusionPattern}</argument>
|
||||
<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>
|
||||
<artifactId>asciidoctor-maven-plugin</artifactId>
|
||||
@@ -74,64 +37,11 @@
|
||||
</plugins>
|
||||
</build>
|
||||
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>spring-snapshots</id>
|
||||
<name>Spring Snapshots</name>
|
||||
<url>https://repo.spring.io/snapshot</url> <!-- For Snapshots -->
|
||||
<snapshots>
|
||||
<enabled>true</enabled>
|
||||
</snapshots>
|
||||
<releases>
|
||||
<enabled>false</enabled>
|
||||
</releases>
|
||||
</repository>
|
||||
<repository>
|
||||
<id>spring-milestones</id>
|
||||
<name>Spring Milestones</name>
|
||||
<url>https://repo.spring.io/milestone</url> <!-- For Milestones -->
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</repository>
|
||||
<repository>
|
||||
<id>spring-release</id>
|
||||
<name>Spring Release</name>
|
||||
<url>https://repo.spring.io/release</url> <!-- For Releases -->
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</repository>
|
||||
</repositories>
|
||||
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>spring-snapshots</id>
|
||||
<name>Spring Snapshots</name>
|
||||
<url>https://repo.spring.io/snapshot</url> <!-- For Snapshots -->
|
||||
<snapshots>
|
||||
<enabled>true</enabled>
|
||||
</snapshots>
|
||||
<releases>
|
||||
<enabled>false</enabled>
|
||||
</releases>
|
||||
</pluginRepository>
|
||||
<pluginRepository>
|
||||
<id>spring-milestones</id>
|
||||
<name>Spring Milestones</name>
|
||||
<url>https://repo.spring.io/milestone</url> <!-- For Milestones -->
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</pluginRepository>
|
||||
<pluginRepository>
|
||||
<id>spring-release</id>
|
||||
<name>Spring Release</name>
|
||||
<url>https://repo.spring.io/release</url> <!-- For Releases -->
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
|
||||
</project>
|
||||
|
||||
@@ -22,6 +22,7 @@ include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1]
|
||||
= Reference Documentation
|
||||
|
||||
include::reference/introduction.adoc[leveloffset=+1]
|
||||
include::reference/upgrade.adoc[leveloffset=+1]
|
||||
include::reference/cassandra.adoc[leveloffset=+1]
|
||||
include::reference/observability.adoc[leveloffset=+1]
|
||||
include::reference/reactive-cassandra.adoc[leveloffset=+1]
|
||||
|
||||
10
src/main/asciidoc/observability/_conventions.adoc
Normal file
10
src/main/asciidoc/observability/_conventions.adoc
Normal file
@@ -0,0 +1,10 @@
|
||||
[[observability-conventions]]
|
||||
=== Observability - Conventions
|
||||
|
||||
Below you can find a list of all `GlobalObservabilityConventions` and `ObservabilityConventions` declared by this project.
|
||||
|
||||
.ObservationConvention implementations
|
||||
|===
|
||||
|ObservationConvention Class Name | Applicable ObservationContext Class Name
|
||||
|`org.springframework.data.cassandra.observability.DefaultCassandraObservationConvention`|`n/a`
|
||||
|===
|
||||
48
src/main/asciidoc/observability/_metrics.adoc
Normal file
48
src/main/asciidoc/observability/_metrics.adoc
Normal file
@@ -0,0 +1,48 @@
|
||||
[[observability-metrics]]
|
||||
=== Observability - Metrics
|
||||
|
||||
Below you can find a list of all metrics declared by this project.
|
||||
|
||||
[[observability-metrics-cassandra-query-observation]]
|
||||
==== Cassandra Query Observation
|
||||
|
||||
____
|
||||
Create an `io.micrometer.observation.Observation` for Cassandra-based queries.
|
||||
____
|
||||
|
||||
**Metric name** `spring.data.cassandra.query`. **Type** `timer` and **base unit** `seconds`.
|
||||
|
||||
Fully qualified name of the enclosing class `org.springframework.data.cassandra.observability.CassandraObservation`.
|
||||
|
||||
|
||||
|
||||
.Low cardinality Keys
|
||||
[cols="a,a"]
|
||||
|===
|
||||
|Name | Description
|
||||
|`db.cassandra.coordinator.dc`|
|
||||
|`db.cassandra.coordinator.id`|
|
||||
|`db.name`|Name of the Cassandra keyspace.
|
||||
|`db.operation`|The database operation.
|
||||
|`db.system`|Database system.
|
||||
|`net.peer.name`|Name of the database host.
|
||||
|`net.peer.port`|Logical remote port number.
|
||||
|`net.sock.peer.addr`|Cassandra peer address.
|
||||
|`net.sock.peer.port`|Cassandra peer port.
|
||||
|`net.transport`|Network transport.
|
||||
|`spring.data.cassandra.methodName`|The method name
|
||||
|`spring.data.cassandra.sessionName`|Cassandra session
|
||||
|===
|
||||
|
||||
.High cardinality Keys
|
||||
[cols="a,a"]
|
||||
|===
|
||||
|Name | Description
|
||||
|`db.cassandra.consistency_level`|
|
||||
|`db.cassandra.idempotence`|
|
||||
|`db.cassandra.page_size`|
|
||||
|`db.statement`|A key-value containing Cassandra CQL.
|
||||
|`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)
|
||||
|===
|
||||
|
||||
|
||||
41
src/main/asciidoc/observability/_spans.adoc
Normal file
41
src/main/asciidoc/observability/_spans.adoc
Normal file
@@ -0,0 +1,41 @@
|
||||
[[observability-spans]]
|
||||
=== Observability - Spans
|
||||
|
||||
Below you can find a list of all spans declared by this project.
|
||||
|
||||
[[observability-spans-cassandra-query-observation]]
|
||||
==== Cassandra Query Observation Span
|
||||
|
||||
> Create an `io.micrometer.observation.Observation` for Cassandra-based queries.
|
||||
|
||||
**Span name** `spring.data.cassandra.query`.
|
||||
|
||||
Fully qualified name of the enclosing class `org.springframework.data.cassandra.observability.CassandraObservation`.
|
||||
|
||||
|
||||
|
||||
.Tag Keys
|
||||
|===
|
||||
|Name | Description
|
||||
|`db.cassandra.consistency_level`|
|
||||
|`db.cassandra.coordinator.dc`|
|
||||
|`db.cassandra.coordinator.id`|
|
||||
|`db.cassandra.idempotence`|
|
||||
|`db.cassandra.page_size`|
|
||||
|`db.name`|Name of the Cassandra keyspace.
|
||||
|`db.operation`|The database operation.
|
||||
|`db.statement`|A key-value containing Cassandra CQL.
|
||||
|`db.system`|Database system.
|
||||
|`net.peer.name`|Name of the database host.
|
||||
|`net.peer.port`|Logical remote port number.
|
||||
|`net.sock.peer.addr`|Cassandra peer address.
|
||||
|`net.sock.peer.port`|Cassandra peer port.
|
||||
|`net.transport`|Network transport.
|
||||
|`spring.data.cassandra.methodName`|The method name
|
||||
|`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)
|
||||
|`spring.data.cassandra.sessionName`|Cassandra session
|
||||
|===
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
[[cassandra.introduction]]
|
||||
= Introduction
|
||||
|
||||
This part of the reference documentation explains the core functionality offered by Spring Data for Apache Cassandra.
|
||||
|
||||
@@ -32,10 +32,10 @@ Also, registers `ObservationRequestTracker.INSTANCE` with the `CqlSessionBuilder
|
||||
<2> Wraps a CQL session object to observe reactive Cassandra statement execution.
|
||||
====
|
||||
|
||||
include::../../../../target/_conventions.adoc[]
|
||||
include::../observability/_conventions.adoc[]
|
||||
|
||||
include::../../../../target/_metrics.adoc[]
|
||||
include::../observability/_metrics.adoc[]
|
||||
|
||||
include::../../../../target/_spans.adoc[]
|
||||
include::../observability/_spans.adoc[]
|
||||
|
||||
See also https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/#cassandra[OpenTelemetry Semantic Conventions] for further reference.
|
||||
|
||||
10
src/main/asciidoc/reference/upgrade.adoc
Normal file
10
src/main/asciidoc/reference/upgrade.adoc
Normal file
@@ -0,0 +1,10 @@
|
||||
include::../{spring-data-commons-docs}/upgrade.adoc[]
|
||||
|
||||
== What to Read Next
|
||||
|
||||
Once you’ve decided to upgrade your application, you can find detailed information regarding specific features in the rest of the document.
|
||||
You can find <<cassandra.migration,migration guides>> specific to major version migrations at the end of this document.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user