fix: move tracing config into a new module

This also deprecates the top-level `authorizationHeader` option in
favour of one under `tracing`. This is because we won't be using the
same header for metrics.

Author: rowanmanning

packages/opentelemetry/README.md

@@ -20,6 +20,7 @@ An [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) client
     * [`options.authorizationHeader`](#optionsauthorizationheader)
     * [`options.tracing`](#optionstracing)
     * [`options.tracing.endpoint`](#optionstracingendpoint)
+    * [`options.tracing.authorizationHeader`](#optionstracingauthorizationheader)
     * [`options.tracing.samplePercentage`](#optionstracingsamplepercentage)
     * [`OTEL_` environment variables](#otel_-environment-variables)
 * [Contributing](#contributing)
@@ -209,10 +210,7 @@ setupOpenTelemetry({
 
 #### `options.authorizationHeader`
 
-Set the [`Authorization` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) in requests to the OpenTelemetry collector. Defaults to `undefined`.
-
-**Environment variable:** `OPENTELEMETRY_AUTHORIZATION_HEADER`<br/>
-**Option:** `authorizationHeader` (`String`)
+**Deprecated**. This will still work but has been replaced with [`options.tracing.authorizationHeader`](#optionstracingauthorizationheader), which is now the preferred way to set this option.
 
 #### `options.tracing`
 
@@ -225,6 +223,13 @@ A URL to send OpenTelemetry traces to. E.g. `http://localhost:4318/v1/traces`. D
 **Environment variable:** `OPENTELEMETRY_TRACING_ENDPOINT`<br/>
 **Option:** `tracing.endpoint` (`String`)
 
+#### `options.tracing.authorizationHeader`
+
+Set the [`Authorization` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) in requests to the OpenTelemetry tracing collector. Defaults to `undefined`.
+
+**Environment variable:** `OPENTELEMETRY_AUTHORIZATION_HEADER`<br/>
+**Option:** `tracing.authorizationHeader` (`String`)
+
 #### `options.tracing.samplePercentage`
 
 The percentage of traces to send to the exporter. Defaults to `5` which means that 5% of traces will be exported.

packages/opentelemetry/lib/config/tracing.js

@@ -0,0 +1,74 @@
+const {
+	OTLPTraceExporter
+} = require('@opentelemetry/exporter-trace-otlp-proto');
+const {
+	NoopSpanProcessor,
+	TraceIdRatioBasedSampler
+} = require('@opentelemetry/sdk-trace-base');
+const logger = require('@dotcom-reliability-kit/logger');
+const { TRACING_USER_AGENT } = require('./user-agents');
+
+const DEFAULT_SAMPLE_PERCENTAGE = 5;
+
+/**
+ * @typedef {object} TracingOptions
+ * @property {string} [authorizationHeader]
+ *     The HTTP `Authorization` header to send with OpenTelemetry tracing requests.
+ * @property {string} [endpoint]
+ *     The URL to send OpenTelemetry trace segments to, for example http://localhost:4318/v1/traces.
+ * @property {number} [samplePercentage]
+ *     What percentage of traces should be sent onto the collector.
+ */
+
+/**
+ * Create an OpenTelemetry tracing configuration.
+ *
+ * @param {TracingOptions} options
+ * @returns {Partial<import('@opentelemetry/sdk-node').NodeSDKConfiguration>}
+ */
+exports.createTracingConfig = function createTracingConfig(options) {
+	/** @type {Partial<import('@opentelemetry/sdk-node').NodeSDKConfiguration>} */
+	const config = {};
+
+	// If we have an OpenTelemetry tracing endpoint then set it up,
+	// otherwise we pass a noop span processor so that nothing is exported
+	if (options?.endpoint) {
+		const headers = {
+			'user-agent': TRACING_USER_AGENT
+		};
+		if (options.authorizationHeader) {
+			headers.authorization = options.authorizationHeader;
+		}
+		config.traceExporter = new OTLPTraceExporter({
+			url: options.endpoint,
+			headers
+		});
+
+		// Sample traces
+		let samplePercentage = DEFAULT_SAMPLE_PERCENTAGE;
+		if (options.samplePercentage && !Number.isNaN(options.samplePercentage)) {
+			samplePercentage = options.samplePercentage;
+		}
+		const sampleRatio = samplePercentage / 100;
+		config.sampler = new TraceIdRatioBasedSampler(sampleRatio);
+
+		logger.info({
+			event: 'OTEL_TRACE_STATUS',
+			message: `OpenTelemetry tracing is enabled and exporting to endpoint ${options.endpoint}`,
+			enabled: true,
+			endpoint: options.endpoint,
+			samplePercentage
+		});
+	} else {
+		logger.warn({
+			event: 'OTEL_TRACE_STATUS',
+			message:
+				'OpenTelemetry tracing is disabled because no tracing endpoint was set',
+			enabled: false,
+			endpoint: null
+		});
+		config.spanProcessor = new NoopSpanProcessor();
+	}
+
+	return config;
+};

packages/opentelemetry/lib/index.js

@@ -1,42 +1,32 @@
 const { createInstrumentationConfig } = require('./config/instrumentations');
 const { createResourceConfig } = require('./config/resource');
+const { createTracingConfig } = require('./config/tracing');
 const { diag, DiagLogLevel } = require('@opentelemetry/api');
 const opentelemetrySDK = require('@opentelemetry/sdk-node');
-const {
-	OTLPTraceExporter
-} = require('@opentelemetry/exporter-trace-otlp-proto');
-const {
-	NoopSpanProcessor,
-	TraceIdRatioBasedSampler
-} = require('@opentelemetry/sdk-trace-base');
 const logger = require('@dotcom-reliability-kit/logger');
-const { TRACING_USER_AGENT } = require('./config/user-agents');
 
-const DEFAULT_SAMPLE_PERCENTAGE = 5;
+/**
+ * @typedef {import('./config/tracing').TracingOptions} TracingOptions
+ */
 
 /**
  * @typedef {object} Options
  * @property {string} [authorizationHeader]
- *      The HTTP `Authorization` header to send with OpenTelemetry requests.
+ *      [DEPRECATED] The HTTP `Authorization` header to send with OpenTelemetry requests. Use `tracing.authorizationHeader` instead.
  * @property {TracingOptions} [tracing]
  *      Configuration options for OpenTelemetry tracing.
  */
 
-/**
- * @typedef {object} TracingOptions
- * @property {string} endpoint
- *     The URL to send OpenTelemetry trace segments to, for example http://localhost:4318/v1/traces.
- * @property {number} [samplePercentage]
- *     What percentage of traces should be sent onto the collector.
- */
-
 /**
  * Set up OpenTelemetry tracing.
  *
  * @param {Options} [options]
  *      OpenTelemetry configuration options.
  */
-function setupOpenTelemetry({ authorizationHeader, tracing } = {}) {
+function setupOpenTelemetry({
+	authorizationHeader,
+	tracing: tracingOptions
+} = {}) {
 	// 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.
@@ -59,54 +49,18 @@ function setupOpenTelemetry({ authorizationHeader, tracing } = {}) {
 		DiagLogLevel.INFO
 	);
 
-	// Construct the OpenTelemetry SDK configuration
-	/** @type {opentelemetrySDK.NodeSDKConfiguration} */
-	const openTelemetryConfig = {};
-	openTelemetryConfig.instrumentations = createInstrumentationConfig();
-	openTelemetryConfig.resource = createResourceConfig();
-
-	// If we have an OpenTelemetry tracing endpoint then set it up,
-	// otherwise we pass a noop span processor so that nothing is exported
-	if (tracing?.endpoint) {
-		const headers = {
-			'user-agent': TRACING_USER_AGENT
-		};
-		if (authorizationHeader) {
-			headers.authorization = authorizationHeader;
-		}
-		openTelemetryConfig.traceExporter = new OTLPTraceExporter({
-			url: tracing.endpoint,
-			headers
-		});
-
-		// Sample traces
-		let samplePercentage = DEFAULT_SAMPLE_PERCENTAGE;
-		if (tracing.samplePercentage && !Number.isNaN(tracing.samplePercentage)) {
-			samplePercentage = tracing.samplePercentage;
-		}
-		const sampleRatio = samplePercentage / 100;
-		openTelemetryConfig.sampler = new TraceIdRatioBasedSampler(sampleRatio);
-
-		logger.info({
-			event: 'OTEL_TRACE_STATUS',
-			message: `OpenTelemetry tracing is enabled and exporting to endpoint ${tracing.endpoint}`,
-			enabled: true,
-			endpoint: tracing.endpoint,
-			samplePercentage
-		});
-	} else {
-		logger.warn({
-			event: 'OTEL_TRACE_STATUS',
-			message:
-				'OpenTelemetry tracing is disabled because no tracing endpoint was set',
-			enabled: false,
-			endpoint: null
-		});
-		openTelemetryConfig.spanProcessor = new NoopSpanProcessor();
-	}
-
 	// Set up and start OpenTelemetry
-	const sdk = new opentelemetrySDK.NodeSDK(openTelemetryConfig);
+	const sdk = new opentelemetrySDK.NodeSDK({
+		// Configurations we set regardless of whether we're using tracing
+		instrumentations: createInstrumentationConfig(),
+		resource: createResourceConfig(),
+
+		// Add tracing-specific configurations
+		...createTracingConfig({
+			authorizationHeader,
+			...tracingOptions
+		})
+	});
 	sdk.start();
 }
 

packages/opentelemetry/setup.js

@@ -4,6 +4,7 @@ const setupOpenTelemetry = require('./lib/index.js');
 let tracing = undefined;
 if (process.env.OPENTELEMETRY_TRACING_ENDPOINT) {
 	tracing = {
+		authorizationHeader: process.env.OPENTELEMETRY_AUTHORIZATION_HEADER,
 		endpoint: process.env.OPENTELEMETRY_TRACING_ENDPOINT,
 		samplePercentage: process.env.OPENTELEMETRY_TRACING_SAMPLE_PERCENTAGE
 			? Number(process.env.OPENTELEMETRY_TRACING_SAMPLE_PERCENTAGE)
@@ -12,6 +13,5 @@ if (process.env.OPENTELEMETRY_TRACING_ENDPOINT) {
 }
 
 setupOpenTelemetry({
-	authorizationHeader: process.env.OPENTELEMETRY_AUTHORIZATION_HEADER,
 	tracing
 });

packages/opentelemetry/test/unit/lib/config/tracing.spec.js

@@ -0,0 +1,144 @@
+jest.mock('@opentelemetry/exporter-trace-otlp-proto');
+jest.mock('@opentelemetry/sdk-trace-base');
+jest.mock('@dotcom-reliability-kit/logger');
+jest.mock('../../../../lib/config/user-agents', () => ({
+	TRACING_USER_AGENT: 'mock-tracing-user-agent'
+}));
+
+const logger = require('@dotcom-reliability-kit/logger');
+const {
+	OTLPTraceExporter
+} = require('@opentelemetry/exporter-trace-otlp-proto');
+const {
+	NoopSpanProcessor,
+	TraceIdRatioBasedSampler
+} = require('@opentelemetry/sdk-trace-base');
+const { createTracingConfig } = require('../../../../lib/config/tracing');
+
+describe('@dotcom-reliability-kit/opentelemetry/lib/config/tracing', () => {
+	it('exports a function', () => {
+		expect(typeof createTracingConfig).toBe('function');
+	});
+
+	describe('createTracingConfig(options)', () => {
+		let config;
+
+		beforeAll(() => {
+			config = createTracingConfig({
+				authorizationHeader: 'mock-auth-header',
+				endpoint: 'mock-endpoint',
+				samplePercentage: 10
+			});
+		});
+
+		it('creates a trace exporter', () => {
+			expect(OTLPTraceExporter).toHaveBeenCalledTimes(1);
+			expect(OTLPTraceExporter).toHaveBeenCalledWith({
+				url: 'mock-endpoint',
+				headers: {
+					authorization: 'mock-auth-header',
+					'user-agent': 'mock-tracing-user-agent'
+				}
+			});
+		});
+
+		it('creates a ratio-based trace sampler', () => {
+			expect(TraceIdRatioBasedSampler).toHaveBeenCalledTimes(1);
+			expect(TraceIdRatioBasedSampler).toHaveBeenCalledWith(0.1);
+		});
+
+		it('does not create a noop span processor', () => {
+			expect(NoopSpanProcessor).toHaveBeenCalledTimes(0);
+		});
+
+		it('logs that tracing is enabled', () => {
+			expect(logger.info).toHaveBeenCalledWith({
+				enabled: true,
+				endpoint: 'mock-endpoint',
+				event: 'OTEL_TRACE_STATUS',
+				message:
+					'OpenTelemetry tracing is enabled and exporting to endpoint mock-endpoint',
+				samplePercentage: 10
+			});
+		});
+
+		it('returns the configuration', () => {
+			expect(config).toEqual({
+				traceExporter: OTLPTraceExporter.mock.instances[0],
+				sampler: TraceIdRatioBasedSampler.mock.instances[0]
+			});
+		});
+
+		describe('when options.authorizationHeader is not defined', () => {
+			beforeAll(() => {
+				OTLPTraceExporter.mockClear();
+				config = createTracingConfig({
+					endpoint: 'mock-endpoint',
+					samplePercentage: 10
+				});
+			});
+
+			it('creates a trace exporter without an authorization header', () => {
+				expect(OTLPTraceExporter).toHaveBeenCalledTimes(1);
+				expect(OTLPTraceExporter).toHaveBeenCalledWith({
+					url: 'mock-endpoint',
+					headers: {
+						'user-agent': 'mock-tracing-user-agent'
+					}
+				});
+			});
+		});
+
+		describe('when options.samplePercentage is not defined', () => {
+			beforeAll(() => {
+				TraceIdRatioBasedSampler.mockClear();
+				config = createTracingConfig({
+					authorizationHeader: 'mock-auth-header',
+					endpoint: 'mock-endpoint'
+				});
+			});
+
+			it('creates a ratio-based trace sampler with a default sample ratio', () => {
+				expect(TraceIdRatioBasedSampler).toHaveBeenCalledTimes(1);
+				expect(TraceIdRatioBasedSampler).toHaveBeenCalledWith(0.05);
+			});
+		});
+
+		describe('when options.endpoint is not defined', () => {
+			beforeAll(() => {
+				OTLPTraceExporter.mockClear();
+				TraceIdRatioBasedSampler.mockClear();
+				config = createTracingConfig({});
+			});
+
+			it('does not creates a trace exporter', () => {
+				expect(OTLPTraceExporter).toHaveBeenCalledTimes(0);
+			});
+
+			it('does not create a ratio-based trace sampler', () => {
+				expect(TraceIdRatioBasedSampler).toHaveBeenCalledTimes(0);
+			});
+
+			it('creates a noop span processor', () => {
+				expect(NoopSpanProcessor).toHaveBeenCalledTimes(1);
+				expect(NoopSpanProcessor).toHaveBeenCalledWith();
+			});
+
+			it('logs that tracing is disabled', () => {
+				expect(logger.warn).toHaveBeenCalledWith({
+					enabled: false,
+					endpoint: null,
+					event: 'OTEL_TRACE_STATUS',
+					message:
+						'OpenTelemetry tracing is disabled because no tracing endpoint was set'
+				});
+			});
+
+			it('returns the configuration', () => {
+				expect(config).toEqual({
+					spanProcessor: NoopSpanProcessor.mock.instances[0]
+				});
+			});
+		});
+	});
+});