Skip to content

Commit a8a6ffd

Browse files
surbhigarg92surbhigarg92
committed
chore: OpenTelemetry documentation
1 parent e2b7ae6 commit a8a6ffd

File tree

1 file changed

+193
-23
lines changed

1 file changed

+193
-23
lines changed

‎README.md

+193-23
Original file line numberDiff line numberDiff line change
@@ -156,55 +156,129 @@ See [Session Pool and Channel Pool Configuration](session-and-channel-pool-confi
156156
for in-depth background information about sessions and gRPC channels and how these are handled in
157157
the Cloud Spanner Java client.
158158

159-
## OpenCensus Metrics
159+
## Metrics
160160

161-
Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/),
161+
Cloud Spanner client supports [OpenTelemetry Metrics](https://opentelemetry.io/),
162162
which gives insight into the client internals and aids in debugging/troubleshooting
163-
production issues. OpenCensus metrics will provide you with enough data to enable you to
163+
production issues. OpenTelemetry metrics will provide you with enough data to enable you to
164164
spot, and investigate the cause of any unusual deviations from normal behavior.
165165

166-
All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner/`. The
167-
metrics will be tagged with:
168-
* `database`: the target database name.
169-
* `instance_id`: the instance id of the target Spanner instance.
170-
* `client_id`: the user defined database client id.
171-
* `library_version`: the version of the library that you're using.
172-
173-
> Note: RPC level metrics can be gleaned from gRPC’s metrics, which are prefixed
174-
with `grpc.io/client/`.
175166
### Available client-side metrics:
176167

177-
* `cloud.google.com/java/spanner/max_in_use_sessions`: This returns the maximum
168+
* `spanner/max_in_use_sessions`: This returns the maximum
178169
number of sessions that have been in use during the last maintenance window
179170
interval, so as to provide an indication of the amount of activity currently
180171
in the database.
181172

182-
* `cloud.google.com/java/spanner/max_allowed_sessions`: This shows the maximum
173+
* `spanner/max_allowed_sessions`: This shows the maximum
183174
number of sessions allowed.
184175

185-
* `cloud.google.com/java/spanner/num_sessions_in_pool`: This metric allows users to
176+
* `spanner/num_sessions_in_pool`: This metric allows users to
186177
see instance-level and database-level data for the total number of sessions in
187178
the pool at this very moment.
188179

189-
* `cloud.google.com/java/spanner/num_acquired_sessions`: This metric allows
180+
* `spanner/num_acquired_sessions`: This metric allows
190181
users to see the total number of acquired sessions.
191182

192-
* `cloud.google.com/java/spanner/num_released_sessions`: This metric allows
183+
* `spanner/num_released_sessions`: This metric allows
193184
users to see the total number of released (destroyed) sessions.
194185

195-
* `cloud.google.com/java/spanner/get_session_timeouts`: This gives you an
186+
* `spanner/get_session_timeouts`: This gives you an
196187
indication of the total number of get session timed-out instead of being
197188
granted (the thread that requested the session is placed in a wait queue where
198189
it waits until a session is released into the pool by another thread) due to
199190
pool exhaustion since the server process started.
200191

201-
* `cloud.google.com/java/spanner/gfe_latency`: This metric shows latency between
192+
* `spanner/gfe_latency`: This metric shows latency between
202193
Google's network receiving an RPC and reading back the first byte of the response.
203194

204-
* `cloud.google.com/java/spanner/gfe_header_missing_count`: This metric shows the
195+
* `spanner/gfe_header_missing_count`: This metric shows the
205196
number of RPC responses received without the server-timing header, most likely
206197
indicating that the RPC never reached Google's network.
207198

199+
If you are using Maven, add this to your pom.xml file
200+
```xml
201+
<dependency>
202+
<groupId>io.opentelemetry</groupId>
203+
<artifactId>opentelemetry-sdk</artifactId>
204+
<version>{opentelemetry.version}</version>
205+
</dependency>
206+
<dependency>
207+
<groupId>io.opentelemetry</groupId>
208+
<artifactId>opentelemetry-sdk-metrics</artifactId>
209+
<version>{opentelemetry.version}</version>
210+
</dependency>
211+
<dependency>
212+
<groupId>io.opentelemetry</groupId>
213+
<artifactId>opentelemetry-exporter-otlp</artifactId>
214+
<version>{opentelemetry.version}</version>
215+
</dependency>
216+
```
217+
If you are using Gradle, add this to your dependencies
218+
```Groovy
219+
compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}'
220+
compile 'io.opentelemetry:opentelemetry-sdk-metrics:{opentelemetry.version}'
221+
compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}'
222+
```
223+
224+
By default, the functionality is disabled. You need to enable OpenTelemetry metrics and must configure the OpenTelemetry with appropriate exporters at the startup of your application:
225+
226+
```java
227+
228+
// Enable OpenTelemetry metrics
229+
SpannerOptions.enableOpenTelemetryMetrics();
230+
231+
SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
232+
// Use Otlp exporter or any other exporter of your choice.
233+
.registerMetricReader(PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build())
234+
.build())
235+
.build();
236+
237+
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
238+
.setMeterProvider(sdkMeterProvider)
239+
.build()
240+
241+
SpannerOptions options = SpannerOptions.newBuilder()
242+
// Inject OpenTelemetry object via Spanner Options or register OpenTelmetry object as Global
243+
.setOpenTelemetry(openTelemetry)
244+
.build();
245+
246+
Spanner spanner = options.getService();
247+
```
248+
249+
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
250+
metrics will be tagged with:
251+
* `database`: the target database name.
252+
* `instance_id`: the instance id of the target Spanner instance.
253+
* `client_id`: the user defined database client id.
254+
255+
256+
### Instrument with OpenCensus
257+
258+
> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).
259+
We recommend migrating to OpenTelemetry, the successor project.
260+
261+
Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/),
262+
which gives insight into the client internals and aids in debugging/troubleshooting
263+
production issues. OpenCensus metrics will provide you with enough data to enable you to
264+
spot, and investigate the cause of any unusual deviations from normal behavior.
265+
266+
All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner`
267+
268+
The metrics are tagged with:
269+
* `database`: the target database name.
270+
* `instance_id`: the instance id of the target Spanner instance.
271+
* `client_id`: the user defined database client id.
272+
* `library_version`: the version of the library that you're using.
273+
274+
275+
By default, the functionality is disabled. You need to include opencensus-impl
276+
dependency to collect the data and exporter dependency to export to backend.
277+
278+
[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
279+
280+
#### OpenCensus Dependencies
281+
208282
If you are using Maven, add this to your pom.xml file
209283
```xml
210284
<dependency>
@@ -225,6 +299,8 @@ compile 'io.opencensus:opencensus-impl:0.30.0'
225299
compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0'
226300
```
227301

302+
#### Configure the OpenCensus Exporter
303+
228304
At the start of your application configure the exporter:
229305

230306
```java
@@ -236,13 +312,107 @@ import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter;
236312
// The minimum reporting period for Stackdriver is 1 minute.
237313
StackdriverStatsExporter.createAndRegister();
238314
```
315+
#### Enable RPC Views
239316

240-
By default, the functionality is disabled. You need to include opencensus-impl
241-
dependency to collect the data and exporter dependency to export to backend.
317+
By default, all session metrics are enabled. To enable RPC views, use either of the following method:
242318

243-
[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
319+
```java
320+
// Register views for GFE metrics, including gfe_latency and gfe_header_missing_count.
321+
SpannerRpcViews.registerGfeLatencyAndHeaderMissingCountViews();
322+
323+
// Register GFE Latency view.
324+
SpannerRpcViews.registerGfeLatencyView();
325+
326+
// Register GFE Header Missing Count view.
327+
SpannerRpcViews.registerGfeHeaderMissingCountView();
328+
```
329+
330+
## Traces
331+
Cloud Spanner client supports OpenTelemetry Traces, which gives insight into the client internals and aids in debugging/troubleshooting production issues.
332+
333+
If you are using Maven, add this to your pom.xml file
334+
```xml
335+
<dependency>
336+
<groupId>io.opentelemetry</groupId>
337+
<artifactId>opentelemetry-sdk</artifactId>
338+
<version>{opentelemetry.version}</version>
339+
</dependency>
340+
<dependency>
341+
<groupId>io.opentelemetry</groupId>
342+
<artifactId>opentelemetry-sdk-trace</artifactId>
343+
<version>{opentelemetry.version}</version>
344+
</dependency>
345+
<dependency>
346+
<groupId>io.opentelemetry</groupId>
347+
<artifactId>opentelemetry-exporter-otlp</artifactId>
348+
<version>{opentelemetry.version}</version>
349+
</dependency>
350+
```
351+
If you are using Gradle, add this to your dependencies
352+
```Groovy
353+
compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}'
354+
compile 'io.opentelemetry:opentelemetry-sdk-trace:{opentelemetry.version}'
355+
compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}'
356+
```
357+
358+
By default, the functionality is disabled. You need to enable OpenTelemetry traces and must configure the OpenTelemetry with appropriate exporters at the startup of your application.
359+
360+
> Note: Enabling OpenTelemetry traces will automatically disable OpenCensus traces.
361+
362+
```java
363+
// Enable OpenTelemetry traces
364+
SpannerOptions.enableOpenTelemetryTraces();
365+
366+
// Create a new tracer provider
367+
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
368+
// Use Otlp exporter or any other exporter of your choice.
369+
.addSpanProcessor(SimpleSpanProcessor.builder(OtlpGrpcSpanExporter
370+
.builder().build()).build())
371+
.build();
372+
373+
374+
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
375+
.setTracerProvider(sdkTracerProvider)
376+
.build()
377+
378+
SpannerOptions options = SpannerOptions.newBuilder()
379+
// Inject OpenTelemetry object via Spanner Options or register OpenTelmetry object as Global
380+
.setOpenTelemetry(openTelemetry)
381+
.build();
382+
383+
Spanner spanner = options.getService();
384+
```
385+
386+
## Migrate from OpenCensus to OpenTelemetry
387+
388+
> 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
389+
390+
#### Disable OpenCensus metrics
391+
Disable OpenCensus metrics for Spanner by including the following code if you still possess OpenCensus dependencies and exporter.
392+
393+
```java
394+
SpannerOptions.disableOpenCensusMetrics();
395+
```
396+
397+
#### Disable OpenCensus traces
398+
Enabling OpenTelemetry traces for Spanner will automatically disable OpenCensus traces.
399+
400+
```java
401+
SpannerOptions.enableOpenTelemetryTraces();
402+
```
403+
404+
#### Remove OpenCensus Dependencies and Code
405+
Remove any OpenCensus-related code and dependencies from your codebase if all your dependencies are ready to move to OpenTelemetry.
406+
407+
* Remove the OpenCensus Exporters which were configured [here](#configure-the-opencensus-exporter)
408+
* Remove SpannerRPCViews reference which were configured [here](#enable-rpc-views)
409+
* Remove the OpenCensus dependencies which were added [here](#opencensus-dependencies)
244410

411+
#### Update your Dashboards and Alerts
245412

413+
Update your dashboards and alerts to reflect below changes
414+
* **Metrics name** : `cloud.google.com/java` prefix has been removed from OpenTelemery metrics and instead has been added as Instrumenation Scope.
415+
* **Metrics namespace** : OpenTelmetry exporters uses `workload.googleapis.com` namespace opposed to `custom.googleapis.com` with OpenCensus.
246416

247417

248418
## Samples

0 commit comments

Comments
 (0)