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>

Author: surbhigarg92

.readme-partials.yaml

@@ -50,55 +50,133 @@ custom_content: |
   for in-depth background information about sessions and gRPC channels and how these are handled in
   the Cloud Spanner Java client.
 
-  ## OpenCensus Metrics
+  ## Metrics
 
-  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 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.
-  * `library_version`: the version of the library that you're using.
-
-  > Note: RPC level metrics can be gleaned from gRPC’s metrics, which are prefixed
-  with `grpc.io/client/`.
   ### Available client-side metrics:
 
-  * `cloud.google.com/java/spanner/max_in_use_sessions`: This returns the maximum
+  * `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.
 
-  * `cloud.google.com/java/spanner/max_allowed_sessions`: This shows the maximum
+  * `spanner/max_allowed_sessions`: This shows the maximum
     number of sessions allowed.
 
-  * `cloud.google.com/java/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_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.
 
-  * `cloud.google.com/java/spanner/num_acquired_sessions`: This metric allows
+  * `spanner/num_acquired_sessions`: This metric allows
     users to see the total number of acquired sessions.
 
-  * `cloud.google.com/java/spanner/num_released_sessions`: This metric allows
+  * `spanner/num_released_sessions`: This metric allows
     users to see the total number of released (destroyed) sessions.
 
-  * `cloud.google.com/java/spanner/get_session_timeouts`: This gives you an
+  * `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.
 
-  * `cloud.google.com/java/spanner/gfe_latency`: This metric shows latency between
+  * `spanner/gfe_latency`: This metric shows latency between
     Google's network receiving an RPC and reading back the first byte of the response.
 
-  * `cloud.google.com/java/spanner/gfe_header_missing_count`: This metric shows the
+  * `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 OpenTelmetry object as Global
+    .setOpenTelemetry(openTelemetry)
+    .build();
+
+  Spanner spanner = options.getService();
+  ```
+
+  ### 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>
@@ -119,6 +197,8 @@ custom_content: |
   compile 'io.opencensus:opencensus-exporter-stats-stackdriver:0.30.0'
   ```
 
+  #### Configure the OpenCensus Exporter
+
   At the start of your application configure the exporter:
 
   ```java
@@ -130,9 +210,107 @@ custom_content: |
   // The minimum reporting period for Stackdriver is 1 minute.
   StackdriverStatsExporter.createAndRegister();
   ```
+  #### Enable RPC Views
 
-  By default, the functionality is disabled. You need to include opencensus-impl
-  dependency to collect the data and exporter dependency to export to backend.
+  By default, all session metrics are enabled. To enable RPC views, use either of the following method:
 
-  [Click here](https://medium.com/google-cloud/troubleshooting-cloud-spanner-applications-with-opencensus-2cf424c4c590) for more information.
+  ```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();
+  ```
+
+  ## 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.