From 2e18d1e2283afc564ce82eeb602c0c668673903f Mon Sep 17 00:00:00 2001 From: Surbhi Garg Date: Wed, 5 Nov 2025 19:15:48 +0530 Subject: [PATCH 1/2] chore: update metrics and traces documentation --- .readme-partials.yaml | 232 +++++++----------------------------------- 1 file changed, 34 insertions(+), 198 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index 65ae24d8b58..392f727e622 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -52,217 +52,30 @@ custom_content: | ## Metrics - ### Available client-side metrics: - - * `spanner/max_in_use_sessions`: This returns the maximum - number of sessions that have been in use during the last maintenance window - interval, so as to provide an indication of the amount of activity currently - in the database. - - * `spanner/max_allowed_sessions`: This shows the maximum - number of sessions allowed. - - * `spanner/num_sessions_in_pool`: This metric allows users to - see instance-level and database-level data for the total number of sessions in - the pool at this very moment. - - * `spanner/num_acquired_sessions`: This metric allows - users to see the total number of acquired sessions. - - * `spanner/num_released_sessions`: This metric allows - users to see the total number of released (destroyed) sessions. - - * `spanner/get_session_timeouts`: This gives you an - indication of the total number of get session timed-out instead of being - granted (the thread that requested the session is placed in a wait queue where - it waits until a session is released into the pool by another thread) due to - pool exhaustion since the server process started. - - * `spanner/gfe_latency`: This metric shows latency between - Google's network receiving an RPC and reading back the first byte of the response. - - * `spanner/gfe_header_missing_count`: This metric shows the - number of RPC responses received without the server-timing header, most likely - indicating that the RPC never reached Google's network. - - ### Instrument with OpenTelemetry - - Cloud Spanner client supports [OpenTelemetry Metrics](https://opentelemetry.io/), - which gives insight into the client internals and aids in debugging/troubleshooting - production issues. OpenTelemetry metrics will provide you with enough data to enable you to - spot, and investigate the cause of any unusual deviations from normal behavior. - - All Cloud Spanner Metrics are prefixed with `spanner/` and uses `cloud.google.com/java` as [Instrumentation Scope](https://opentelemetry.io/docs/concepts/instrumentation-scope/). The - metrics will be tagged with: - * `database`: the target database name. - * `instance_id`: the instance id of the target Spanner instance. - * `client_id`: the user defined database client id. - - By default, the functionality is disabled. You need to add OpenTelemetry dependencies, enable OpenTelemetry metrics and must configure the OpenTelemetry with appropriate exporters at the startup of your application: - - #### OpenTelemetry Dependencies - If you are using Maven, add this to your pom.xml file - ```xml - - io.opentelemetry - opentelemetry-sdk - {opentelemetry.version} - - - io.opentelemetry - opentelemetry-sdk-metrics - {opentelemetry.version} - - - io.opentelemetry - opentelemetry-exporter-otlp - {opentelemetry.version} - - ``` - If you are using Gradle, add this to your dependencies - ```Groovy - compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}' - compile 'io.opentelemetry:opentelemetry-sdk-metrics:{opentelemetry.version}' - compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}' - ``` - - #### OpenTelemetry Configuration - By default, all metrics are disabled. To enable metrics and configure the OpenTelemetry follow below: - - ```java - // Enable OpenTelemetry metrics before injecting OpenTelemetry object. - SpannerOptions.enableOpenTelemetryMetrics(); - - SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder() - // Use Otlp exporter or any other exporter of your choice. - .registerMetricReader(PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build()) - .build()) - .build(); - - OpenTelemetry openTelemetry = OpenTelemetrySdk.builder() - .setMeterProvider(sdkMeterProvider) - .build() - - SpannerOptions options = SpannerOptions.newBuilder() - // Inject OpenTelemetry object via Spanner Options or register OpenTelemetry object as Global - .setOpenTelemetry(openTelemetry) - .build(); - - Spanner spanner = options.getService(); - ``` + Cloud Spanner client supports [client-side metrics](https://cloud.google.com/spanner/docs/view-manage-client-side-metrics) that you can use along with server-side metrics to optimize performance and troubleshoot performance issues if they occur. - #### OpenTelemetry SQL Statement Tracing - The OpenTelemetry traces that are generated by the Java client include any request and transaction - tags that have been set. The traces can also include the SQL statements that are executed and the - name of the thread that executes the statement. Enable this with the `enableExtendedTracing` - option: + Client-side metrics are measured from the time a request leaves your application to the time your application receives the response. + In contrast, server-side metrics are measured from the time Spanner receives a request until the last byte of data is sent to the client. + + These metrics are enabled by default. You can opt out of using client-side metrics with the following code: ``` SpannerOptions options = SpannerOptions.newBuilder() - .setOpenTelemetry(openTelemetry) - .setEnableExtendedTracing(true) + .setBuiltInMetricsEnabled(false) .build(); ``` - This option can also be enabled by setting the environment variable - `SPANNER_ENABLE_EXTENDED_TRACING=true`. - - #### OpenTelemetry API Tracing - You can enable tracing of each API call that the Spanner client executes with the `enableApiTracing` - option. These traces also include any retry attempts for an API call: - - ``` - SpannerOptions options = SpannerOptions.newBuilder() - .setOpenTelemetry(openTelemetry) - .setEnableApiTracing(true) - .build(); - ``` - - This option can also be enabled by setting the environment variable - `SPANNER_ENABLE_API_TRACING=true`. + You can also disable these metrics by setting `SPANNER_DISABLE_BUILTIN_METRICS` to `true`. - > Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release. - - - ### Instrument with OpenCensus - - > Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/). - We recommend migrating to OpenTelemetry, the successor project. - - Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/), - which gives insight into the client internals and aids in debugging/troubleshooting - production issues. OpenCensus metrics will provide you with enough data to enable you to - spot, and investigate the cause of any unusual deviations from normal behavior. - - All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner` - - The metrics are tagged with: - * `database`: the target database name. - * `instance_id`: the instance id of the target Spanner instance. - * `client_id`: the user defined database client id. - * `library_version`: the version of the library that you're using. - - - By default, the functionality is disabled. You need to include opencensus-impl - dependency to collect the data and exporter dependency to export to backend. - - [Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information. - - #### OpenCensus Dependencies - - If you are using Maven, add this to your pom.xml file - ```xml - - io.opencensus - opencensus-impl - 0.30.0 - runtime - - - io.opencensus - opencensus-exporter-stats-stackdriver - 0.30.0 - - ``` - If you are using Gradle, add this to your dependencies - ```Groovy - compile 'io.opencensus:opencensus-impl:0.30.0' - compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0' - ``` - - #### Configure the OpenCensus Exporter - - At the start of your application configure the exporter: - - ```java - import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter; - // Enable OpenCensus exporters to export metrics to Stackdriver Monitoring. - // Exporters use Application Default Credentials to authenticate. - // See https://developers.google.com/identity/protocols/application-default-credentials - // for more details. - // The minimum reporting period for Stackdriver is 1 minute. - StackdriverStatsExporter.createAndRegister(); - ``` - #### Enable RPC Views - - By default, all session metrics are enabled. To enable RPC views, use either of the following method: - - ```java - // Register views for GFE metrics, including gfe_latency and gfe_header_missing_count. - SpannerRpcViews.registerGfeLatencyAndHeaderMissingCountViews(); - - // Register GFE Latency view. - SpannerRpcViews.registerGfeLatencyView(); - - // Register GFE Header Missing Count view. - SpannerRpcViews.registerGfeHeaderMissingCountView(); - ``` + > Note: Client-side metrics needs `monitoring.timeSeries.create` IAM permission to export metrics data. Ask your administrator to grant your service account the [Monitoring Metric Writer](https://cloud.google.com/iam/docs/roles-permissions/monitoring#monitoring.metricWriter) (roles/monitoring.metricWriter) IAM role on the project. ## Traces Cloud Spanner client supports OpenTelemetry Traces, which gives insight into the client internals and aids in debugging/troubleshooting production issues. By default, the functionality is disabled. You need to add OpenTelemetry dependencies, enable OpenTelemetry traces and must configure the OpenTelemetry with appropriate exporters at the startup of your application. + See [Configure client-side tracing](https://cloud.google.com/spanner/docs/set-up-tracing#configure-client-side-tracing) for more details on configuring traces. + #### OpenTelemetry Dependencies If you are using Maven, add this to your pom.xml file @@ -348,10 +161,33 @@ custom_content: | `SPANNER_ENABLE_API_TRACING=true`. > Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release. + + #### End-to-end Tracing + + In addition to client-side tracing, you can opt in for [end-to-end tracing](https://cloud.google.com/spanner/docs/tracing-overview#end-to-end-side-tracing). End-to-end tracing helps you understand and debug latency issues that are specific to Spanner such as the following: + * Identify whether the latency is due to network latency between your application and Spanner, or if the latency is occurring within Spanner. + * Identify the Google Cloud regions that your application requests are being routed through and if there is a cross-region request. A cross-region request usually means higher latencies between your application and Spanner. + + ``` + SpannerOptions options = SpannerOptions.newBuilder() + .setOpenTelemetry(openTelemetry) + .setEnableEndToEndTracing(true) + .build(); + ``` + + Refer to [Configure end-to-end tracing](https://cloud.google.com/spanner/docs/set-up-tracing#configure-end-to-end-tracing) to configure end-to-end tracing and to understand its attributes. + + > Note: End-to-end traces can only be exported to [Cloud Trace](https://cloud.google.com/trace/docs). + + + ## Instrument with OpenCensus + > Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/). + We recommend migrating to OpenTelemetry, the successor project. + ## Migrate from OpenCensus to OpenTelemetry - > Using the [OpenTelemetry OpenCensus Bridge](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-opencensus-shim), you can immediately begin exporting your metrics and traces with OpenTelemetry + > Using the [OpenTelemetry OpenCensus Bridge](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-opencensus-shim), you can immediately begin exporting your metrics and traces with OpenTelemetry. #### Disable OpenCensus metrics Disable OpenCensus metrics for Spanner by including the following code if you still possess OpenCensus dependencies and exporter. From c0b72a09a499f91eab2fc98472269882c76cfcc2 Mon Sep 17 00:00:00 2001 From: cloud-java-bot Date: Wed, 5 Nov 2025 13:56:54 +0000 Subject: [PATCH 2/2] chore: generate libraries at Wed Nov 5 13:54:14 UTC 2025 --- README.md | 230 ++++++++---------------------------------------------- 1 file changed, 33 insertions(+), 197 deletions(-) diff --git a/README.md b/README.md index ad16dd733b6..e1407bcd6ef 100644 --- a/README.md +++ b/README.md @@ -150,217 +150,30 @@ the Cloud Spanner Java client. ## Metrics -### Available client-side metrics: +Cloud Spanner client supports [client-side metrics](https://cloud.google.com/spanner/docs/view-manage-client-side-metrics) that you can use along with server-side metrics to optimize performance and troubleshoot performance issues if they occur. -* `spanner/max_in_use_sessions`: This returns the maximum - number of sessions that have been in use during the last maintenance window - interval, so as to provide an indication of the amount of activity currently - in the database. +Client-side metrics are measured from the time a request leaves your application to the time your application receives the response. +In contrast, server-side metrics are measured from the time Spanner receives a request until the last byte of data is sent to the client. -* `spanner/max_allowed_sessions`: This shows the maximum - number of sessions allowed. +These metrics are enabled by default. You can opt out of using client-side metrics with the following code: -* `spanner/num_sessions_in_pool`: This metric allows users to - see instance-level and database-level data for the total number of sessions in - the pool at this very moment. - -* `spanner/num_acquired_sessions`: This metric allows - users to see the total number of acquired sessions. - -* `spanner/num_released_sessions`: This metric allows - users to see the total number of released (destroyed) sessions. - -* `spanner/get_session_timeouts`: This gives you an - indication of the total number of get session timed-out instead of being - granted (the thread that requested the session is placed in a wait queue where - it waits until a session is released into the pool by another thread) due to - pool exhaustion since the server process started. - -* `spanner/gfe_latency`: This metric shows latency between - Google's network receiving an RPC and reading back the first byte of the response. - -* `spanner/gfe_header_missing_count`: This metric shows the - number of RPC responses received without the server-timing header, most likely - indicating that the RPC never reached Google's network. - -### Instrument with OpenTelemetry - -Cloud Spanner client supports [OpenTelemetry Metrics](https://opentelemetry.io/), -which gives insight into the client internals and aids in debugging/troubleshooting -production issues. OpenTelemetry metrics will provide you with enough data to enable you to -spot, and investigate the cause of any unusual deviations from normal behavior. - -All Cloud Spanner Metrics are prefixed with `spanner/` and uses `cloud.google.com/java` as [Instrumentation Scope](https://opentelemetry.io/docs/concepts/instrumentation-scope/). The -metrics will be tagged with: -* `database`: the target database name. -* `instance_id`: the instance id of the target Spanner instance. -* `client_id`: the user defined database client id. - -By default, the functionality is disabled. You need to add OpenTelemetry dependencies, enable OpenTelemetry metrics and must configure the OpenTelemetry with appropriate exporters at the startup of your application: - -#### OpenTelemetry Dependencies -If you are using Maven, add this to your pom.xml file -```xml - - io.opentelemetry - opentelemetry-sdk - {opentelemetry.version} - - - io.opentelemetry - opentelemetry-sdk-metrics - {opentelemetry.version} - - - io.opentelemetry - opentelemetry-exporter-otlp - {opentelemetry.version} - -``` -If you are using Gradle, add this to your dependencies -```Groovy -compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}' -compile 'io.opentelemetry:opentelemetry-sdk-metrics:{opentelemetry.version}' -compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}' ``` - -#### OpenTelemetry Configuration -By default, all metrics are disabled. To enable metrics and configure the OpenTelemetry follow below: - -```java -// Enable OpenTelemetry metrics before injecting OpenTelemetry object. -SpannerOptions.enableOpenTelemetryMetrics(); - -SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder() -// Use Otlp exporter or any other exporter of your choice. - .registerMetricReader(PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build()) - .build()) - .build(); - -OpenTelemetry openTelemetry = OpenTelemetrySdk.builder() - .setMeterProvider(sdkMeterProvider) - .build() - SpannerOptions options = SpannerOptions.newBuilder() -// Inject OpenTelemetry object via Spanner Options or register OpenTelemetry object as Global - .setOpenTelemetry(openTelemetry) + .setBuiltInMetricsEnabled(false) .build(); - -Spanner spanner = options.getService(); -``` - -#### OpenTelemetry SQL Statement Tracing -The OpenTelemetry traces that are generated by the Java client include any request and transaction -tags that have been set. The traces can also include the SQL statements that are executed and the -name of the thread that executes the statement. Enable this with the `enableExtendedTracing` -option: - -``` -SpannerOptions options = SpannerOptions.newBuilder() - .setOpenTelemetry(openTelemetry) - .setEnableExtendedTracing(true) - .build(); -``` - -This option can also be enabled by setting the environment variable -`SPANNER_ENABLE_EXTENDED_TRACING=true`. - -#### OpenTelemetry API Tracing -You can enable tracing of each API call that the Spanner client executes with the `enableApiTracing` -option. These traces also include any retry attempts for an API call: - -``` -SpannerOptions options = SpannerOptions.newBuilder() -.setOpenTelemetry(openTelemetry) -.setEnableApiTracing(true) -.build(); -``` - -This option can also be enabled by setting the environment variable -`SPANNER_ENABLE_API_TRACING=true`. - -> Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release. - - -### Instrument with OpenCensus - -> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/). -We recommend migrating to OpenTelemetry, the successor project. - -Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/), -which gives insight into the client internals and aids in debugging/troubleshooting -production issues. OpenCensus metrics will provide you with enough data to enable you to -spot, and investigate the cause of any unusual deviations from normal behavior. - -All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner` - -The metrics are tagged with: -* `database`: the target database name. -* `instance_id`: the instance id of the target Spanner instance. -* `client_id`: the user defined database client id. -* `library_version`: the version of the library that you're using. - - -By default, the functionality is disabled. You need to include opencensus-impl -dependency to collect the data and exporter dependency to export to backend. - -[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information. - -#### OpenCensus Dependencies - -If you are using Maven, add this to your pom.xml file -```xml - - io.opencensus - opencensus-impl - 0.30.0 - runtime - - - io.opencensus - opencensus-exporter-stats-stackdriver - 0.30.0 - -``` -If you are using Gradle, add this to your dependencies -```Groovy -compile 'io.opencensus:opencensus-impl:0.30.0' -compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0' -``` - -#### Configure the OpenCensus Exporter - -At the start of your application configure the exporter: - -```java -import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter; -// Enable OpenCensus exporters to export metrics to Stackdriver Monitoring. -// Exporters use Application Default Credentials to authenticate. -// See https://developers.google.com/identity/protocols/application-default-credentials -// for more details. -// The minimum reporting period for Stackdriver is 1 minute. -StackdriverStatsExporter.createAndRegister(); ``` -#### Enable RPC Views -By default, all session metrics are enabled. To enable RPC views, use either of the following method: +You can also disable these metrics by setting `SPANNER_DISABLE_BUILTIN_METRICS` to `true`. -```java -// Register views for GFE metrics, including gfe_latency and gfe_header_missing_count. -SpannerRpcViews.registerGfeLatencyAndHeaderMissingCountViews(); - -// Register GFE Latency view. -SpannerRpcViews.registerGfeLatencyView(); - -// Register GFE Header Missing Count view. -SpannerRpcViews.registerGfeHeaderMissingCountView(); -``` +> Note: Client-side metrics needs `monitoring.timeSeries.create` IAM permission to export metrics data. Ask your administrator to grant your service account the [Monitoring Metric Writer](https://cloud.google.com/iam/docs/roles-permissions/monitoring#monitoring.metricWriter) (roles/monitoring.metricWriter) IAM role on the project. ## Traces Cloud Spanner client supports OpenTelemetry Traces, which gives insight into the client internals and aids in debugging/troubleshooting production issues. By default, the functionality is disabled. You need to add OpenTelemetry dependencies, enable OpenTelemetry traces and must configure the OpenTelemetry with appropriate exporters at the startup of your application. +See [Configure client-side tracing](https://cloud.google.com/spanner/docs/set-up-tracing#configure-client-side-tracing) for more details on configuring traces. + #### OpenTelemetry Dependencies If you are using Maven, add this to your pom.xml file @@ -447,9 +260,32 @@ This option can also be enabled by setting the environment variable > Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release. +#### End-to-end Tracing + +In addition to client-side tracing, you can opt in for [end-to-end tracing](https://cloud.google.com/spanner/docs/tracing-overview#end-to-end-side-tracing). End-to-end tracing helps you understand and debug latency issues that are specific to Spanner such as the following: +* Identify whether the latency is due to network latency between your application and Spanner, or if the latency is occurring within Spanner. +* Identify the Google Cloud regions that your application requests are being routed through and if there is a cross-region request. A cross-region request usually means higher latencies between your application and Spanner. + +``` +SpannerOptions options = SpannerOptions.newBuilder() +.setOpenTelemetry(openTelemetry) +.setEnableEndToEndTracing(true) +.build(); +``` + +Refer to [Configure end-to-end tracing](https://cloud.google.com/spanner/docs/set-up-tracing#configure-end-to-end-tracing) to configure end-to-end tracing and to understand its attributes. + +> Note: End-to-end traces can only be exported to [Cloud Trace](https://cloud.google.com/trace/docs). + + +## Instrument with OpenCensus + +> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/). +We recommend migrating to OpenTelemetry, the successor project. + ## Migrate from OpenCensus to OpenTelemetry -> Using the [OpenTelemetry OpenCensus Bridge](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-opencensus-shim), you can immediately begin exporting your metrics and traces with OpenTelemetry +> Using the [OpenTelemetry OpenCensus Bridge](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-opencensus-shim), you can immediately begin exporting your metrics and traces with OpenTelemetry. #### Disable OpenCensus metrics Disable OpenCensus metrics for Spanner by including the following code if you still possess OpenCensus dependencies and exporter.