Add option to explicitly set app version for telemetry (#9388)

* Add option to explicitly set app version for telemetry

* update deps

* misc cleanup

Author: andrewbrook

common/api-review/telemetry-angular.api.md

@@ -23,6 +23,7 @@ export interface Telemetry {
 
 // @public
 export interface TelemetryOptions {
+    appVersion?: string;
     endpointUrl?: string;
 }
 

common/api-review/telemetry-react.api.md

@@ -22,6 +22,7 @@ export interface Telemetry {
 
 // @public
 export interface TelemetryOptions {
+    appVersion?: string;
     endpointUrl?: string;
 }
 

common/api-review/telemetry.api.md

@@ -31,6 +31,7 @@ export interface Telemetry {
 
 // @public
 export interface TelemetryOptions {
+    appVersion?: string;
     endpointUrl?: string;
 }
 

docs-devsite/telemetry_.telemetryoptions.md

@@ -22,8 +22,19 @@ export interface TelemetryOptions
 
 |  Property | Type | Description |
 |  --- | --- | --- |
+|  [appVersion](./telemetry_.telemetryoptions.md#telemetryoptionsappversion) | string | The version of the application. This should be a unique string that identifies the snapshot of code to be deployed, such as "1.0.2". If not specified, other default locations will be checked for an identifier. Setting a value here takes precedent over any other values. |
 |  [endpointUrl](./telemetry_.telemetryoptions.md#telemetryoptionsendpointurl) | string | The URL for the endpoint to which telemetry data should be sent, in the Open Telemetry format. By default, data will be sent to Firebase. |
 
+## TelemetryOptions.appVersion
+
+The version of the application. This should be a unique string that identifies the snapshot of code to be deployed, such as "1.0.2". If not specified, other default locations will be checked for an identifier. Setting a value here takes precedent over any other values.
+
+<b>Signature:</b>
+
+```typescript
+appVersion?: string;
+```
+
 ## TelemetryOptions.endpointUrl
 
 The URL for the endpoint to which telemetry data should be sent, in the Open Telemetry format. By default, data will be sent to Firebase.

docs-devsite/telemetry_angular.telemetryoptions.md

@@ -22,8 +22,19 @@ export interface TelemetryOptions
 
 |  Property | Type | Description |
 |  --- | --- | --- |
+|  [appVersion](./telemetry_angular.telemetryoptions.md#telemetryoptionsappversion) | string | The version of the application. This should be a unique string that identifies the snapshot of code to be deployed, such as "1.0.2". If not specified, other default locations will be checked for an identifier. Setting a value here takes precedent over any other values. |
 |  [endpointUrl](./telemetry_angular.telemetryoptions.md#telemetryoptionsendpointurl) | string | The URL for the endpoint to which telemetry data should be sent, in the Open Telemetry format. By default, data will be sent to Firebase. |
 
+## TelemetryOptions.appVersion
+
+The version of the application. This should be a unique string that identifies the snapshot of code to be deployed, such as "1.0.2". If not specified, other default locations will be checked for an identifier. Setting a value here takes precedent over any other values.
+
+<b>Signature:</b>
+
+```typescript
+appVersion?: string;
+```
+
 ## TelemetryOptions.endpointUrl
 
 The URL for the endpoint to which telemetry data should be sent, in the Open Telemetry format. By default, data will be sent to Firebase.

docs-devsite/telemetry_react.telemetryoptions.md

@@ -22,8 +22,19 @@ export interface TelemetryOptions
 
 |  Property | Type | Description |
 |  --- | --- | --- |
+|  [appVersion](./telemetry_react.telemetryoptions.md#telemetryoptionsappversion) | string | The version of the application. This should be a unique string that identifies the snapshot of code to be deployed, such as "1.0.2". If not specified, other default locations will be checked for an identifier. Setting a value here takes precedent over any other values. |
 |  [endpointUrl](./telemetry_react.telemetryoptions.md#telemetryoptionsendpointurl) | string | The URL for the endpoint to which telemetry data should be sent, in the Open Telemetry format. By default, data will be sent to Firebase. |
 
+## TelemetryOptions.appVersion
+
+The version of the application. This should be a unique string that identifies the snapshot of code to be deployed, such as "1.0.2". If not specified, other default locations will be checked for an identifier. Setting a value here takes precedent over any other values.
+
+<b>Signature:</b>
+
+```typescript
+appVersion?: string;
+```
+
 ## TelemetryOptions.endpointUrl
 
 The URL for the endpoint to which telemetry data should be sent, in the Open Telemetry format. By default, data will be sent to Firebase.

packages/telemetry/src/api.test.ts

@@ -124,7 +124,8 @@ describe('Top level API', () => {
       expect(log.body).to.equal('This is a test error');
       expect(log.attributes).to.deep.equal({
         'error.type': 'TestError',
-        'error.stack': '...stack trace...'
+        'error.stack': '...stack trace...',
+        'app.version': 'unset'
       });
     });
 
@@ -140,7 +141,8 @@ describe('Top level API', () => {
       expect(log.body).to.equal('error with no stack');
       expect(log.attributes).to.deep.equal({
         'error.type': 'Error',
-        'error.stack': 'No stack trace available'
+        'error.stack': 'No stack trace available',
+        'app.version': 'unset'
       });
     });
 
@@ -151,7 +153,9 @@ describe('Top level API', () => {
       const log = emittedLogs[0];
       expect(log.severityNumber).to.equal(SeverityNumber.ERROR);
       expect(log.body).to.equal('a string error');
-      expect(log.attributes).to.deep.equal({});
+      expect(log.attributes).to.deep.equal({
+        'app.version': 'unset'
+      });
     });
 
     it('should capture an unknown error type correctly', () => {
@@ -161,7 +165,9 @@ describe('Top level API', () => {
       const log = emittedLogs[0];
       expect(log.severityNumber).to.equal(SeverityNumber.ERROR);
       expect(log.body).to.equal('Unknown error type: number');
-      expect(log.attributes).to.deep.equal({});
+      expect(log.attributes).to.deep.equal({
+        'app.version': 'unset'
+      });
     });
 
     it('should propagate trace context', async () => {
@@ -187,6 +193,7 @@ describe('Top level API', () => {
       expect(emittedLogs[0].attributes).to.deep.equal({
         'error.type': 'TestError',
         'error.stack': '...stack trace...',
+        'app.version': 'unset',
         'logging.googleapis.com/trace': `projects/${PROJECT_ID}/traces/my-trace`,
         'logging.googleapis.com/spanId': `my-span`
       });
@@ -211,6 +218,7 @@ describe('Top level API', () => {
       expect(log.attributes).to.deep.equal({
         'error.type': 'TestError',
         'error.stack': '...stack trace...',
+        'app.version': 'unset',
         strAttr: 'string attribute',
         mapAttr: {
           boolAttr: true,
@@ -219,6 +227,24 @@ describe('Top level API', () => {
         arrAttr: [1, 2, 3]
       });
     });
+
+    it('should use explicit app version when provided', () => {
+      const telemetry = new TelemetryService(
+        fakeTelemetry.app,
+        fakeTelemetry.loggerProvider
+      );
+      telemetry.options = {
+        appVersion: '1.0.0'
+      };
+
+      captureError(telemetry, 'a string error');
+
+      expect(emittedLogs.length).to.equal(1);
+      const log = emittedLogs[0];
+      expect(log.attributes).to.deep.equal({
+        'app.version': '1.0.0'
+      });
+    });
   });
 
   describe('flush()', () => {

packages/telemetry/src/api.ts

@@ -54,7 +54,13 @@ export function getTelemetry(
     TELEMETRY_TYPE
   );
   const identifier = options?.endpointUrl || '';
-  return telemetryProvider.getImmediate({ identifier });
+  const telemetry: TelemetryService = telemetryProvider.getImmediate({
+    identifier
+  });
+  if (options) {
+    telemetry.options = options;
+  }
+  return telemetry;
 }
 
 /**
@@ -72,20 +78,27 @@ export function captureError(
   attributes?: AnyValueMap
 ): void {
   const logger = telemetry.loggerProvider.getLogger('error-logger');
+  const customAttributes = attributes || {};
 
+  // Add trace metadata
   const activeSpanContext = trace.getActiveSpan()?.spanContext();
-  const traceAttributes = {} as AnyValueMap;
   if (telemetry.app.options.projectId && activeSpanContext?.traceId) {
-    traceAttributes[
+    customAttributes[
       'logging.googleapis.com/trace'
     ] = `projects/${telemetry.app.options.projectId}/traces/${activeSpanContext.traceId}`;
     if (activeSpanContext?.spanId) {
-      traceAttributes['logging.googleapis.com/spanId'] =
+      customAttributes['logging.googleapis.com/spanId'] =
         activeSpanContext.spanId;
     }
   }
 
-  const customAttributes = attributes || {};
+  // Add app version metadata
+  let appVersion = 'unset';
+  // TODO: implement app version fallback logic
+  if ((telemetry as TelemetryService).options?.appVersion) {
+    appVersion = (telemetry as TelemetryService).options!.appVersion!;
+  }
+  customAttributes['app.version'] = appVersion;
 
   if (error instanceof Error) {
     logger.emit({
@@ -94,27 +107,20 @@ export function captureError(
       attributes: {
         'error.type': error.name || 'Error',
         'error.stack': error.stack || 'No stack trace available',
-        ...traceAttributes,
         ...customAttributes
       }
     });
   } else if (typeof error === 'string') {
     logger.emit({
       severityNumber: SeverityNumber.ERROR,
       body: error,
-      attributes: {
-        ...traceAttributes,
-        ...customAttributes
-      }
+      attributes: customAttributes
     });
   } else {
     logger.emit({
       severityNumber: SeverityNumber.ERROR,
       body: `Unknown error type: ${typeof error}`,
-      attributes: {
-        ...traceAttributes,
-        ...customAttributes
-      }
+      attributes: customAttributes
     });
   }
 }

packages/telemetry/src/public-types.ts

@@ -46,4 +46,11 @@ export interface TelemetryOptions {
    * By default, data will be sent to Firebase.
    */
   endpointUrl?: string;
+
+  /**
+   * The version of the application. This should be a unique string that identifies the snapshot of
+   * code to be deployed, such as "1.0.2". If not specified, other default locations will be checked
+   * for an identifier. Setting a value here takes precedent over any other values.
+   */
+  appVersion?: string;
 }

packages/telemetry/src/service.ts

@@ -16,13 +16,23 @@
  */
 
 import { _FirebaseService, FirebaseApp } from '@firebase/app';
-import { Telemetry } from './public-types';
+import { Telemetry, TelemetryOptions } from './public-types';
 import { LoggerProvider } from '@opentelemetry/sdk-logs';
 
 export class TelemetryService implements Telemetry, _FirebaseService {
+  private _options?: TelemetryOptions;
+
   constructor(public app: FirebaseApp, public loggerProvider: LoggerProvider) {}
 
   _delete(): Promise<void> {
     return Promise.resolve();
   }
+
+  set options(optionsToSet: TelemetryOptions) {
+    this._options = optionsToSet;
+  }
+
+  get options(): TelemetryOptions | undefined {
+    return this._options;
+  }
 }