feat: Add the MetricsTracerFactory for client side metrics

common/client-side-metrics-attributes.ts

@@ -0,0 +1,45 @@
+// 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.
+
+/**
+ * Attributes (labels) associated with a Bigtable metric. These
+ * attributes provide context for the metric values.
+ */
+export interface Attributes {
+  projectId: string;
+  instanceId: string;
+  table: string;
+  cluster?: string | null;
+  zone?: string | null;
+  appProfileId?: string;
+  methodName: string;
+  attemptStatus?: string;
+  finalOperationStatus?: string;
+  streamingOperation?: string;
+  clientName: string;
+}
+
+/**
+ * Converts an Attributes object to a string representation.
+ * This string representation is suitable for use as labels or tags.
+ * The order of attributes in the output string is fixed:
+ * projectId;instanceId;table;cluster;zone;appProfileId;methodName;attemptStatus;finalOperationStatus;streamingOperation;clientName
+ * If an attribute is null or undefined, the empty string is used.
+ * @param {Attributes} a The Attributes object to convert.
+ * @returns A string representation of the attribute.
+ */
+export function attributesToString(a: Attributes) {
+  const p = (attribute?: string | null) => (attribute ? attribute : '');
+  return `${p(a.projectId)};${p(a.instanceId)};${p(a.table)};${p(a.cluster)};${p(a.zone)};${p(a.appProfileId)};${p(a.methodName)};${p(a.attemptStatus)};${p(a.finalOperationStatus)};${p(a.streamingOperation)};nodejs-bigtable`;
+}

common/logger.ts

@@ -0,0 +1,52 @@
+// 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.
+
+/**
+ * A simple logger interface for logging messages.  Implementations of this interface
+ * can provide various logging mechanisms (e.g., console logging, file logging, etc.).
+ */
+interface ILogger {
+  log(message: string): void;
+}
+
+/**
+ * An abstract base class that provides a logger instance. Subclasses can use this logger
+ * for logging messages.
+ */
+export abstract class WithLogger {
+  protected logger: ILogger;
+  /**
+   * @param {ILogger} logger The logger instance to be used by this object.
+   */
+  constructor(logger: ILogger) {
+    this.logger = logger;
+  }
+}
+
+/**
+ * An abstract base class that provides a logger instance and a name. Subclasses
+ * can use the logger for logging messages, incorporating the name for context.
+ */
+export abstract class WithLoggerAndName {
+  protected logger: ILogger;
+  protected name: string;
+  /**
+   * @param {ILogger} logger The logger instance to be used by this object.
+   * @param {string} name The name associated with this object.
+   */
+  constructor(logger: ILogger, name: string) {
+    this.logger = logger;
+    this.name = name;
+  }
+}

common/test-date-provider.ts

@@ -0,0 +1,56 @@
+// 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 {WithLogger} from './logger';
+
+/**
+ * A test implementation of a Date-like object.  Used for testing purposes.  It provides a
+ * getTime method that returns a pre-determined fake date value, allowing for
+ * deterministic testing of time-dependent functionality.
+ */
+class TestDateLike {
+  private fakeDate;
+  /**
+   * @param {number} fakeDate The fake date value to be returned by getTime(), in milliseconds.
+   */
+  constructor(fakeDate: number) {
+    this.fakeDate = fakeDate;
+  }
+  /**
+   * Returns the fake date value that this object was created with.
+   * @returns {number} The fake date, in milliseconds.
+   */
+  getTime() {
+    return this.fakeDate;
+  }
+}
+
+/**
+ * A test implementation of a DateProvider. Used for testing purposes. Provides
+ * a deterministic series of fake dates, with each call to getDate() returning a date 1000ms later than the last.
+ * Logs each date value returned for verification purposes.
+ */
+export class TestDateProvider extends WithLogger {
+  private dateCounter = 0;
+  /**
+   * Returns a new fake date 1000ms later than the last. Logs the date for test verification.
+   * @returns {TestDateLike} A fake date object.
+   */
+  getDate() {
+    // The test assumes exactly 1s passes between each getDate call.
+    this.dateCounter = this.dateCounter + 1000;
+    this.logger.log(`getDate call returns ${this.dateCounter.toString()} ms`);
+    return new TestDateLike(this.dateCounter);
+  }
+}

common/test-meter-provider.ts

@@ -0,0 +1,88 @@
+// 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 {WithLogger, WithLoggerAndName} from './logger';
+import {Attributes, attributesToString} from './client-side-metrics-attributes';
+
+/**
+ * A test implementation of a MeterProvider.  This MeterProvider is used for testing purposes.
+ * It doesn't send metrics to a backend, but instead logs metric updates for verification.
+ */
+export class TestMeterProvider extends WithLogger {
+  /**
+   * Returns a TestMeter, that logs metric updates for verification.
+   * @param {string} name The name of the meter.
+   * @returns {TestMeter}
+   */
+  getMeter(name: string) {
+    return new TestMeter(this.logger, name);
+  }
+}
+
+/**
+ * A test implementation of a Meter.  Used for testing purposes.  It doesn't send metrics to a backend,
+ * but instead logs metric updates for verification.
+ */
+class TestMeter extends WithLoggerAndName {
+  /**
+   * Creates a test histogram.  The TestHistogram logs when values are recorded.
+   * @param {string} instrument The name of the instrument.
+   * @returns {TestHistogram}
+   */
+  createHistogram(instrument: string) {
+    return new TestHistogram(this.logger, `${this.name}:${instrument}`);
+  }
+  /**
+   * Creates a test counter. The TestCounter logs when values are added.
+   * @param {string} instrument The name of the instrument.
+   * @returns {TestCounter}
+   */
+  createCounter(instrument: string) {
+    return new TestCounter(this.logger, `${this.name}:${instrument}`);
+  }
+}
+
+/**
+ * A test implementation of a Counter. Used for testing purposes. It doesn't send metrics to a backend,
+ * but instead logs value additions for verification.
+ */
+class TestCounter extends WithLoggerAndName {
+  /**
+   * Simulates adding a value to the counter. Logs the value and the counter name.
+   * @param {number} value The value to be added to the counter.
+   * @param {Attributes} attributes The attributes associated with the value.
+   */
+  add(value: number, attributes: Attributes) {
+    this.logger.log(
+      `Value added to counter ${this.name} = ${value.toString()} with attributes ${attributesToString(attributes)}`
+    );
+  }
+}
+
+/**
+ * A test implementation of a Histogram. Used for testing purposes. It doesn't send metrics to a backend,
+ * but instead logs recorded values for verification.
+ */
+class TestHistogram extends WithLoggerAndName {
+  /**
+   * Simulates recording a value in the histogram. Logs the value and the histogram name.
+   * @param {number} value The value to be recorded in the histogram.
+   * @param {Attributes} attributes The attributes associated with the value.
+   */
+  record(value: number, attributes: Attributes) {
+    this.logger.log(
+      `Value added to histogram ${this.name} = ${value.toString()} with attributes ${attributesToString(attributes)}`
+    );
+  }
+}

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",