.readme-partials.yaml

custom_content: |
  #### Calling Cloud Spanner
  Here is a code snippet showing a simple usage example. Add the following imports
  at the top of your file:

  ```java
  import com.google.cloud.spanner.DatabaseClient;
  import com.google.cloud.spanner.DatabaseId;
  import com.google.cloud.spanner.ResultSet;
  import com.google.cloud.spanner.Spanner;
  import com.google.cloud.spanner.SpannerOptions;
  import com.google.cloud.spanner.Statement;

  ```

  Then, to make a query to Spanner, use the following code:
  ```java
  // Instantiates a client
  SpannerOptions options = SpannerOptions.newBuilder().build();
  Spanner spanner = options.getService();
  String instance = "my-instance";
  String database = "my-database";
  try {
    // Creates a database client
    DatabaseClient dbClient = spanner.getDatabaseClient(
      DatabaseId.of(options.getProjectId(), instance, database));
    // Queries the database
    try (ResultSet resultSet = dbClient.singleUse().executeQuery(Statement.of("SELECT 1"))) {
      // Prints the results
      while (resultSet.next()) {
        System.out.printf("%d\n", resultSet.getLong(0));
      }
    }
  } finally {
    // Closes the client which will free up the resources used
    spanner.close();
  }
  ```

  #### Complete source code

  In [DatabaseSelect.java](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-examples/src/main/java/com/google/cloud/examples/spanner/snippets/DatabaseSelect.java) we put together all the code shown above in a single program.

  ## Session Pool

  The Cloud Spanner client maintains a session pool, as sessions are expensive to create and are
  intended to be long-lived. The client automatically takes a session from the pool and uses this
  executing queries and transactions.
  See [Session Pool and Channel Pool Configuration](session-and-channel-pool-configuration.md)
  for in-depth background information about sessions and gRPC channels and how these are handled in
  the Cloud Spanner Java client.

  ## Metrics

  ### Available client-side metrics:

  * `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.

  * `spanner/max_allowed_sessions`: This shows the maximum
    number of sessions allowed.

  * `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_acquired_sessions`: This metric allows
    users to see the total number of acquired sessions.

  * `spanner/num_released_sessions`: This metric allows
    users to see the total number of released (destroyed) sessions.

  * `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.

  * `spanner/gfe_latency`: This metric shows latency between
    Google's network receiving an RPC and reading back the first byte of the response.

  * `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 OpenTelemetry object as Global
    .setOpenTelemetry(openTelemetry)
    .build();

  Spanner spanner = options.getService();
  ```
  
  #### OpenTelemetry SQL Statement Tracing
  The OpenTelemetry traces that are generated by the Java client include any request and transaction
  tags that have been set. The traces can also include the SQL statements that are executed and the
  name of the thread that executes the statement. Enable this with the `enableExtendedTracing`
  option:
  
  ```
  SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .setEnableExtendedTracing(true)
    .build();
  ```
  
  This option can also be enabled by setting the environment variable
  `SPANNER_ENABLE_EXTENDED_TRACING=true`.

  #### OpenTelemetry API Tracing
  You can enable tracing of each API call that the Spanner client executes with the `enableApiTracing`
  option. These traces also include any retry attempts for an API call:
    
  ```
  SpannerOptions options = SpannerOptions.newBuilder()
  .setOpenTelemetry(openTelemetry)
  .setEnableApiTracing(true)
  .build();
  ```
    
  This option can also be enabled by setting the environment variable
  `SPANNER_ENABLE_API_TRACING=true`.
  
  > Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release.


  ### 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>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-impl</artifactId>
    <version>0.30.0</version>
    <scope>runtime</scope>
  </dependency>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-exporter-stats-stackdriver</artifactId>
    <version>0.30.0</version>
  </dependency>
  ```
  If you are using Gradle, add this to your dependencies
  ```Groovy
  compile 'io.opencensus:opencensus-impl:0.30.0'
  compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0'
  ```

  #### Configure the OpenCensus Exporter

  At the start of your application configure the exporter:

  ```java
  import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter;
  // Enable OpenCensus exporters to export metrics to Stackdriver Monitoring.
  // Exporters use Application Default Credentials to authenticate.
  // See https://developers.google.com/identity/protocols/application-default-credentials
  // for more details.
  // The minimum reporting period for Stackdriver is 1 minute.
  StackdriverStatsExporter.createAndRegister();
  ```
  #### Enable RPC Views

  By default, all session metrics are enabled. To enable RPC views, use either of the following method:

  ```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();
  ```
  
  #### OpenTelemetry SQL Statement Tracing
  The OpenTelemetry traces that are generated by the Java client include any request and transaction
  tags that have been set. The traces can also include the SQL statements that are executed and the
  name of the thread that executes the statement. Enable this with the `enableExtendedTracing`
  option:

  ```
  SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .setEnableExtendedTracing(true)
    .build();
  ```

  This option can also be enabled by setting the environment variable
  `SPANNER_ENABLE_EXTENDED_TRACING=true`.

  #### OpenTelemetry API Tracing
  You can enable tracing of each API call that the Spanner client executes with the `enableApiTracing`
  option. These traces also include any retry attempts for an API call:
    
  ```
  SpannerOptions options = SpannerOptions.newBuilder()
  .setOpenTelemetry(openTelemetry)
  .setEnableApiTracing(true)
  .build();
  ```
    
  This option can also be enabled by setting the environment variable
  `SPANNER_ENABLE_API_TRACING=true`.

  > Note: The attribute keys that are used for additional information about retry attempts and the number of requests might change in a future release.

  ## 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.