From 6e0832e0ebead7c65efb7a1899240577e3936fa8 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Fri, 11 Nov 2022 09:49:41 +0100 Subject: [PATCH] Refine reference documentation. Include Micrometer partials instead of generating those. Include upgrading section with links to release notes. Closes #1328 --- spring-data-cassandra-distribution/pom.xml | 90 ------------------- src/main/asciidoc/index.adoc | 1 + .../asciidoc/observability/_conventions.adoc | 10 +++ src/main/asciidoc/observability/_metrics.adoc | 48 ++++++++++ src/main/asciidoc/observability/_spans.adoc | 41 +++++++++ src/main/asciidoc/reference/introduction.adoc | 1 + .../asciidoc/reference/observability.adoc | 6 +- src/main/asciidoc/reference/upgrade.adoc | 10 +++ 8 files changed, 114 insertions(+), 93 deletions(-) create mode 100644 src/main/asciidoc/observability/_conventions.adoc create mode 100644 src/main/asciidoc/observability/_metrics.adoc create mode 100644 src/main/asciidoc/observability/_spans.adoc create mode 100644 src/main/asciidoc/reference/upgrade.adoc diff --git a/spring-data-cassandra-distribution/pom.xml b/spring-data-cassandra-distribution/pom.xml index 23a8c748b..3bda53ec0 100644 --- a/spring-data-cassandra-distribution/pom.xml +++ b/spring-data-cassandra-distribution/pom.xml @@ -22,13 +22,6 @@ ${basedir}/.. SDCASS - - - ${maven.multiModuleProjectDirectory}/spring-data-cassandra/ - - .* - ${maven.multiModuleProjectDirectory}/target/ - @@ -37,36 +30,6 @@ org.apache.maven.plugins maven-assembly-plugin - - org.codehaus.mojo - exec-maven-plugin - - - generate-docs - generate-resources - - java - - - io.micrometer.docs.DocsGeneratorCommand - true - - ${micrometer-docs-generator.inputPath} - ${micrometer-docs-generator.inclusionPattern} - ${micrometer-docs-generator.outputPath} - - - - - - - io.micrometer - micrometer-docs-generator - ${micrometer-docs-generator} - jar - - - org.asciidoctor asciidoctor-maven-plugin @@ -74,64 +37,11 @@ - - - spring-snapshots - Spring Snapshots - https://repo.spring.io/snapshot - - true - - - false - - - - spring-milestones - Spring Milestones - https://repo.spring.io/milestone - - false - - - - spring-release - Spring Release - https://repo.spring.io/release - - false - - - - - - spring-snapshots - Spring Snapshots - https://repo.spring.io/snapshot - - true - - - false - - - - spring-milestones - Spring Milestones - https://repo.spring.io/milestone - - false - - spring-release Spring Release https://repo.spring.io/release - - false - - diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index e3e95c4d1..9126c9882 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -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] diff --git a/src/main/asciidoc/observability/_conventions.adoc b/src/main/asciidoc/observability/_conventions.adoc new file mode 100644 index 000000000..205edf269 --- /dev/null +++ b/src/main/asciidoc/observability/_conventions.adoc @@ -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` +|=== diff --git a/src/main/asciidoc/observability/_metrics.adoc b/src/main/asciidoc/observability/_metrics.adoc new file mode 100644 index 000000000..9efd4a9d1 --- /dev/null +++ b/src/main/asciidoc/observability/_metrics.adoc @@ -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) +|=== + + diff --git a/src/main/asciidoc/observability/_spans.adoc b/src/main/asciidoc/observability/_spans.adoc new file mode 100644 index 000000000..18f990455 --- /dev/null +++ b/src/main/asciidoc/observability/_spans.adoc @@ -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 +|=== + + + + diff --git a/src/main/asciidoc/reference/introduction.adoc b/src/main/asciidoc/reference/introduction.adoc index 947c5d444..ff9c596cf 100644 --- a/src/main/asciidoc/reference/introduction.adoc +++ b/src/main/asciidoc/reference/introduction.adoc @@ -1,3 +1,4 @@ +[[cassandra.introduction]] = Introduction This part of the reference documentation explains the core functionality offered by Spring Data for Apache Cassandra. diff --git a/src/main/asciidoc/reference/observability.adoc b/src/main/asciidoc/reference/observability.adoc index 4918ff7b6..10e127d12 100644 --- a/src/main/asciidoc/reference/observability.adoc +++ b/src/main/asciidoc/reference/observability.adoc @@ -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. diff --git a/src/main/asciidoc/reference/upgrade.adoc b/src/main/asciidoc/reference/upgrade.adoc new file mode 100644 index 000000000..c15b14116 --- /dev/null +++ b/src/main/asciidoc/reference/upgrade.adoc @@ -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 <> 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. + +