feat: prevent the setup from running twice

This ensures that we can't accidentally re-instrument the code or run
the setup script multiple times, which would have some weird
consequences. This also sets us up to add host metrics, which otherwise
would have been difficult to manage.

Author: rowanmanning

packages/opentelemetry/README.md

@@ -152,6 +152,8 @@ opentelemetry.setup({ /* ... */ });
     </tr>
 </table>
 
+This method returns any SDK instances created during setup. Calling this method a second time will return the same instances without rerunning setup.
+
 ### Running in production
 
 #### Production metrics

packages/opentelemetry/lib/index.js

@@ -2,7 +2,7 @@ const { createInstrumentationConfig } = require('./config/instrumentations');
 const { createMetricsConfig } = require('./config/metrics');
 const { createResourceConfig } = require('./config/resource');
 const { createTracingConfig } = require('./config/tracing');
-const opentelemetrySDK = require('@opentelemetry/sdk-node');
+const opentelemetry = require('@opentelemetry/sdk-node');
 const logger = require('@dotcom-reliability-kit/logger');
 
 /**
@@ -23,17 +23,36 @@ const logger = require('@dotcom-reliability-kit/logger');
  *      Configuration options for OpenTelemetry tracing.
  */
 
+/**
+ * @typedef {object} Instances
+ * @property {opentelemetry.NodeSDK} sdk
+ *      A singleton instance of the OpenTelemetry Node SDK.
+ */
+
+/**
+ * Stores the singleton instances that were created during OpenTelemetry setup.
+ *
+ * @type {Instances}
+ */
+let instances;
+
 /**
  * Set up OpenTelemetry tracing.
  *
  * @param {Options} [options]
  *      OpenTelemetry configuration options.
+ * @returns {Instances}
+ *      Returns any created SDK instances.
  */
 function setupOpenTelemetry({
 	authorizationHeader,
 	metrics: metricsOptions,
 	tracing: tracingOptions
 } = {}) {
+	if (instances) {
+		return instances;
+	}
+
 	// We don't support using the built-in `OTEL_`-prefixed environment variables. We
 	// do want to know when these are used, though, so that we can easily spot when
 	// an app's use of these environment variables might be interfering.
@@ -51,31 +70,35 @@ function setupOpenTelemetry({
 	// the LOG_LEVEL environment variable) takes over. We set the
 	// OpenTelemetry log level to the maximum value that we want
 	// Reliability Kit to consider logging
-	opentelemetrySDK.api.diag.setLogger(
+	opentelemetry.api.diag.setLogger(
 		// @ts-ignore this complains because DiagLogger accepts a type
 		// of unknown whereas our logger is stricter. This is fine though,
 		// if something unknown is logged then we do our best with it.
 		// It's easier to ignore this error than fix it.
 		logger.createChildLogger({ event: 'OTEL_INTERNALS' }),
-		opentelemetrySDK.api.DiagLogLevel.INFO
+		opentelemetry.api.DiagLogLevel.INFO
 	);
 
 	// Set up and start OpenTelemetry
-	const sdk = new opentelemetrySDK.NodeSDK({
-		// Configurations we set regardless of whether we're using tracing
-		instrumentations: createInstrumentationConfig(),
-		resource: createResourceConfig(),
+	instances = {
+		sdk: new opentelemetry.NodeSDK({
+			// Configurations we set regardless of whether we're using tracing
+			instrumentations: createInstrumentationConfig(),
+			resource: createResourceConfig(),
 
-		// Add metrics-specific configurations
-		...createMetricsConfig(metricsOptions || {}),
+			// Add metrics-specific configurations
+			...createMetricsConfig(metricsOptions || {}),
 
-		// Add tracing-specific configurations
-		...createTracingConfig({
-			authorizationHeader,
-			...tracingOptions
+			// Add tracing-specific configurations
+			...createTracingConfig({
+				authorizationHeader,
+				...tracingOptions
+			})
 		})
-	});
-	sdk.start();
+	};
+	instances.sdk.start();
+
+	return instances;
 }
 
 exports.setup = setupOpenTelemetry;

packages/opentelemetry/test/unit/lib/index.spec.js

@@ -15,26 +15,49 @@ jest.mock('../../../lib/config/tracing', () => ({
 	createTracingConfig: jest.fn().mockReturnValue({ tracing: 'mock-tracing' })
 }));
 
-const {
-	createInstrumentationConfig
-} = require('../../../lib/config/instrumentations');
-const { createMetricsConfig } = require('../../../lib/config/metrics');
-const { createResourceConfig } = require('../../../lib/config/resource');
-const { createTracingConfig } = require('../../../lib/config/tracing');
-const { diag, DiagLogLevel } = require('@opentelemetry/sdk-node').api;
-const { NodeSDK } = require('@opentelemetry/sdk-node');
-const logger = require('@dotcom-reliability-kit/logger');
-
-logger.createChildLogger.mockReturnValue('mock child logger');
-DiagLogLevel.INFO = 'mock info log level';
-
-// Import the OTel function for testing
-const opentelemetry = require('../../../lib/index');
-
 describe('@dotcom-reliability-kit/opentelemetry', () => {
+	let createInstrumentationConfig;
+	let createMetricsConfig;
+	let createResourceConfig;
+	let createTracingConfig;
+	let diag;
+	let DiagLogLevel;
+	let logger;
+	let NodeSDK;
+	let opentelemetry;
+
+	// Helper function to reload all modules. We need this because the setup
+	// method stores a global singleton so it's impossible to call it multiple
+	// times with different configuration values normally. We need to do this
+	// in the tests though
+	function reloadAllModules() {
+		jest.resetModules();
+		createInstrumentationConfig =
+			require('../../../lib/config/instrumentations').createInstrumentationConfig;
+		createMetricsConfig =
+			require('../../../lib/config/metrics').createMetricsConfig;
+		createResourceConfig =
+			require('../../../lib/config/resource').createResourceConfig;
+		createTracingConfig =
+			require('../../../lib/config/tracing').createTracingConfig;
+		diag = require('@opentelemetry/sdk-node').api.diag;
+		DiagLogLevel = require('@opentelemetry/sdk-node').api.DiagLogLevel;
+		NodeSDK = require('@opentelemetry/sdk-node').NodeSDK;
+		logger = require('@dotcom-reliability-kit/logger');
+
+		logger.createChildLogger.mockReturnValue('mock child logger');
+		DiagLogLevel.INFO = 'mock info log level';
+
+		opentelemetry = require('../../../lib/index');
+	}
+
+	beforeEach(reloadAllModules);
+
 	describe('.setup(options)', () => {
-		beforeAll(() => {
-			opentelemetry.setup({
+		let instances;
+
+		beforeEach(() => {
+			instances = opentelemetry.setup({
 				tracing: {
 					endpoint: 'mock-tracing-endpoint',
 					samplePercentage: 137
@@ -93,9 +116,16 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 			expect(NodeSDK.prototype.start).toHaveBeenCalledTimes(1);
 		});
 
+		it('returns the SDK instance', () => {
+			expect(instances).toEqual({
+				sdk: NodeSDK.mock.instances[0]
+			});
+		});
+
 		describe('when no options are set', () => {
-			beforeAll(() => {
+			beforeEach(() => {
 				NodeSDK.mockClear();
+				reloadAllModules();
 				opentelemetry.setup();
 			});
 
@@ -111,8 +141,9 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 		});
 
 		describe('when an authorization header is passed into the root options (deprecated)', () => {
-			beforeAll(() => {
+			beforeEach(() => {
 				createTracingConfig.mockReset();
+				reloadAllModules();
 				opentelemetry.setup({
 					authorizationHeader: 'mock-authorization-header-root',
 					tracing: {
@@ -131,8 +162,9 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 		});
 
 		describe('when an authorization header is passed into the tracing options', () => {
-			beforeAll(() => {
+			beforeEach(() => {
 				createTracingConfig.mockReset();
+				reloadAllModules();
 				opentelemetry.setup({
 					tracing: {
 						authorizationHeader: 'mock-authorization-header-tracing',
@@ -151,8 +183,9 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 		});
 
 		describe('when an authorization header is passed into both the root options (deprecated) and tracing options', () => {
-			beforeAll(() => {
+			beforeEach(() => {
 				createTracingConfig.mockReset();
+				reloadAllModules();
 				opentelemetry.setup({
 					authorizationHeader: 'mock-authorization-header-root',
 					tracing: {
@@ -172,8 +205,9 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 		});
 
 		describe('when OTEL_ environment variables are defined', () => {
-			beforeAll(() => {
+			beforeEach(() => {
 				process.env.OTEL_MOCK = 'mock';
+				reloadAllModules();
 				opentelemetry.setup();
 			});
 
@@ -185,5 +219,39 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 				});
 			});
 		});
+
+		describe('when called a second time', () => {
+			let returnValue1;
+			let returnValue2;
+
+			beforeEach(() => {
+				reloadAllModules();
+				returnValue1 = opentelemetry.setup({
+					tracing: {
+						endpoint: 'mock-tracing-endpoint',
+						samplePercentage: 137
+					},
+					metrics: {
+						endpoint: 'mock-metrics-endpoint'
+					}
+				});
+				returnValue2 = opentelemetry.setup();
+			});
+
+			it('instantiates and starts the OpenTelemetry Node SDK once only', () => {
+				expect(NodeSDK).toHaveBeenCalledTimes(1);
+				expect(NodeSDK).toHaveBeenCalledWith({
+					instrumentations: 'mock-instrumentations',
+					resource: 'mock-resource',
+					tracing: 'mock-tracing',
+					metrics: 'mock-metrics'
+				});
+				expect(NodeSDK.prototype.start).toHaveBeenCalledTimes(1);
+			});
+
+			it('returns the same instances on each call', () => {
+				expect(returnValue1).toStrictEqual(returnValue2);
+			});
+		});
 	});
 });