Normalize getTelemetry initialization

Author: andrewbrook

packages/telemetry/package.json

@@ -70,7 +70,6 @@
   },
   "dependencies": {
     "@firebase/component": "0.7.0",
-    "@firebase/util": "1.13.0",
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/api-logs": "0.203.0",
     "@opentelemetry/exporter-logs-otlp-http": "0.203.0",

packages/telemetry/src/api.test.ts

@@ -25,7 +25,17 @@ import {
   SimpleSpanProcessor,
   WebTracerProvider
 } from '@opentelemetry/sdk-trace-web';
-import { captureError, flush } from './api';
+import {
+  FirebaseApp,
+  initializeApp,
+  _registerComponent,
+  _addOrOverwriteComponent
+} from '@firebase/app';
+import { Component, ComponentType } from '@firebase/component';
+import { FirebaseAppCheckInternal } from '@firebase/app-check-interop-types';
+import { captureError, flush, getTelemetry } from './api';
+import { TelemetryService } from './service';
+import { registerTelemetry } from './register';
 
 const PROJECT_ID = 'my-project';
 const APP_ID = 'my-appid';
@@ -65,6 +75,33 @@ describe('Top level API', () => {
     emittedLogs.length = 0;
   });
 
+  describe('getTelemetry()', () => {
+    it('works without options', () => {
+      expect(getTelemetry(getFakeApp())).to.be.instanceOf(TelemetryService);
+      // Two instances are the same
+      expect(getTelemetry(getFakeApp())).to.equal(getTelemetry(getFakeApp()));
+    });
+
+    it('works with options: no endpointUrl', () => {
+      expect(getTelemetry(getFakeApp(), {})).to.equal(
+        getTelemetry(getFakeApp())
+      );
+    });
+
+    it('works with options: endpointUrl set', () => {
+      const app = getFakeApp();
+      expect(getTelemetry(app, { endpointUrl: 'http://endpoint1' })).to.equal(
+        getTelemetry(app, { endpointUrl: 'http://endpoint1' })
+      );
+      expect(
+        getTelemetry(app, { endpointUrl: 'http://endpoint1' })
+      ).not.to.equal(getTelemetry(app, { endpointUrl: 'http://endpoint2' }));
+      expect(
+        getTelemetry(app, { endpointUrl: 'http://endpoint1' })
+      ).not.to.equal(getTelemetry(app, {}));
+    });
+  });
+
   describe('captureError()', () => {
     it('should capture an Error object correctly', () => {
       const error = new Error('This is a test error');
@@ -189,3 +226,32 @@ describe('Top level API', () => {
     });
   });
 });
+
+function getFakeApp(): FirebaseApp {
+  registerTelemetry();
+  _registerComponent(
+    new Component(
+      'app-check-internal',
+      () => {
+        return {} as FirebaseAppCheckInternal;
+      },
+      ComponentType.PUBLIC
+    )
+  );
+  const app = initializeApp({});
+  _addOrOverwriteComponent(
+    app,
+    //@ts-ignore
+    new Component(
+      'heartbeat',
+      // @ts-ignore
+      () => {
+        return {
+          triggerHeartbeat: () => {}
+        };
+      },
+      ComponentType.PUBLIC
+    )
+  );
+  return app;
+}

packages/telemetry/src/api.ts

@@ -16,13 +16,13 @@
  */
 
 import { _getProvider, FirebaseApp, getApp } from '@firebase/app';
-import { deepEqual } from '@firebase/util';
 import { TELEMETRY_TYPE } from './constants';
 import { Telemetry, TelemetryOptions } from './public-types';
 import { Provider } from '@firebase/component';
 import { AnyValueMap, SeverityNumber } from '@opentelemetry/api-logs';
 import { trace } from '@opentelemetry/api';
 import { TelemetryService } from './service';
+import { encodeInstanceIdentifier } from './helpers';
 
 declare module '@firebase/component' {
   interface NameServiceMapping {
@@ -50,25 +50,13 @@ export function getTelemetry(
   app: FirebaseApp = getApp(),
   options?: TelemetryOptions
 ): Telemetry {
-  // Dependencies
   const telemetryProvider: Provider<'telemetry'> = _getProvider(
     app,
     TELEMETRY_TYPE
   );
-
-  if (telemetryProvider.isInitialized()) {
-    const initialOptions = telemetryProvider.getOptions();
-    if (
-      (!initialOptions && !options) ||
-      (initialOptions && options && deepEqual(initialOptions, options))
-    ) {
-      return telemetryProvider.getImmediate();
-    }
-    throw new Error('Firebase Telemetry is already initialized');
-  }
-
-  telemetryProvider.initialize({ options });
-  return telemetryProvider.getImmediate();
+  const finalOptions: TelemetryOptions = options || {};
+  const identifier = encodeInstanceIdentifier(finalOptions);
+  return telemetryProvider.getImmediate({ identifier });
 }
 
 /**

packages/telemetry/src/helpers.test.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * 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
+ *
+ *   http://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 { expect } from 'chai';
+import { encodeInstanceIdentifier, decodeInstanceIdentifier } from './helpers';
+import { TelemetryOptions } from './public-types';
+
+describe('Identifier encoding/decoding', () => {
+  it('encodes/decodes empty options', () => {
+    const encoded = encodeInstanceIdentifier({});
+    const decoded = decodeInstanceIdentifier(encoded);
+    expect(decoded).to.deep.equal({});
+  });
+
+  it('encodes/decodes full options', () => {
+    const options: TelemetryOptions = {
+      endpointUrl: 'http://myendpoint'
+    };
+    const encoded = encodeInstanceIdentifier(options);
+    const decoded = decodeInstanceIdentifier(encoded);
+    expect(decoded).to.deep.equal(options);
+  });
+});

packages/telemetry/src/helpers.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * 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
+ *
+ *   http://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 { TelemetryOptions } from './public-types';
+
+/**
+ * Encodes {@link TelemetryOptions} into a string that will be used to uniquely identify
+ * {@link Telemetry} instances by endpoint URL.
+ *
+ * @internal
+ */
+export function encodeInstanceIdentifier(options: TelemetryOptions): string {
+  return options.endpointUrl || '';
+}
+
+/**
+ * Decodes an instance identifier string into {@link TelemetryOptions}.
+ *
+ * @internal
+ */
+export function decodeInstanceIdentifier(identifier: string): TelemetryOptions {
+  if (identifier) {
+    return {
+      endpointUrl: identifier
+    };
+  }
+  return {};
+}

packages/telemetry/src/register.node.ts

@@ -21,15 +21,20 @@ import { TELEMETRY_TYPE } from './constants';
 import { name, version } from '../package.json';
 import { TelemetryService } from './service';
 import { createLoggerProvider } from './logging/logger-provider';
-import { TelemetryOptions } from './public-types';
+import { decodeInstanceIdentifier } from './helpers';
 
 export function registerTelemetry(): void {
   _registerComponent(
     new Component(
       TELEMETRY_TYPE,
-      (container, { options }: { options?: TelemetryOptions }) => {
+      (container, { instanceIdentifier }) => {
+        if (instanceIdentifier === undefined) {
+          throw new Error('TelemetryService instance identifier is undefined');
+        }
+
+        const options = decodeInstanceIdentifier(instanceIdentifier);
         // TODO: change to default endpoint once it exists
-        const endpointUrl = options?.endpointUrl || 'http://localhost';
+        const endpointUrl = options.endpointUrl || 'http://localhost';
 
         // getImmediate for FirebaseApp will always succeed
         const app = container.getProvider('app').getImmediate();
@@ -39,7 +44,7 @@ export function registerTelemetry(): void {
         return new TelemetryService(app, loggerProvider, appCheckProvider);
       },
       ComponentType.PUBLIC
-    )
+    ).setMultipleInstances(true)
   );
 
   registerVersion(name, version, 'node');

packages/telemetry/src/register.ts

@@ -21,15 +21,20 @@ import { TELEMETRY_TYPE } from './constants';
 import { name, version } from '../package.json';
 import { TelemetryService } from './service';
 import { createLoggerProvider } from './logging/logger-provider';
-import { TelemetryOptions } from './public-types';
+import { decodeInstanceIdentifier } from './helpers';
 
 export function registerTelemetry(): void {
   _registerComponent(
     new Component(
       TELEMETRY_TYPE,
-      (container, { options }: { options?: TelemetryOptions }) => {
+      (container, { instanceIdentifier }) => {
+        if (instanceIdentifier === undefined) {
+          throw new Error('TelemetryService instance identifier is undefined');
+        }
+
+        const options = decodeInstanceIdentifier(instanceIdentifier);
         // TODO: change to default endpoint once it exists
-        const endpointUrl = options?.endpointUrl || 'http://localhost';
+        const endpointUrl = options.endpointUrl || 'http://localhost';
 
         // getImmediate for FirebaseApp will always succeed
         const app = container.getProvider('app').getImmediate();
@@ -39,7 +44,7 @@ export function registerTelemetry(): void {
         return new TelemetryService(app, loggerProvider, appCheckProvider);
       },
       ComponentType.PUBLIC
-    )
+    ).setMultipleInstances(true)
   );
 
   registerVersion(name, version);