feat: Add the MetricsCollector for client side metrics

package.json

@@ -47,9 +47,14 @@
     "precompile": "gts clean"
   },
   "dependencies": {
+    "@google-cloud/opentelemetry-cloud-monitoring-exporter": "^0.20.0",
+    "@google-cloud/opentelemetry-resource-util": "^2.4.0",
     "@google-cloud/precise-date": "^4.0.0",
     "@google-cloud/projectify": "^4.0.0",
     "@google-cloud/promisify": "^4.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-metrics": "^1.30.0",
     "arrify": "^2.0.0",
     "concat-stream": "^2.0.0",
     "dot-prop": "^6.0.0",

src/client-side-metrics/client-side-metrics-attributes.ts

@@ -0,0 +1,34 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// The backend is expecting true/false and will fail if other values are provided.
+// export in open telemetry is expecting string value attributes so we don't use boolean
+// true/false.
+export enum StreamingState {
+  STREAMING = 'true',
+  UNARY = 'false',
+}
+
+/**
+ * Represents the names of Bigtable methods. These are used as attributes for
+ * metrics, allowing for differentiation of performance by method.
+ */
+export enum MethodName {
+  READ_ROWS = 'Bigtable.ReadRows',
+  MUTATE_ROW = 'Bigtable.MutateRow',
+  CHECK_AND_MUTATE_ROW = 'Bigtable.CheckAndMutateRow',
+  READ_MODIFY_WRITE_ROW = 'Bigtable.ReadModifyWriteRow',
+  SAMPLE_ROW_KEYS = 'Bigtable.SampleRowKeys',
+  MUTATE_ROWS = 'Bigtable.MutateRows',
+}

src/client-side-metrics/metrics-handler.ts

@@ -0,0 +1,71 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {MethodName, StreamingState} from './client-side-metrics-attributes';
+import {grpc} from 'google-gax';
+
+/**
+ * The interfaces below use undefined instead of null to indicate a metric is
+ * not available yet. The benefit of this is that new metrics can be added
+ * without requiring users to change the methods in their metrics handler.
+ */
+
+type IMetricsCollectorData = {
+  instanceId: string;
+  table: string;
+  cluster?: string;
+  zone?: string;
+  appProfileId?: string;
+  methodName: MethodName;
+  clientUid: string;
+};
+
+interface StandardData {
+  projectId: string;
+  metricsCollectorData: IMetricsCollectorData;
+  clientName: string;
+  streamingOperation: StreamingState;
+}
+
+export interface OnOperationCompleteData extends StandardData {
+  firstResponseLatency?: number;
+  operationLatency: number;
+  retryCount?: number;
+  finalOperationStatus: grpc.status;
+}
+
+export interface OnAttemptCompleteData extends StandardData {
+  attemptLatency: number;
+  serverLatency?: number;
+  connectivityErrorCount: number;
+  attemptStatus: grpc.status;
+}
+
+/**
+ * An interface for handling client-side metrics related to Bigtable operations.
+ * Implementations of this interface can define how metrics are recorded and processed.
+ */
+export interface IMetricsHandler {
+  /**
+   * Called when an operation completes (successfully or unsuccessfully).
+   * @param {OnOperationCompleteData} data Metrics and attributes related to the completed operation.
+   */
+  onOperationComplete?(data: OnOperationCompleteData): void;
+
+  /**
+   * Called when an attempt (e.g., an RPC attempt) completes.
+   * @param {OnAttemptCompleteData} data Metrics and attributes related to the completed attempt.
+   */
+  onAttemptComplete?(data: OnAttemptCompleteData): void;
+}

src/client-side-metrics/operation-metrics-collector.ts

@@ -0,0 +1,300 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import * as fs from 'fs';
+import {IMetricsHandler} from './metrics-handler';
+import {MethodName, StreamingState} from './client-side-metrics-attributes';
+import {grpc} from 'google-gax';
+import * as gax from 'google-gax';
+const root = gax.protobuf.loadSync(
+  './protos/google/bigtable/v2/response_params.proto'
+);
+const ResponseParams = root.lookupType('ResponseParams');
+
+/**
+ * An interface representing a tabular API surface, such as a Bigtable table.
+ */
+export interface ITabularApiSurface {
+  instance: {
+    id: string;
+  };
+  id: string;
+  bigtable: {
+    appProfileId?: string;
+    clientUid: string;
+  };
+}
+
+const packageJSON = fs.readFileSync('package.json');
+const version = JSON.parse(packageJSON.toString()).version;
+
+// MetricsCollectorState is a list of states that the metrics collector can be in.
+// Tracking the OperationMetricsCollector state is done so that the
+// OperationMetricsCollector methods are not called in the wrong order. If the
+// methods are called in the wrong order they will not execute and they will
+// throw warnings.
+//
+// The following state transitions are allowed:
+// OPERATION_NOT_STARTED -> OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS
+// OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS -> OPERATION_STARTED_ATTEMPT_IN_PROGRESS
+// OPERATION_STARTED_ATTEMPT_IN_PROGRESS -> OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS
+// OPERATION_STARTED_ATTEMPT_IN_PROGRESS -> OPERATION_COMPLETE
+enum MetricsCollectorState {
+  OPERATION_NOT_STARTED,
+  OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS,
+  OPERATION_STARTED_ATTEMPT_IN_PROGRESS_NO_ROWS_YET,
+  OPERATION_STARTED_ATTEMPT_IN_PROGRESS_SOME_ROWS_RECEIVED,
+  OPERATION_COMPLETE,
+}
+
+/**
+ * A class for tracing and recording client-side metrics related to Bigtable operations.
+ */
+export class OperationMetricsCollector {
+  private state: MetricsCollectorState;
+  private operationStartTime: Date | null;
+  private attemptStartTime: Date | null;
+  private zone: string | undefined;
+  private cluster: string | undefined;
+  private tabularApiSurface: ITabularApiSurface;
+  private methodName: MethodName;
+  private attemptCount = 0;
+  private metricsHandlers: IMetricsHandler[];
+  private firstResponseLatency: number | null;
+  private serverTimeRead: boolean;
+  private serverTime: number | null;
+  private connectivityErrorCount: number;
+  private streamingOperation: StreamingState;
+
+  /**
+   * @param {ITabularApiSurface} tabularApiSurface Information about the Bigtable table being accessed.
+   * @param {IMetricsHandler[]} metricsHandlers The metrics handlers used for recording metrics.
+   * @param {MethodName} methodName The name of the method being traced.
+   * @param {StreamingState} streamingOperation Whether or not the call is a streaming operation.
+   */
+  constructor(
+    tabularApiSurface: ITabularApiSurface,
+    metricsHandlers: IMetricsHandler[],
+    methodName: MethodName,
+    streamingOperation: StreamingState
+  ) {
+    this.state = MetricsCollectorState.OPERATION_NOT_STARTED;
+    this.zone = undefined;
+    this.cluster = undefined;
+    this.tabularApiSurface = tabularApiSurface;
+    this.methodName = methodName;
+    this.operationStartTime = null;
+    this.attemptStartTime = null;
+    this.metricsHandlers = metricsHandlers;
+    this.firstResponseLatency = null;
+    this.serverTimeRead = false;
+    this.serverTime = null;
+    this.connectivityErrorCount = 0;
+    this.streamingOperation = streamingOperation;
+  }
+
+  private getMetricsCollectorData() {
+    return {
+      instanceId: this.tabularApiSurface.instance.id,
+      table: this.tabularApiSurface.id,
+      cluster: this.cluster,
+      zone: this.zone,
+      appProfileId: this.tabularApiSurface.bigtable.appProfileId,
+      methodName: this.methodName,
+      clientUid: this.tabularApiSurface.bigtable.clientUid,
+    };
+  }
+
+  /**
+   * Called when the operation starts. Records the start time.
+   */
+  onOperationStart() {
+    if (this.state === MetricsCollectorState.OPERATION_NOT_STARTED) {
+      this.operationStartTime = new Date();
+      this.firstResponseLatency = null;
+      this.state =
+        MetricsCollectorState.OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS;
+    } else {
+      console.warn('Invalid state transition');
+    }
+  }
+
+  /**
+   * Called when an attempt (e.g., an RPC attempt) completes. Records attempt latencies.
+   * @param {string} projectId The id of the project.
+   * @param {grpc.status} attemptStatus The grpc status for the attempt.
+   */
+  onAttemptComplete(projectId: string, attemptStatus: grpc.status) {
+    if (
+      this.state ===
+        MetricsCollectorState.OPERATION_STARTED_ATTEMPT_IN_PROGRESS_NO_ROWS_YET ||
+      this.state ===
+        MetricsCollectorState.OPERATION_STARTED_ATTEMPT_IN_PROGRESS_SOME_ROWS_RECEIVED
+    ) {
+      this.state =
+        MetricsCollectorState.OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS;
+      this.attemptCount++;
+      const endTime = new Date();
+      if (projectId && this.attemptStartTime) {
+        const totalTime = endTime.getTime() - this.attemptStartTime.getTime();
+        this.metricsHandlers.forEach(metricsHandler => {
+          if (metricsHandler.onAttemptComplete) {
+            metricsHandler.onAttemptComplete({
+              attemptLatency: totalTime,
+              serverLatency: this.serverTime ?? undefined,
+              connectivityErrorCount: this.connectivityErrorCount,
+              streamingOperation: this.streamingOperation,
+              attemptStatus,
+              clientName: `nodejs-bigtable/${version}`,
+              metricsCollectorData: this.getMetricsCollectorData(),
+              projectId,
+            });
+          }
+        });
+      }
+    } else {
+      console.warn('Invalid state transition attempted');
+    }
+  }
+
+  /**
+   * Called when a new attempt starts. Records the start time of the attempt.
+   */
+  onAttemptStart() {
+    if (
+      this.state ===
+      MetricsCollectorState.OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS
+    ) {
+      this.state =
+        MetricsCollectorState.OPERATION_STARTED_ATTEMPT_IN_PROGRESS_NO_ROWS_YET;
+      this.attemptStartTime = new Date();
+      this.serverTime = null;
+      this.serverTimeRead = false;
+      this.connectivityErrorCount = 0;
+    } else {
+      console.warn('Invalid state transition attempted');
+    }
+  }
+
+  /**
+   * Called when the first response is received. Records first response latencies.
+   */
+  onResponse(projectId: string) {
+    if (
+      this.state ===
+      MetricsCollectorState.OPERATION_STARTED_ATTEMPT_IN_PROGRESS_NO_ROWS_YET
+    ) {
+      this.state =
+        MetricsCollectorState.OPERATION_STARTED_ATTEMPT_IN_PROGRESS_SOME_ROWS_RECEIVED;
+      const endTime = new Date();
+      if (projectId && this.operationStartTime) {
+        this.firstResponseLatency =
+          endTime.getTime() - this.operationStartTime.getTime();
+      }
+    }
+  }
+
+  /**
+   * Called when an operation completes (successfully or unsuccessfully).
+   * Records operation latencies, retry counts, and connectivity error counts.
+   * @param {string} projectId The id of the project.
+   * @param {grpc.status} finalOperationStatus Information about the completed operation.
+   */
+  onOperationComplete(projectId: string, finalOperationStatus: grpc.status) {
+    if (
+      this.state ===
+      MetricsCollectorState.OPERATION_STARTED_ATTEMPT_NOT_IN_PROGRESS
+    ) {
+      this.state = MetricsCollectorState.OPERATION_COMPLETE;
+      const endTime = new Date();
+      if (projectId && this.operationStartTime) {
+        const totalTime = endTime.getTime() - this.operationStartTime.getTime();
+        {
+          this.metricsHandlers.forEach(metricsHandler => {
+            if (metricsHandler.onOperationComplete) {
+              metricsHandler.onOperationComplete({
+                finalOperationStatus: finalOperationStatus,
+                streamingOperation: this.streamingOperation,
+                metricsCollectorData: this.getMetricsCollectorData(),
+                clientName: `nodejs-bigtable/${version}`,
+                projectId,
+                operationLatency: totalTime,
+                retryCount: this.attemptCount - 1,
+                firstResponseLatency: this.firstResponseLatency ?? undefined,
+              });
+            }
+          });
+        }
+      }
+    } else {
+      console.warn('Invalid state transition attempted');
+    }
+  }
+
+  /**
+   * Called when metadata is received. Extracts server timing information if available.
+   * @param {object} metadata The received metadata.
+   */
+  onMetadataReceived(metadata: {
+    internalRepr: Map<string, string[]>;
+    options: {};
+  }) {
+    const mappedEntries = new Map(
+      Array.from(metadata.internalRepr.entries(), ([key, value]) => [
+        key,
+        value.toString(),
+      ])
+    );
+    const SERVER_TIMING_REGEX = /.*gfet4t7;\s*dur=(\d+\.?\d*).*/;
+    const SERVER_TIMING_KEY = 'server-timing';
+    const durationValues = mappedEntries.get(SERVER_TIMING_KEY);
+    const matchedDuration = durationValues?.match(SERVER_TIMING_REGEX);
+    if (matchedDuration && matchedDuration[1]) {
+      if (!this.serverTimeRead) {
+        this.serverTimeRead = true;
+        this.serverTime = isNaN(parseInt(matchedDuration[1]))
+          ? null
+          : parseInt(matchedDuration[1]);
+      }
+    } else {
+      this.connectivityErrorCount++;
+    }
+  }
+
+  /**
+   * Called when status information is received. Extracts zone and cluster information.
+   * @param {object} status The received status information.
+   */
+  onStatusMetadataReceived(status: {
+    metadata: {internalRepr: Map<string, Uint8Array[]>; options: {}};
+  }) {
+    const INSTANCE_INFORMATION_KEY = 'x-goog-ext-425905942-bin';
+    const mappedValue = status.metadata.internalRepr.get(
+      INSTANCE_INFORMATION_KEY
+    ) as Buffer[];
+    const decodedValue = ResponseParams.decode(
+      mappedValue[0],
+      mappedValue[0].length
+    );
+    if (decodedValue && (decodedValue as unknown as {zoneId: string}).zoneId) {
+      this.zone = (decodedValue as unknown as {zoneId: string}).zoneId;
+    }
+    if (
+      decodedValue &&
+      (decodedValue as unknown as {clusterId: string}).clusterId
+    ) {
+      this.cluster = (decodedValue as unknown as {clusterId: string}).clusterId;
+    }
+  }
+}

test-common/test-metrics-handler.ts

@@ -0,0 +1,53 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {
+  IMetricsHandler,
+  OnAttemptCompleteData,
+  OnOperationCompleteData,
+} from '../src/client-side-metrics/metrics-handler';
+
+/**
+ * A test implementation of the IMetricsHandler interface.  Used for testing purposes.
+ * It logs the metrics and attributes received by the onOperationComplete and onAttemptComplete methods.
+ */
+export class TestMetricsHandler implements IMetricsHandler {
+  private messages: {value: string};
+  requestsHandled: (OnOperationCompleteData | OnAttemptCompleteData)[] = [];
+
+  constructor(messages: {value: string}) {
+    this.messages = messages;
+  }
+  /**
+   * Logs the metrics and attributes received for an operation completion.
+   * @param {OnOperationCompleteData} data Metrics related to the completed operation.
+   */
+  onOperationComplete(data: OnOperationCompleteData) {
+    this.requestsHandled.push(data);
+    data.clientName = 'nodejs-bigtable';
+    this.messages.value += 'Recording parameters for onOperationComplete:\n';
+    this.messages.value += `${JSON.stringify(data)}\n`;
+  }
+
+  /**
+   * Logs the metrics and attributes received for an attempt completion.
+   * @param {OnOperationCompleteData} data Metrics related to the completed attempt.
+   */
+  onAttemptComplete(data: OnAttemptCompleteData) {
+    this.requestsHandled.push(data);
+    data.clientName = 'nodejs-bigtable';
+    this.messages.value += 'Recording parameters for onAttemptComplete:\n';
+    this.messages.value += `${JSON.stringify(data)}\n`;
+  }
+}

test/metrics-collector/metrics-collector.ts

@@ -0,0 +1,195 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {describe} from 'mocha';
+import * as assert from 'assert';
+import * as fs from 'fs';
+import {TestMetricsHandler} from '../../test-common/test-metrics-handler';
+import {OperationMetricsCollector} from '../../src/client-side-metrics/operation-metrics-collector';
+import {
+  MethodName,
+  StreamingState,
+} from '../../src/client-side-metrics/client-side-metrics-attributes';
+import {grpc} from 'google-gax';
+import {expectedRequestsHandled} from './metrics-handler-fixture';
+import * as gax from 'google-gax';
+const root = gax.protobuf.loadSync(
+  './protos/google/bigtable/v2/response_params.proto'
+);
+const ResponseParams = root.lookupType('ResponseParams');
+
+/**
+ * A fake implementation of the Bigtable client for testing purposes.  Provides a
+ * metricsTracerFactory and a stubbed projectId method.
+ */
+class FakeBigtable {
+  clientUid = 'fake-uuid';
+  appProfileId?: string;
+  projectId = 'my-project';
+}
+
+/**
+ * A fake implementation of a Bigtable instance for testing purposes.  Provides only an ID.
+ */
+class FakeInstance {
+  /**
+   * The ID of the fake instance.
+   */
+  id = 'fakeInstanceId';
+}
+
+describe('Bigtable/MetricsCollector', () => {
+  const logger = {value: ''};
+  const originalDate = global.Date;
+
+  before(() => {
+    let mockTime = new Date('1970-01-01T00:00:01.000Z').getTime();
+
+    (global as any).Date = class extends originalDate {
+      constructor(...args: any[]) {
+        // Using a rest parameter
+        if (args.length === 0) {
+          super(mockTime);
+          logger.value += `getDate call returns ${mockTime.toString()} ms\n`;
+          mockTime += 1000;
+        }
+      }
+
+      static now(): number {
+        return mockTime;
+      }
+
+      static parse(dateString: string): number {
+        return originalDate.parse(dateString);
+      }
+
+      static UTC(
+        year: number,
+        month: number,
+        date?: number,
+        hours?: number,
+        minutes?: number,
+        seconds?: number,
+        ms?: number
+      ): number {
+        return originalDate.UTC(year, month, date, hours, minutes, seconds, ms);
+      }
+    };
+  });
+
+  after(() => {
+    (global as any).Date = originalDate;
+  });
+
+  it('should record the right metrics with a typical method call', async () => {
+    const testHandler = new TestMetricsHandler(logger);
+    const metricsHandlers = [testHandler];
+    class FakeTable {
+      id = 'fakeTableId';
+      instance = new FakeInstance();
+      bigtable = new FakeBigtable();
+
+      async fakeMethod(): Promise<void> {
+        function createMetadata(duration: string) {
+          return {
+            internalRepr: new Map([
+              ['server-timing', [`gfet4t7; dur=${duration}`]],
+            ]),
+            options: {},
+          };
+        }
+        if (this.bigtable.projectId) {
+          const status = {
+            metadata: {
+              internalRepr: new Map([
+                [
+                  'x-goog-ext-425905942-bin',
+                  [
+                    ResponseParams.encode({
+                      zoneId: 'us-west1-c',
+                      clusterId: 'fake-cluster3',
+                    }).finish(),
+                  ],
+                ],
+              ]),
+              options: {},
+            },
+          };
+          const metricsCollector = new OperationMetricsCollector(
+            this,
+            metricsHandlers,
+            MethodName.READ_ROWS,
+            StreamingState.STREAMING
+          );
+          // In this method we simulate a series of events that might happen
+          // when a user calls one of the Table methods.
+          // Here is an example of what might happen in a method call:
+          logger.value += '1. The operation starts\n';
+          metricsCollector.onOperationStart();
+          logger.value += '2. The attempt starts.\n';
+          metricsCollector.onAttemptStart();
+          logger.value += '3. Client receives status information.\n';
+          metricsCollector.onStatusMetadataReceived(status);
+          logger.value += '4. Client receives metadata.\n';
+          metricsCollector.onMetadataReceived(createMetadata('101'));
+          logger.value += '5. Client receives first row.\n';
+          metricsCollector.onResponse(this.bigtable.projectId);
+          logger.value += '6. Client receives metadata.\n';
+          metricsCollector.onMetadataReceived(createMetadata('102'));
+          logger.value += '7. Client receives second row.\n';
+          metricsCollector.onResponse(this.bigtable.projectId);
+          logger.value += '8. A transient error occurs.\n';
+          metricsCollector.onAttemptComplete(
+            this.bigtable.projectId,
+            grpc.status.DEADLINE_EXCEEDED
+          );
+          logger.value += '9. After a timeout, the second attempt is made.\n';
+          metricsCollector.onAttemptStart();
+          logger.value += '10. Client receives status information.\n';
+          metricsCollector.onStatusMetadataReceived(status);
+          logger.value += '11. Client receives metadata.\n';
+          metricsCollector.onMetadataReceived(createMetadata('103'));
+          logger.value += '12. Client receives third row.\n';
+          metricsCollector.onResponse(this.bigtable.projectId);
+          logger.value += '13. Client receives metadata.\n';
+          metricsCollector.onMetadataReceived(createMetadata('104'));
+          logger.value += '14. Client receives fourth row.\n';
+          metricsCollector.onResponse(this.bigtable.projectId);
+          logger.value += '15. User reads row 1\n';
+          logger.value += '16. Stream ends, operation completes\n';
+          metricsCollector.onAttemptComplete(
+            this.bigtable.projectId,
+            grpc.status.OK
+          );
+          metricsCollector.onOperationComplete(
+            this.bigtable.projectId,
+            grpc.status.OK
+          );
+        }
+      }
+    }
+    const table = new FakeTable();
+    await table.fakeMethod();
+    const expectedOutput = fs.readFileSync(
+      './test/metrics-collector/typical-method-call.txt',
+      'utf8'
+    );
+    // Ensure events occurred in the right order here:
+    assert.strictEqual(logger.value, expectedOutput.replace(/\r/g, ''));
+    assert.deepStrictEqual(
+      testHandler.requestsHandled,
+      expectedRequestsHandled
+    );
+  });
+});

test/metrics-collector/metrics-handler-fixture.ts

@@ -0,0 +1,70 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export const expectedRequestsHandled = [
+  {
+    attemptLatency: 2000,
+    serverLatency: 101,
+    connectivityErrorCount: 0,
+    streamingOperation: 'true',
+    attemptStatus: 4,
+    clientName: 'nodejs-bigtable',
+    metricsCollectorData: {
+      appProfileId: undefined,
+      instanceId: 'fakeInstanceId',
+      table: 'fakeTableId',
+      cluster: 'fake-cluster3',
+      zone: 'us-west1-c',
+      methodName: 'Bigtable.ReadRows',
+      clientUid: 'fake-uuid',
+    },
+    projectId: 'my-project',
+  },
+  {
+    attemptLatency: 2000,
+    serverLatency: 103,
+    connectivityErrorCount: 0,
+    streamingOperation: 'true',
+    attemptStatus: 0,
+    clientName: 'nodejs-bigtable',
+    metricsCollectorData: {
+      appProfileId: undefined,
+      instanceId: 'fakeInstanceId',
+      table: 'fakeTableId',
+      cluster: 'fake-cluster3',
+      zone: 'us-west1-c',
+      methodName: 'Bigtable.ReadRows',
+      clientUid: 'fake-uuid',
+    },
+    projectId: 'my-project',
+  },
+  {
+    finalOperationStatus: 0,
+    streamingOperation: 'true',
+    metricsCollectorData: {
+      appProfileId: undefined,
+      instanceId: 'fakeInstanceId',
+      table: 'fakeTableId',
+      cluster: 'fake-cluster3',
+      zone: 'us-west1-c',
+      methodName: 'Bigtable.ReadRows',
+      clientUid: 'fake-uuid',
+    },
+    clientName: 'nodejs-bigtable',
+    projectId: 'my-project',
+    operationLatency: 7000,
+    retryCount: 1,
+    firstResponseLatency: 5000,
+  },
+];

test/metrics-collector/typical-method-call.txt

@@ -0,0 +1,30 @@
+1. The operation starts
+getDate call returns 1000 ms
+2. The attempt starts.
+getDate call returns 2000 ms
+3. Client receives status information.
+4. Client receives metadata.
+5. Client receives first row.
+getDate call returns 3000 ms
+6. Client receives metadata.
+7. Client receives second row.
+8. A transient error occurs.
+getDate call returns 4000 ms
+Recording parameters for onAttemptComplete:
+{"attemptLatency":2000,"serverLatency":101,"connectivityErrorCount":0,"streamingOperation":"true","attemptStatus":4,"clientName":"nodejs-bigtable","metricsCollectorData":{"instanceId":"fakeInstanceId","table":"fakeTableId","cluster":"fake-cluster3","zone":"us-west1-c","methodName":"Bigtable.ReadRows","clientUid":"fake-uuid"},"projectId":"my-project"}
+9. After a timeout, the second attempt is made.
+getDate call returns 5000 ms
+10. Client receives status information.
+11. Client receives metadata.
+12. Client receives third row.
+getDate call returns 6000 ms
+13. Client receives metadata.
+14. Client receives fourth row.
+15. User reads row 1
+16. Stream ends, operation completes
+getDate call returns 7000 ms
+Recording parameters for onAttemptComplete:
+{"attemptLatency":2000,"serverLatency":103,"connectivityErrorCount":0,"streamingOperation":"true","attemptStatus":0,"clientName":"nodejs-bigtable","metricsCollectorData":{"instanceId":"fakeInstanceId","table":"fakeTableId","cluster":"fake-cluster3","zone":"us-west1-c","methodName":"Bigtable.ReadRows","clientUid":"fake-uuid"},"projectId":"my-project"}
+getDate call returns 8000 ms
+Recording parameters for onOperationComplete:
+{"finalOperationStatus":0,"streamingOperation":"true","metricsCollectorData":{"instanceId":"fakeInstanceId","table":"fakeTableId","cluster":"fake-cluster3","zone":"us-west1-c","methodName":"Bigtable.ReadRows","clientUid":"fake-uuid"},"clientName":"nodejs-bigtable","projectId":"my-project","operationLatency":7000,"retryCount":1,"firstResponseLatency":5000}