feat: add a service ID property

This is going to be required to send OpenTelemetry metrics as our
systems will only accept metrics with the corresponding semantic
resource attribute.

Author: rowanmanning

packages/app-info/README.md

@@ -14,6 +14,7 @@ A utility to get application information (e.g. the system code) in a consistent
     * [`appInfo.cloudProvider`](#appinfocloudprovider)
     * [`appInfo.herokuAppId`](#appinfoherokuappid)
     * [`appInfo.herokuDynoId`](#appinfoherokudynoid)
+    * [`appInfo.instanceId`](#appinfoinstanceid)
     * [`appInfo.semanticConventions`](#appinfosemanticconventions)
   * [Migrating](#migrating)
   * [Contributing](#contributing)
@@ -100,6 +101,10 @@ Get the `process.env.HEROKU_DYNO_ID` which is the dyno identifier
 
 This is derived from the dyno metadata
 
+### `appInfo.instanceId`
+
+Get the ID of the instance that's running the application. This is derived from `process.env.HEROKU_DYNO_ID` if present, otherwise it will be set to a random UUID that identifies the currently running process.
+
 ### `appInfo.semanticConventions`
 
 This object contains aliases for the main `appInfo` properties that correspond to OpenTelemetry's [Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/). We use the following mapping:
@@ -109,6 +114,7 @@ This object contains aliases for the main `appInfo` properties that correspond t
   * `appInfo.semanticConventions.deployment.environment` aliases `appInfo.environment`
   * `appInfo.semanticConventions.service.name` aliases `appInfo.systemCode`
   * `appInfo.semanticConventions.service.version` aliases `appInfo.releaseVersion`
+  * `appInfo.semanticConventions.service.instance.id` aliases `appInfo.instanceId`
 
 
 ## Migrating

packages/app-info/lib/index.js

@@ -1,4 +1,5 @@
 const path = require('node:path');
+const { randomUUID } = require('node:crypto');
 
 // This package relies on Heroku and AWS Lambda environment variables.
 // Documentation for these variables is available here:
@@ -149,6 +150,14 @@ exports.herokuAppId = process.env.HEROKU_APP_ID || null;
  */
 exports.herokuDynoId = process.env.HEROKU_DYNO_ID || null;
 
+/**
+ * The ID of the running instance of the service.
+ *
+ * @readonly
+ * @type {string}
+ */
+exports.instanceId = process.env.HEROKU_DYNO_ID || randomUUID();
+
 /**
  * @type {import('@dotcom-reliability-kit/app-info').SemanticConventions}
  */
@@ -162,7 +171,10 @@ exports.semanticConventions = {
 	},
 	service: {
 		name: exports.systemCode,
-		version: exports.releaseVersion
+		version: exports.releaseVersion,
+		instance: {
+			id: exports.instanceId
+		}
 	}
 };
 

packages/app-info/test/unit/lib/index.spec.js

@@ -1,3 +1,5 @@
+jest.mock('node:crypto');
+
 describe('@dotcom-reliability-kit/app-info', () => {
 	let appInfo;
 
@@ -375,6 +377,35 @@ describe('@dotcom-reliability-kit/app-info', () => {
 		});
 	});
 
+	describe('.instanceId', () => {
+		let randomUUID;
+
+		beforeEach(() => {
+			jest.resetModules();
+			process.env.HEROKU_DYNO_ID = 'mock-heroku-dyno-id';
+			appInfo = require('../../../lib');
+		});
+
+		it('is set to `process.env.HEROKU_DYNO_ID`', () => {
+			expect(appInfo.instanceId).toBe('mock-heroku-dyno-id');
+		});
+
+		describe('when `process.env.HEROKU_DYNO_ID` is not defined', () => {
+			beforeEach(() => {
+				jest.resetModules();
+				randomUUID = require('node:crypto').randomUUID;
+				randomUUID.mockReturnValue('mock-generated-uuid');
+				delete process.env.HEROKU_DYNO_ID;
+				appInfo = require('../../../lib');
+			});
+
+			it('is set to a random UUID', () => {
+				expect(randomUUID).toHaveBeenCalledTimes(1);
+				expect(appInfo.instanceId).toBe('mock-generated-uuid');
+			});
+		});
+	});
+
 	describe('.semanticConventions', () => {
 		describe('.cloud', () => {
 			describe('.provider', () => {
@@ -418,6 +449,16 @@ describe('@dotcom-reliability-kit/app-info', () => {
 					);
 				});
 			});
+
+			describe('.instance', () => {
+				describe('.id', () => {
+					it('is an alias of `instanceId`', () => {
+						expect(appInfo.semanticConventions.service.instance.id).toBe(
+							appInfo.instanceId
+						);
+					});
+				});
+			});
 		});
 	});
 });

packages/app-info/types/index.d.ts

@@ -9,18 +9,22 @@ declare module '@dotcom-reliability-kit/app-info' {
 	export const cloudProvider: string | null;
 	export const herokuAppId: string | null;
 	export const herokuDynoId: string | null;
+	export const instanceId: string;
 
 	export type SemanticConventions = {
 		cloud: {
 			provider: string | null,
 			region: string | null
 		},
 		deployment: {
-			environment: string | null
+			environment: string
 		},
 		service: {
 			name: string | null
-			version: string | null
+			version: string | null,
+			instance: {
+				id: string
+			}
 		}
 	};
 
@@ -35,6 +39,7 @@ declare module '@dotcom-reliability-kit/app-info' {
 		cloudProvider: typeof cloudProvider,
 		herokuAppId: typeof herokuAppId,
 		herokuDynoId: typeof herokuDynoId,
+		instanceId: typeof instanceId,
 		semanticConventions: SemanticConventions
 	};