Skip to content

Commit

Permalink
docs: README for OpenTelemetry metrics and traces (#2880)
Browse files Browse the repository at this point in the history 
* docs: README for OpenTelemetry metrics and traces

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
  • Loading branch information
@surbhigarg92 @gcf-owl-bot
surbhigarg92 and gcf-owl-bot[bot] committed Feb 15, 2024
1 parent 9282ed6 commit c8632f5
Show file tree
Hide file tree
Showing 2 changed files with 412 additions and 56 deletions.
234 changes: 206 additions & 28 deletions .readme-partials.yaml
View file
Expand Up @@ -50,55 +50,133 @@ custom_content: |
for in-depth background information about sessions and gRPC channels and how these are handled in
the Cloud Spanner Java client.
## OpenCensus Metrics
## Metrics
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 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.
* `library_version`: the version of the library that you're using.
> Note: RPC level metrics can be gleaned from gRPC’s metrics, which are prefixed
with `grpc.io/client/`.
### Available client-side metrics:
* `cloud.google.com/java/spanner/max_in_use_sessions`: This returns the maximum
* `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.
* `cloud.google.com/java/spanner/max_allowed_sessions`: This shows the maximum
* `spanner/max_allowed_sessions`: This shows the maximum
number of sessions allowed.
* `cloud.google.com/java/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_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.
* `cloud.google.com/java/spanner/num_acquired_sessions`: This metric allows
* `spanner/num_acquired_sessions`: This metric allows
users to see the total number of acquired sessions.
* `cloud.google.com/java/spanner/num_released_sessions`: This metric allows
* `spanner/num_released_sessions`: This metric allows
users to see the total number of released (destroyed) sessions.
* `cloud.google.com/java/spanner/get_session_timeouts`: This gives you an
* `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.
* `cloud.google.com/java/spanner/gfe_latency`: This metric shows latency between
* `spanner/gfe_latency`: This metric shows latency between
Google's network receiving an RPC and reading back the first byte of the response.
* `cloud.google.com/java/spanner/gfe_header_missing_count`: This metric shows the
* `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
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
<version>{opentelemetry.version}</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-metrics</artifactId>
<version>{opentelemetry.version}</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
<version>{opentelemetry.version}</version>
</dependency>
```
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 OpenTelmetry object as Global
.setOpenTelemetry(openTelemetry)
.build();
Spanner spanner = options.getService();
```
### 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
<dependency>
Expand All @@ -119,6 +197,8 @@ custom_content: |
compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0'
```
#### Configure the OpenCensus Exporter
At the start of your application configure the exporter:
```java
Expand All @@ -130,9 +210,107 @@ custom_content: |
// The minimum reporting period for Stackdriver is 1 minute.
StackdriverStatsExporter.createAndRegister();
```
#### Enable RPC Views
By default, the functionality is disabled. You need to include opencensus-impl
dependency to collect the data and exporter dependency to export to backend.
By default, all session metrics are enabled. To enable RPC views, use either of the following method:
[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
```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();
```
## 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.
#### OpenTelemetry Dependencies
If you are using Maven, add this to your pom.xml file
```xml
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
<version>{opentelemetry.version}</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
<version>{opentelemetry.version}</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
<version>{opentelemetry.version}</version>
</dependency>
```
If you are using Gradle, add this to your dependencies
```Groovy
compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}'
compile 'io.opentelemetry:opentelemetry-sdk-trace:{opentelemetry.version}'
compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}'
```
#### OpenTelemetry Configuration
> Note: Enabling OpenTelemetry traces will automatically disable OpenCensus traces.
```java
// Enable OpenTelemetry traces
SpannerOptions.enableOpenTelemetryTraces();
// Create a new tracer provider
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
// Use Otlp exporter or any other exporter of your choice.
.addSpanProcessor(SimpleSpanProcessor.builder(OtlpGrpcSpanExporter
.builder().build()).build())
.build();
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.build()
SpannerOptions options = SpannerOptions.newBuilder()
// Inject OpenTelemetry object via Spanner Options or register OpenTelmetry object as Global
.setOpenTelemetry(openTelemetry)
.build();
Spanner spanner = options.getService();
```
## 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
#### Disable OpenCensus metrics
Disable OpenCensus metrics for Spanner by including the following code if you still possess OpenCensus dependencies and exporter.
```java
SpannerOptions.disableOpenCensusMetrics();
```
#### Disable OpenCensus traces
Enabling OpenTelemetry traces for Spanner will automatically disable OpenCensus traces.
```java
SpannerOptions.enableOpenTelemetryTraces();
```
#### Remove OpenCensus Dependencies and Code
Remove any OpenCensus-related code and dependencies from your codebase if all your dependencies are ready to move to OpenTelemetry.
* Remove the OpenCensus Exporters which were configured [here](#configure-the-opencensus-exporter)
* Remove SpannerRPCViews reference which were configured [here](#enable-rpc-views)
* Remove the OpenCensus dependencies which were added [here](#opencensus-dependencies)
#### Update your Dashboards and Alerts
Update your dashboards and alerts to reflect below changes
* **Metrics name** : `cloud.google.com/java` prefix has been removed from OpenTelemery metrics and instead has been added as Instrumenation Scope.
* **Metrics namespace** : OpenTelmetry exporters uses `workload.googleapis.com` namespace opposed to `custom.googleapis.com` with OpenCensus.

0 comments on commit c8632f5

Please sign in to comment.