feat: add the ability to get metrics meters

This allows apps to define custom metrics in a safe way that ensures
Reliability Kit was the thing that set up OpenTelemetry.

Author: rowanmanning

packages/opentelemetry/README.md

@@ -11,6 +11,7 @@ An [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) client
     * [Automated setup with `--require`](#automated-setup-with---require)
     * [Automated setup with `require()`](#automated-setup-with-require)
     * [Manual setup](#manual-setup)
+  * [Sending custom metrics](#sending-custom-metrics)
   * [Running in production](#running-in-production)
     * [Production metrics](#production-metrics)
     * [Production tracing](#production-tracing)
@@ -154,6 +155,31 @@ opentelemetry.setup({ /* ... */ });
 
 This method returns any SDK instances created during setup. Calling this method a second time will return the same instances without rerunning setup.
 
+### Sending custom metrics
+
+Many metrics are taken care of by OpenTelemetry's auto-instrumentation (e.g. HTTP request data), but you sometimes need to send your own metrics. We expose the OpenTelemetry `getMeter` method ([documentation](https://opentelemetry.io/docs/languages/js/instrumentation/#acquiring-a-meter)) which allows you to do this.
+
+In your code, load in the `getMeter` function:
+
+```js
+import getMeter from '@dotcom-reliability-kit/opentelemetry';
+// or
+const { getMeter } = require('@dotcom-reliability-kit/opentelemetry');
+```
+
+You can now use it in the same way as the built-in OpenTelemetry equivalent. For more information, see the [OpenTelemetry Meter documentation](https://opentelemetry.io/docs/specs/otel/metrics/api/#meter).
+
+```js
+// Assumes that `app` is an Express application instance
+const meter = getMeter('my-app');
+const hitCounter = meter.createCounter('my-app.hits');
+
+app.get('/', (request, response) => {
+    hitCounter.add(1);
+    response.send('Thanks for visiting');
+});
+```
+
 ### Running in production
 
 #### Production metrics

packages/opentelemetry/lib/index.js

@@ -32,7 +32,7 @@ const logger = require('@dotcom-reliability-kit/logger');
 /**
  * Stores the singleton instances that were created during OpenTelemetry setup.
  *
- * @type {Instances}
+ * @type {Instances | undefined}
  */
 let instances;
 
@@ -101,4 +101,31 @@ function setupOpenTelemetry({
 	return instances;
 }
 
+/**
+ * Get a metrics meter from the configured OpenTelemetry SDK.
+ *
+ * @param {string} name
+ *     The meter name.
+ * @param {string} [version]
+ *     The meter version.
+ * @param {opentelemetry.api.MeterOptions} [options]
+ *     Additional configuration options for the meter.
+ * @returns {opentelemetry.api.Meter}
+ *      Returns a metrics meter.
+ */
+function getMeter(name, version, options) {
+	if (!instances) {
+		throw Object.assign(
+			new Error(
+				'Reliability Kit OpenTelemetry must be set up before meters can be created. See the setup guide for more information: https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/opentelemetry#setup'
+			),
+			{
+				code: 'OTEL_MISSING_SETUP'
+			}
+		);
+	}
+	return opentelemetry.api.metrics.getMeter(name, version, options);
+}
+
 exports.setup = setupOpenTelemetry;
+exports.getMeter = getMeter;

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

@@ -20,8 +20,7 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 	let createMetricsConfig;
 	let createResourceConfig;
 	let createTracingConfig;
-	let diag;
-	let DiagLogLevel;
+	let api;
 	let logger;
 	let NodeSDK;
 	let opentelemetry;
@@ -40,13 +39,12 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 			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;
+		api = require('@opentelemetry/sdk-node').api;
 		NodeSDK = require('@opentelemetry/sdk-node').NodeSDK;
 		logger = require('@dotcom-reliability-kit/logger');
 
 		logger.createChildLogger.mockReturnValue('mock child logger');
-		DiagLogLevel.INFO = 'mock info log level';
+		api.DiagLogLevel.INFO = 'mock info log level';
 
 		opentelemetry = require('../../../lib/index');
 	}
@@ -73,8 +71,8 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 			expect(logger.createChildLogger).toHaveBeenCalledWith({
 				event: 'OTEL_INTERNALS'
 			});
-			expect(diag.setLogger).toHaveBeenCalledTimes(1);
-			expect(diag.setLogger).toHaveBeenCalledWith(
+			expect(api.diag.setLogger).toHaveBeenCalledTimes(1);
+			expect(api.diag.setLogger).toHaveBeenCalledWith(
 				'mock child logger',
 				'mock info log level'
 			);
@@ -254,4 +252,44 @@ describe('@dotcom-reliability-kit/opentelemetry', () => {
 			});
 		});
 	});
+
+	describe('.getMeter(name, version, options)', () => {
+		let meter;
+
+		beforeEach(() => {
+			reloadAllModules();
+			api.metrics.getMeter.mockReturnValue('mock-meter');
+			opentelemetry.setup();
+			meter = opentelemetry.getMeter(
+				'mock-name',
+				'mock-version',
+				'mock-options'
+			);
+		});
+
+		it('creates and returns a global meter', () => {
+			expect(api.metrics.getMeter).toHaveBeenCalledTimes(1);
+			expect(api.metrics.getMeter).toHaveBeenCalledWith(
+				'mock-name',
+				'mock-version',
+				'mock-options'
+			);
+			expect(meter).toEqual('mock-meter');
+		});
+
+		describe('when OpenTelemetry has not been set up via Reliability Kit', () => {
+			beforeEach(() => {
+				reloadAllModules();
+			});
+
+			it('throws an error', () => {
+				expect.hasAssertions();
+				try {
+					opentelemetry.getMeter('mock-name', 'mock-version', 'mock-options');
+				} catch (error) {
+					expect(error.code).toEqual('OTEL_MISSING_SETUP');
+				}
+			});
+		});
+	});
 });