Skip to content

Commit 6db9287

Browse files
cloud-java-botcloud-java-bot
committed
chore: generate libraries at Wed Nov 5 13:46:39 UTC 2025
1 parent f6cc78d commit 6db9287

File tree

1 file changed

+32
-196
lines changed

1 file changed

+32
-196
lines changed

‎README.md‎

Lines changed: 32 additions & 196 deletions
Original file line numberDiff line numberDiff line change
@@ -150,217 +150,30 @@ the Cloud Spanner Java client.
150150

151151
## Metrics
152152

153-
### Available client-side metrics:
153+
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.
154154

155-
* `spanner/max_in_use_sessions`: This returns the maximum
156-
number of sessions that have been in use during the last maintenance window
157-
interval, so as to provide an indication of the amount of activity currently
158-
in the database.
155+
Client-side metrics are measured from the time a request leaves your application to the time your application receives the response.
156+
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.
159157

160-
* `spanner/max_allowed_sessions`: This shows the maximum
161-
number of sessions allowed.
158+
These metrics are default enabled, you can choose to opt out of using client-side metrics by using the following code:
162159

163-
* `spanner/num_sessions_in_pool`: This metric allows users to
164-
see instance-level and database-level data for the total number of sessions in
165-
the pool at this very moment.
166-
167-
* `spanner/num_acquired_sessions`: This metric allows
168-
users to see the total number of acquired sessions.
169-
170-
* `spanner/num_released_sessions`: This metric allows
171-
users to see the total number of released (destroyed) sessions.
172-
173-
* `spanner/get_session_timeouts`: This gives you an
174-
indication of the total number of get session timed-out instead of being
175-
granted (the thread that requested the session is placed in a wait queue where
176-
it waits until a session is released into the pool by another thread) due to
177-
pool exhaustion since the server process started.
178-
179-
* `spanner/gfe_latency`: This metric shows latency between
180-
Google's network receiving an RPC and reading back the first byte of the response.
181-
182-
* `spanner/gfe_header_missing_count`: This metric shows the
183-
number of RPC responses received without the server-timing header, most likely
184-
indicating that the RPC never reached Google's network.
185-
186-
### Instrument with OpenTelemetry
187-
188-
Cloud Spanner client supports [OpenTelemetry Metrics](https://opentelemetry.io/),
189-
which gives insight into the client internals and aids in debugging/troubleshooting
190-
production issues. OpenTelemetry metrics will provide you with enough data to enable you to
191-
spot, and investigate the cause of any unusual deviations from normal behavior.
192-
193-
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
194-
metrics will be tagged with:
195-
* `database`: the target database name.
196-
* `instance_id`: the instance id of the target Spanner instance.
197-
* `client_id`: the user defined database client id.
198-
199-
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:
200-
201-
#### OpenTelemetry Dependencies
202-
If you are using Maven, add this to your pom.xml file
203-
```xml
204-
<dependency>
205-
<groupId>io.opentelemetry</groupId>
206-
<artifactId>opentelemetry-sdk</artifactId>
207-
<version>{opentelemetry.version}</version>
208-
</dependency>
209-
<dependency>
210-
<groupId>io.opentelemetry</groupId>
211-
<artifactId>opentelemetry-sdk-metrics</artifactId>
212-
<version>{opentelemetry.version}</version>
213-
</dependency>
214-
<dependency>
215-
<groupId>io.opentelemetry</groupId>
216-
<artifactId>opentelemetry-exporter-otlp</artifactId>
217-
<version>{opentelemetry.version}</version>
218-
</dependency>
219-
```
220-
If you are using Gradle, add this to your dependencies
221-
```Groovy
222-
compile 'io.opentelemetry:opentelemetry-sdk:{opentelemetry.version}'
223-
compile 'io.opentelemetry:opentelemetry-sdk-metrics:{opentelemetry.version}'
224-
compile 'io.opentelemetry:opentelemetry-exporter-oltp:{opentelemetry.version}'
225160
```
226-
227-
#### OpenTelemetry Configuration
228-
By default, all metrics are disabled. To enable metrics and configure the OpenTelemetry follow below:
229-
230-
```java
231-
// Enable OpenTelemetry metrics before injecting OpenTelemetry object.
232-
SpannerOptions.enableOpenTelemetryMetrics();
233-
234-
SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
235-
// Use Otlp exporter or any other exporter of your choice.
236-
.registerMetricReader(PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build())
237-
.build())
238-
.build();
239-
240-
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
241-
.setMeterProvider(sdkMeterProvider)
242-
.build()
243-
244161
SpannerOptions options = SpannerOptions.newBuilder()
245-
// Inject OpenTelemetry object via Spanner Options or register OpenTelemetry object as Global
246-
.setOpenTelemetry(openTelemetry)
162+
.setBuiltInMetricsEnabled(false)
247163
.build();
248-
249-
Spanner spanner = options.getService();
250-
```
251-
252-
#### OpenTelemetry SQL Statement Tracing
253-
The OpenTelemetry traces that are generated by the Java client include any request and transaction
254-
tags that have been set. The traces can also include the SQL statements that are executed and the
255-
name of the thread that executes the statement. Enable this with the `enableExtendedTracing`
256-
option:
257-
258-
```
259-
SpannerOptions options = SpannerOptions.newBuilder()
260-
.setOpenTelemetry(openTelemetry)
261-
.setEnableExtendedTracing(true)
262-
.build();
263-
```
264-
265-
This option can also be enabled by setting the environment variable
266-
`SPANNER_ENABLE_EXTENDED_TRACING=true`.
267-
268-
#### OpenTelemetry API Tracing
269-
You can enable tracing of each API call that the Spanner client executes with the `enableApiTracing`
270-
option. These traces also include any retry attempts for an API call:
271-
272-
```
273-
SpannerOptions options = SpannerOptions.newBuilder()
274-
.setOpenTelemetry(openTelemetry)
275-
.setEnableApiTracing(true)
276-
.build();
277-
```
278-
279-
This option can also be enabled by setting the environment variable
280-
`SPANNER_ENABLE_API_TRACING=true`.
281-
282-
> Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release.
283-
284-
285-
### Instrument with OpenCensus
286-
287-
> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).
288-
We recommend migrating to OpenTelemetry, the successor project.
289-
290-
Cloud Spanner client supports [Opencensus Metrics](https://opencensus.io/stats/),
291-
which gives insight into the client internals and aids in debugging/troubleshooting
292-
production issues. OpenCensus metrics will provide you with enough data to enable you to
293-
spot, and investigate the cause of any unusual deviations from normal behavior.
294-
295-
All Cloud Spanner Metrics are prefixed with `cloud.google.com/java/spanner`
296-
297-
The metrics are tagged with:
298-
* `database`: the target database name.
299-
* `instance_id`: the instance id of the target Spanner instance.
300-
* `client_id`: the user defined database client id.
301-
* `library_version`: the version of the library that you're using.
302-
303-
304-
By default, the functionality is disabled. You need to include opencensus-impl
305-
dependency to collect the data and exporter dependency to export to backend.
306-
307-
[Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
308-
309-
#### OpenCensus Dependencies
310-
311-
If you are using Maven, add this to your pom.xml file
312-
```xml
313-
<dependency>
314-
<groupId>io.opencensus</groupId>
315-
<artifactId>opencensus-impl</artifactId>
316-
<version>0.30.0</version>
317-
<scope>runtime</scope>
318-
</dependency>
319-
<dependency>
320-
<groupId>io.opencensus</groupId>
321-
<artifactId>opencensus-exporter-stats-stackdriver</artifactId>
322-
<version>0.30.0</version>
323-
</dependency>
324-
```
325-
If you are using Gradle, add this to your dependencies
326-
```Groovy
327-
compile 'io.opencensus:opencensus-impl:0.30.0'
328-
compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0'
329-
```
330-
331-
#### Configure the OpenCensus Exporter
332-
333-
At the start of your application configure the exporter:
334-
335-
```java
336-
import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter;
337-
// Enable OpenCensus exporters to export metrics to Stackdriver Monitoring.
338-
// Exporters use Application Default Credentials to authenticate.
339-
// See https://developers.google.com/identity/protocols/application-default-credentials
340-
// for more details.
341-
// The minimum reporting period for Stackdriver is 1 minute.
342-
StackdriverStatsExporter.createAndRegister();
343164
```
344-
#### Enable RPC Views
345165

346-
By default, all session metrics are enabled. To enable RPC views, use either of the following method:
166+
You can also disable these metrics by setting `SPANNER_DISABLE_BUILTIN_METRICS` to `true`
347167

348-
```java
349-
// Register views for GFE metrics, including gfe_latency and gfe_header_missing_count.
350-
SpannerRpcViews.registerGfeLatencyAndHeaderMissingCountViews();
351-
352-
// Register GFE Latency view.
353-
SpannerRpcViews.registerGfeLatencyView();
354-
355-
// Register GFE Header Missing Count view.
356-
SpannerRpcViews.registerGfeHeaderMissingCountView();
357-
```
168+
> 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.
358169
359170
## Traces
360171
Cloud Spanner client supports OpenTelemetry Traces, which gives insight into the client internals and aids in debugging/troubleshooting production issues.
361172

362173
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.
363174

175+
Refer [Configure client-side tracing](https://cloud.google.com/spanner/docs/set-up-tracing#configure-client-side-tracing) to configure traces
176+
364177
#### OpenTelemetry Dependencies
365178

366179
If you are using Maven, add this to your pom.xml file
@@ -447,6 +260,29 @@ This option can also be enabled by setting the environment variable
447260

448261
> Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release.
449262
263+
#### End-to-end Tracing
264+
265+
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:
266+
* Identify whether the latency is due to network latency between your application and Spanner, or if the latency is occurring within Spanner.
267+
* 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.
268+
269+
```
270+
SpannerOptions options = SpannerOptions.newBuilder()
271+
.setOpenTelemetry(openTelemetry)
272+
.setEnableEndToEndTracing(true)
273+
.build();
274+
```
275+
276+
Refer [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 understand the attributes for this.
277+
278+
> Note: End-to-end traces can only be exported to [Cloud Trace](https://cloud.google.com/trace/docs).
279+
280+
281+
## Instrument with OpenCensus
282+
283+
> Note: OpenCensus project is deprecated. See [Sunsetting OpenCensus](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).
284+
We recommend migrating to OpenTelemetry, the successor project.
285+
450286
## Migrate from OpenCensus to OpenTelemetry
451287

452288
> 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

0 commit comments

Comments
 (0)