Skip to content

Commit 2e18d1e

Browse files
surbhigarg92surbhigarg92
committed
chore: update metrics and traces documentation
1 parent 9cdba74 commit 2e18d1e

File tree

1 file changed

+34
-198
lines changed

1 file changed

+34
-198
lines changed

‎.readme-partials.yaml‎

Lines changed: 34 additions & 198 deletions
Original file line numberDiff line numberDiff line change
@@ -52,217 +52,30 @@ custom_content: |
5252
5353
## Metrics
5454
55-
### Available client-side metrics:
56-
57-
* `spanner/max_in_use_sessions`: This returns the maximum
58-
number of sessions that have been in use during the last maintenance window
59-
interval, so as to provide an indication of the amount of activity currently
60-
in the database.
61-
62-
* `spanner/max_allowed_sessions`: This shows the maximum
63-
number of sessions allowed.
64-
65-
* `spanner/num_sessions_in_pool`: This metric allows users to
66-
see instance-level and database-level data for the total number of sessions in
67-
the pool at this very moment.
68-
69-
* `spanner/num_acquired_sessions`: This metric allows
70-
users to see the total number of acquired sessions.
71-
72-
* `spanner/num_released_sessions`: This metric allows
73-
users to see the total number of released (destroyed) sessions.
74-
75-
* `spanner/get_session_timeouts`: This gives you an
76-
indication of the total number of get session timed-out instead of being
77-
granted (the thread that requested the session is placed in a wait queue where
78-
it waits until a session is released into the pool by another thread) due to
79-
pool exhaustion since the server process started.
80-
81-
* `spanner/gfe_latency`: This metric shows latency between
82-
Google's network receiving an RPC and reading back the first byte of the response.
83-
84-
* `spanner/gfe_header_missing_count`: This metric shows the
85-
number of RPC responses received without the server-timing header, most likely
86-
indicating that the RPC never reached Google's network.
87-
88-
### Instrument with OpenTelemetry
89-
90-
Cloud Spanner client supports [OpenTelemetry Metrics](https://opentelemetry.io/),
91-
which gives insight into the client internals and aids in debugging/troubleshooting
92-
production issues. OpenTelemetry metrics will provide you with enough data to enable you to
93-
spot, and investigate the cause of any unusual deviations from normal behavior.
94-
95-
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
96-
metrics will be tagged with:
97-
* `database`: the target database name.
98-
* `instance_id`: the instance id of the target Spanner instance.
99-
* `client_id`: the user defined database client id.
100-
101-
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:
102-
103-
#### OpenTelemetry Dependencies
104-
If you are using Maven, add this to your pom.xml file
105-
```xml
106-
<dependency>
107-
<groupId>io.opentelemetry</groupId>
108-
<artifactId>opentelemetry-sdk</artifactId>
109-
<version>{opentelemetry.version}</version>
110-
</dependency>
111-
<dependency>
112-
<groupId>io.opentelemetry</groupId>
113-
<artifactId>opentelemetry-sdk-metrics</artifactId>
114-
<version>{opentelemetry.version}</version>
115-
</dependency>
116-
<dependency>
117-
<groupId>io.opentelemetry</groupId>
118-
<artifactId>opentelemetry-exporter-otlp</artifactId>
119-
<version>{opentelemetry.version}</version>
120-
</dependency>
121-
```
122-
If you are using Gradle, add this to your dependencies
123-
```Groovy
124-
compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}'
125-
compile 'io.opentelemetry:opentelemetry-sdk-metrics:{opentelemetry.version}'
126-
compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}'
127-
```
128-
129-
#### OpenTelemetry Configuration
130-
By default, all metrics are disabled. To enable metrics and configure the OpenTelemetry follow below:
131-
132-
```java
133-
// Enable OpenTelemetry metrics before injecting OpenTelemetry object.
134-
SpannerOptions.enableOpenTelemetryMetrics();
135-
136-
SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
137-
// Use Otlp exporter or any other exporter of your choice.
138-
.registerMetricReader(PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build())
139-
.build())
140-
.build();
141-
142-
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
143-
.setMeterProvider(sdkMeterProvider)
144-
.build()
145-
146-
SpannerOptions options = SpannerOptions.newBuilder()
147-
// Inject OpenTelemetry object via Spanner Options or register OpenTelemetry object as Global
148-
.setOpenTelemetry(openTelemetry)
149-
.build();
150-
151-
Spanner spanner = options.getService();
152-
```
55+
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.
15356
154-
#### OpenTelemetry SQL Statement Tracing
155-
The OpenTelemetry traces that are generated by the Java client include any request and transaction
156-
tags that have been set. The traces can also include the SQL statements that are executed and the
157-
name of the thread that executes the statement. Enable this with the `enableExtendedTracing`
158-
option:
57+
Client-side metrics are measured from the time a request leaves your application to the time your application receives the response.
58+
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.
59+
60+
These metrics are enabled by default. You can opt out of using client-side metrics with the following code:
15961
16062
```
16163
SpannerOptions options = SpannerOptions.newBuilder()
162-
.setOpenTelemetry(openTelemetry)
163-
.setEnableExtendedTracing(true)
64+
.setBuiltInMetricsEnabled(false)
16465
.build();
16566
```
16667
167-
This option can also be enabled by setting the environment variable
168-
`SPANNER_ENABLE_EXTENDED_TRACING=true`.
169-
170-
#### OpenTelemetry API Tracing
171-
You can enable tracing of each API call that the Spanner client executes with the `enableApiTracing`
172-
option. These traces also include any retry attempts for an API call:
173-
174-
```
175-
SpannerOptions options = SpannerOptions.newBuilder()
176-
.setOpenTelemetry(openTelemetry)
177-
.setEnableApiTracing(true)
178-
.build();
179-
```
180-
181-
This option can also be enabled by setting the environment variable
182-
`SPANNER_ENABLE_API_TRACING=true`.
68+
You can also disable these metrics by setting `SPANNER_DISABLE_BUILTIN_METRICS` to `true`.
18369
184-
> Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release.
185-
186-
187-
### Instrument with OpenCensus
188-
189-
> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).
190-
We recommend migrating to OpenTelemetry, the successor project.
191-
192-
Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/),
193-
which gives insight into the client internals and aids in debugging/troubleshooting
194-
production issues. OpenCensus metrics will provide you with enough data to enable you to
195-
spot, and investigate the cause of any unusual deviations from normal behavior.
196-
197-
All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner`
198-
199-
The metrics are tagged with:
200-
* `database`: the target database name.
201-
* `instance_id`: the instance id of the target Spanner instance.
202-
* `client_id`: the user defined database client id.
203-
* `library_version`: the version of the library that you're using.
204-
205-
206-
By default, the functionality is disabled. You need to include opencensus-impl
207-
dependency to collect the data and exporter dependency to export to backend.
208-
209-
[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
210-
211-
#### OpenCensus Dependencies
212-
213-
If you are using Maven, add this to your pom.xml file
214-
```xml
215-
<dependency>
216-
<groupId>io.opencensus</groupId>
217-
<artifactId>opencensus-impl</artifactId>
218-
<version>0.30.0</version>
219-
<scope>runtime</scope>
220-
</dependency>
221-
<dependency>
222-
<groupId>io.opencensus</groupId>
223-
<artifactId>opencensus-exporter-stats-stackdriver</artifactId>
224-
<version>0.30.0</version>
225-
</dependency>
226-
```
227-
If you are using Gradle, add this to your dependencies
228-
```Groovy
229-
compile 'io.opencensus:opencensus-impl:0.30.0'
230-
compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0'
231-
```
232-
233-
#### Configure the OpenCensus Exporter
234-
235-
At the start of your application configure the exporter:
236-
237-
```java
238-
import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter;
239-
// Enable OpenCensus exporters to export metrics to Stackdriver Monitoring.
240-
// Exporters use Application Default Credentials to authenticate.
241-
// See https://developers.google.com/identity/protocols/application-default-credentials
242-
// for more details.
243-
// The minimum reporting period for Stackdriver is 1 minute.
244-
StackdriverStatsExporter.createAndRegister();
245-
```
246-
#### Enable RPC Views
247-
248-
By default, all session metrics are enabled. To enable RPC views, use either of the following method:
249-
250-
```java
251-
// Register views for GFE metrics, including gfe_latency and gfe_header_missing_count.
252-
SpannerRpcViews.registerGfeLatencyAndHeaderMissingCountViews();
253-
254-
// Register GFE Latency view.
255-
SpannerRpcViews.registerGfeLatencyView();
256-
257-
// Register GFE Header Missing Count view.
258-
SpannerRpcViews.registerGfeHeaderMissingCountView();
259-
```
70+
> 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.
26071
26172
## Traces
26273
Cloud Spanner client supports OpenTelemetry Traces, which gives insight into the client internals and aids in debugging/troubleshooting production issues.
26374
26475
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.
26576
77+
See [Configure client-side tracing](https://cloud.google.com/spanner/docs/set-up-tracing#configure-client-side-tracing) for more details on configuring traces.
78+
26679
#### OpenTelemetry Dependencies
26780
26881
If you are using Maven, add this to your pom.xml file
@@ -348,10 +161,33 @@ custom_content: |
348161
`SPANNER_ENABLE_API_TRACING=true`.
349162
350163
> Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release.
164+
165+
#### End-to-end Tracing
166+
167+
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:
168+
* Identify whether the latency is due to network latency between your application and Spanner, or if the latency is occurring within Spanner.
169+
* 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.
170+
171+
```
172+
SpannerOptions options = SpannerOptions.newBuilder()
173+
.setOpenTelemetry(openTelemetry)
174+
.setEnableEndToEndTracing(true)
175+
.build();
176+
```
177+
178+
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.
179+
180+
> Note: End-to-end traces can only be exported to [Cloud Trace](https://cloud.google.com/trace/docs).
181+
182+
183+
## Instrument with OpenCensus
351184
185+
> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).
186+
We recommend migrating to OpenTelemetry, the successor project.
187+
352188
## Migrate from OpenCensus to OpenTelemetry
353189
354-
> 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
190+
> 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.
355191
356192
#### Disable OpenCensus metrics
357193
Disable OpenCensus metrics for Spanner by including the following code if you still possess OpenCensus dependencies and exporter.

0 commit comments

Comments
 (0)