Set up client-side metrics

Go

Follow these steps if you use the Bigtable client library for Go, which calls the Bigtable APIs.

Install and configure the client library for Go

Update the Bigtable client library for Go to version 1.27.0 or later. Your go.mod should look similar to the following:

require (
  cloud.google.com/go/bigtable v1.27.2-0.20240725222120-ce31365acc54

Optional: Opt out of client-side metrics

Client-side metrics are enabled by default in the Go client library. To opt out, pass NoopMetricsProvider in the ClientConfig:

client, err := bigtable.NewClientWithConfig(ctx, project, instance,
bigtable.ClientConfig{MetricsProvider: bigtable.NoopMetricsProvider{},
})

HBase

Follow these steps if you use the Bigtable HBase client for Java, which calls the HBase API, to connect your application to Bigtable.

Install and configure the HBase client library for Java

1. Download and install the latest Bigtable HBase client for Java. To enable client-side metrics, you must use version 2.6.4 or later.

2. Create an empty Maven project.

3. Determine the artifact dependency that's right for your use case. The 2.x versions include an HBase async client that the 1.x versions do not have.

   • bigtable-hbase-1.x or bigtable-hbase-2.x: Use for standalone applications where you are in control of your dependencies.
   • bigtable-hbase-1.x-hadoop or bigtable-hbase-2.x-hadoop: Use in Hadoop environments.
   • bigtable-hbase-1.x-shaded or bigtable-hbase-2.x-shaded: Use in environments other than Hadoop that require earlier versions of components such as protobufs or Guava.

4. Update the pom.xml file:

   <dependencyManagement>
       <dependencies>
           <dependency>
                 <groupId>com.google.cloud.bigtable</groupId>
                 <artifactId>BIGTABLE_HBASE_ARTIFACT</artifactId>
                 <version>VERSION_NUMBER</version>
             </dependency>
       </dependencies>
   </dependencyManagement>
   

   Provide the following:

   • BIGTABLE_HBASE_ARTIFACT: the artifact dependency for your project, formatted like bigtable-hbase-1.x or bigtable-hbase-2.x-hadoop.
   • VERSION_NUMBER: the client library version that you are using, formatted like 2.6.4

Enable client-side metrics in your application

Using bigtable-hbase-1.x or bigtable-hbase-2.x

When you create a connection using the HBase client library and either the bigtable-hbase-1.x or bigtable-hbase-2.x artifacts, your code to enable the built-in client-side metrics looks similar to the following:

  import com.google.cloud.bigtable.data.v2.BigtableDataSettings;

  Configuration configuration = BigtableConfiguration.configure("my-project-id", "my-instance-id");
  Connection connection = new BigtableConnection(configuration);

  BigtableDataSettings.enableBuiltinMetrics();

Using -hadoop or -shaded artifacts

When you create a connection using the HBase client library and one of the -hadoop or -shaded artifacts, your code to enable the built-in client-side metrics looks similar to the following:

  import com.google.bigtable.repackaged.com.google.cloud.bigtable.data.v2.BigtableDataSettings;

  Configuration configuration = BigtableConfiguration.configure("my-project-id", "my-instance-id");
  Connection connection = new BigtableConnection(configuration);

  BigtableDataSettings.enableBuiltinMetrics();

Optional: Opt out of client-side metrics

If you are using version 2.14.1 or later, client-side metrics are enabled by default. You can opt out.

Configuration configuration = BigtableConfiguration.configure("my-project-id", "my-instance-id");
configuration.setBoolean(BigtableOptionsFactory.BIGTABLE_ENABLE_CLIENT_SIDE_METRICS, false);
Connection connection = new BigtableConnection(configuration);

Java

Follow these steps if you use the Bigtable client library for Java, which calls the Bigtable APIs.

Before you begin

Optional: If you use an OpenCensus Stats integration to get Bigtable metrics, revert the dependency and StackdriverStatsExporter changes in your application. To understand why, see When to upgrade.

Install and configure the client library for Java

1. Download and install the latest Bigtable client library for Java. You must have version 2.16.0 or higher to use client-side metrics.

2. Update the Java client library's pom.xml file to use the latest version. Your pom should look similar to the following:

   <dependencyManagement>
       <dependencies>
           <dependency>
                 <groupId>com.google.cloud</groupId>
                 <artifactId>google-cloud-bigtable-bom</artifactId>
                 <version>2.38.0</version>
                 <scope>import</scope>
                 <type>pom</type>
             </dependency>
       </dependencies>
   </dependencyManagement>
   
   <dependencies>
       <dependency>
             <groupId>com.google.cloud</groupId>
             <artifactId>google-cloud-bigtable</artifactId>
       </dependency>
   </dependencies>
   

Enable client-side metrics in your application

When you create a client using the client library, enable the built-in metrics. Your code should look similar to the following:

  BigtableDataSettings settings = BigtableDataSettings.newBuilder()
              .setProjectId("our-project-2-12")
              .setInstanceId("our-instance-85")
              .setAppProfileId("our-appProfile-06")
              .build();

  BigtableDataSettings.enableBuiltinMetrics();

  try (BigtableDataClient client = BigtableDataClient.create(settings)) {
          // Application logic
  }

Set up a custom OpenTelemetry instance

If you are using version 2.38.0 or later, and you want to publish client-side metrics to Cloud Monitoring and custom sinks, you can set up a custom OpenTelemetry instance.

  SdkMeterProviderBuilder meterProviderBuilder = SdkMeterProvider.builder();

  // register client side metrics on your meter provider
  BuiltinMetricsView.registerBuiltinMetrics("my-project-id", meterProviderBuilder);

  // register other metric reader and views
  meterProviderBuilder.registerMetricReader().registerView();

  // create the OTEL instance
  OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
          .setMeterProvider(meterProviderBuilder.build())
          .build();

  // Override MetricsProvider in BigtableDataSettings
  BigtableDataSettings settings = BigtableDataSettings.newBuilder()
          .setProjectId("my-project-id")
          .setInstanceId("my-instance-id")
          .setMetricsProvider(CustomOpenTelemetryMetricsProvider.create(openTelemetry))
          .build();

  try (BigtableDataClient client = BigtableDataClient.create(settings)) {
        // Application logic
  }

Optional: Opt out of client-side metrics

If you are using version 2.38.0 and later, you can opt out of using client-side metrics.

BigtableDataSettings settings = BigtableDataSettings.newBuilder()
        .setProjectId("my-project")
        .setInstanceId("my-instance")
        .setMetricsProvider(NoopMetricsProvider.INSTANCE)
        .build();