Skip to content

Commit c8632f5

Browse files
surbhigarg92gcf-owl-bot[bot]
surbhigarg92
and
gcf-owl-bot[bot]
authored
docs: README for OpenTelemetry metrics and traces (#2880)
* 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>
1 parent 9282ed6 commit c8632f5

File tree

2 files changed

+412
-56
lines changed

2 files changed

+412
-56
lines changed

‎.readme-partials.yaml

Lines changed: 206 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -50,55 +50,133 @@ custom_content: |
5050
for in-depth background information about sessions and gRPC channels and how these are handled in
5151
the Cloud Spanner Java client.
5252
53-
## OpenCensus Metrics
53+
## Metrics
5454
55-
Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/),
56-
which gives insight into the client internals and aids in debugging/troubleshooting
57-
production issues. OpenCensus metrics will provide you with enough data to enable you to
58-
spot, and investigate the cause of any unusual deviations from normal behavior.
59-
60-
All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner/`. The
61-
metrics will be tagged with:
62-
* `database`: the target database name.
63-
* `instance_id`: the instance id of the target Spanner instance.
64-
* `client_id`: the user defined database client id.
65-
* `library_version`: the version of the library that you're using.
66-
67-
> Note: RPC level metrics can be gleaned from gRPC’s metrics, which are prefixed
68-
with `grpc.io/client/`.
6955
### Available client-side metrics:
7056
71-
* `cloud.google.com/java/spanner/max_in_use_sessions`: This returns the maximum
57+
* `spanner/max_in_use_sessions`: This returns the maximum
7258
number of sessions that have been in use during the last maintenance window
7359
interval, so as to provide an indication of the amount of activity currently
7460
in the database.
7561
76-
* `cloud.google.com/java/spanner/max_allowed_sessions`: This shows the maximum
62+
* `spanner/max_allowed_sessions`: This shows the maximum
7763
number of sessions allowed.
7864
79-
* `cloud.google.com/java/spanner/num_sessions_in_pool`: This metric allows users to
80-
see instance-level and database-level data for the total number of sessions in
81-
the pool at this very moment.
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.
8268
83-
* `cloud.google.com/java/spanner/num_acquired_sessions`: This metric allows
69+
* `spanner/num_acquired_sessions`: This metric allows
8470
users to see the total number of acquired sessions.
8571
86-
* `cloud.google.com/java/spanner/num_released_sessions`: This metric allows
72+
* `spanner/num_released_sessions`: This metric allows
8773
users to see the total number of released (destroyed) sessions.
8874
89-
* `cloud.google.com/java/spanner/get_session_timeouts`: This gives you an
75+
* `spanner/get_session_timeouts`: This gives you an
9076
indication of the total number of get session timed-out instead of being
9177
granted (the thread that requested the session is placed in a wait queue where
9278
it waits until a session is released into the pool by another thread) due to
9379
pool exhaustion since the server process started.
9480
95-
* `cloud.google.com/java/spanner/gfe_latency`: This metric shows latency between
81+
* `spanner/gfe_latency`: This metric shows latency between
9682
Google's network receiving an RPC and reading back the first byte of the response.
9783
98-
* `cloud.google.com/java/spanner/gfe_header_missing_count`: This metric shows the
84+
* `spanner/gfe_header_missing_count`: This metric shows the
9985
number of RPC responses received without the server-timing header, most likely
10086
indicating that the RPC never reached Google's network.
10187
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 OpenTelmetry object as Global
148+
.setOpenTelemetry(openTelemetry)
149+
.build();
150+
151+
Spanner spanner = options.getService();
152+
```
153+
154+
### Instrument with OpenCensus
155+
156+
> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).
157+
We recommend migrating to OpenTelemetry, the successor project.
158+
159+
Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/),
160+
which gives insight into the client internals and aids in debugging/troubleshooting
161+
production issues. OpenCensus metrics will provide you with enough data to enable you to
162+
spot, and investigate the cause of any unusual deviations from normal behavior.
163+
164+
All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner`
165+
166+
The metrics are tagged with:
167+
* `database`: the target database name.
168+
* `instance_id`: the instance id of the target Spanner instance.
169+
* `client_id`: the user defined database client id.
170+
* `library_version`: the version of the library that you're using.
171+
172+
173+
By default, the functionality is disabled. You need to include opencensus-impl
174+
dependency to collect the data and exporter dependency to export to backend.
175+
176+
[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
177+
178+
#### OpenCensus Dependencies
179+
102180
If you are using Maven, add this to your pom.xml file
103181
```xml
104182
<dependency>
@@ -119,6 +197,8 @@ custom_content: |
119197
compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0'
120198
```
121199
200+
#### Configure the OpenCensus Exporter
201+
122202
At the start of your application configure the exporter:
123203
124204
```java
@@ -130,9 +210,107 @@ custom_content: |
130210
// The minimum reporting period for Stackdriver is 1 minute.
131211
StackdriverStatsExporter.createAndRegister();
132212
```
213+
#### Enable RPC Views
133214
134-
By default, the functionality is disabled. You need to include opencensus-impl
135-
dependency to collect the data and exporter dependency to export to backend.
215+
By default, all session metrics are enabled. To enable RPC views, use either of the following method:
136216
137-
[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
217+
```java
218+
// Register views for GFE metrics, including gfe_latency and gfe_header_missing_count.
219+
SpannerRpcViews.registerGfeLatencyAndHeaderMissingCountViews();
220+
221+
// Register GFE Latency view.
222+
SpannerRpcViews.registerGfeLatencyView();
223+
224+
// Register GFE Header Missing Count view.
225+
SpannerRpcViews.registerGfeHeaderMissingCountView();
226+
```
227+
228+
## Traces
229+
Cloud Spanner client supports OpenTelemetry Traces, which gives insight into the client internals and aids in debugging/troubleshooting production issues.
230+
231+
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.
232+
233+
#### OpenTelemetry Dependencies
234+
235+
If you are using Maven, add this to your pom.xml file
236+
```xml
237+
<dependency>
238+
<groupId>io.opentelemetry</groupId>
239+
<artifactId>opentelemetry-sdk</artifactId>
240+
<version>{opentelemetry.version}</version>
241+
</dependency>
242+
<dependency>
243+
<groupId>io.opentelemetry</groupId>
244+
<artifactId>opentelemetry-sdk-trace</artifactId>
245+
<version>{opentelemetry.version}</version>
246+
</dependency>
247+
<dependency>
248+
<groupId>io.opentelemetry</groupId>
249+
<artifactId>opentelemetry-exporter-otlp</artifactId>
250+
<version>{opentelemetry.version}</version>
251+
</dependency>
252+
```
253+
If you are using Gradle, add this to your dependencies
254+
```Groovy
255+
compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}'
256+
compile 'io.opentelemetry:opentelemetry-sdk-trace:{opentelemetry.version}'
257+
compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}'
258+
```
259+
#### OpenTelemetry Configuration
260+
261+
> Note: Enabling OpenTelemetry traces will automatically disable OpenCensus traces.
262+
263+
```java
264+
// Enable OpenTelemetry traces
265+
SpannerOptions.enableOpenTelemetryTraces();
266+
267+
// Create a new tracer provider
268+
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
269+
// Use Otlp exporter or any other exporter of your choice.
270+
.addSpanProcessor(SimpleSpanProcessor.builder(OtlpGrpcSpanExporter
271+
.builder().build()).build())
272+
.build();
273+
274+
275+
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
276+
.setTracerProvider(sdkTracerProvider)
277+
.build()
278+
279+
SpannerOptions options = SpannerOptions.newBuilder()
280+
// Inject OpenTelemetry object via Spanner Options or register OpenTelmetry object as Global
281+
.setOpenTelemetry(openTelemetry)
282+
.build();
283+
284+
Spanner spanner = options.getService();
285+
```
286+
287+
## Migrate from OpenCensus to OpenTelemetry
288+
289+
> 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
290+
291+
#### Disable OpenCensus metrics
292+
Disable OpenCensus metrics for Spanner by including the following code if you still possess OpenCensus dependencies and exporter.
293+
294+
```java
295+
SpannerOptions.disableOpenCensusMetrics();
296+
```
297+
298+
#### Disable OpenCensus traces
299+
Enabling OpenTelemetry traces for Spanner will automatically disable OpenCensus traces.
300+
301+
```java
302+
SpannerOptions.enableOpenTelemetryTraces();
303+
```
304+
305+
#### Remove OpenCensus Dependencies and Code
306+
Remove any OpenCensus-related code and dependencies from your codebase if all your dependencies are ready to move to OpenTelemetry.
307+
308+
* Remove the OpenCensus Exporters which were configured [here](#configure-the-opencensus-exporter)
309+
* Remove SpannerRPCViews reference which were configured [here](#enable-rpc-views)
310+
* Remove the OpenCensus dependencies which were added [here](#opencensus-dependencies)
311+
312+
#### Update your Dashboards and Alerts
138313
314+
Update your dashboards and alerts to reflect below changes
315+
* **Metrics name** : `cloud.google.com/java` prefix has been removed from OpenTelemery metrics and instead has been added as Instrumenation Scope.
316+
* **Metrics namespace** : OpenTelmetry exporters uses `workload.googleapis.com` namespace opposed to `custom.googleapis.com` with OpenCensus.

0 commit comments

Comments
 (0)