@prairielearn/opentelemetry 1.5.2 → 1.6.0

package/README.md

@@ -14,6 +14,8 @@ import { init } from '@prairielearn/opentelemetry';
 await init({
   openTelemetryEnabled: true,
   openTelemetryExporter: 'honeycomb',
+  openTelemetryMetricExporter: 'honeycomb',
+  openTelemetryMetricExportIntervalMillis: 30_000,
   openTelemetrySamplerType: 'always-on',
   openTelemetrySampleRate: 0.1,
   honeycombApiKey: 'KEY',
@@ -23,6 +25,10 @@ await init({
 
 This will automatically instrument a variety of commonly-used Node packages.
 
+When using code from the OpenTelemetry libraries, make sure you import it via `@prairielearn/opentelemetry` instead of installing it separately to ensure that there is only one version of each OpenTelemetry package in use at once. If the desired functionality is not yet exported, please add it!
+
+## Traces
+
 To easily instrument individual pieces of functionality, you can use the `instrumented()` helper function:
 
 ```ts
@@ -59,4 +65,40 @@ await tracer.startActiveSpan('span.name', async (span) => {
 });
 ```
 
-When using code from the OpenTelemetry libraries, make sure you import it via `@prairielearn/opentelemetry` instead of installing it separately to ensure that there is only one version of each OpenTelemetry package in use at once. If the desired functionality is not yet exported, please add it!
+## Metrics
+
+You can manually create counters and other metrics with the following functions
+
+- `getHistogram`
+- `getCounter`
+- `getUpDownCounter`
+- `getObservableCounter`
+- `getObservableUpDownCounter`
+- `getObservableGauge`
+
+```ts
+import { metrics, getCounter, ValueType } from '@prairielearn/opentelemetry';
+
+function handleRequest(req, res) {
+  const meter = metrics.getMeter('meter-name');
+  const requestCounter = getCounter(meter, 'request.count', {
+    valueType: ValueType.INT,
+  });
+  requestCounter.add(1);
+}
+```
+
+You can also use the `instrumentedWithMetrics` helper to automatically capture a duration histogram and error count:
+
+```ts
+import { metrics, instrumentedWithMetrics } from '@prairielearn/opentelemetry';
+
+const meter = metrics.getMeter('meter-name');
+await instrumentedWithMetrics(meter, 'operation.name', async () => {
+  const random = Math.random() * 1000;
+  await new Promise((resolve) => setTimeout(resolve, random));
+  if (random > 900) {
+    throw new Error('Failed!');
+  }
+});
+```

package/dist/index.d.ts

@@ -1,26 +1,5 @@
-import { SpanExporter } from '@opentelemetry/sdk-trace-base';
-import { Span } from '@opentelemetry/api';
-export interface OpenTelemetryConfig {
-    openTelemetryEnabled: boolean;
-    openTelemetryExporter: 'console' | 'honeycomb' | 'jaeger' | SpanExporter;
-    openTelemetrySamplerType: 'always-on' | 'always-off' | 'trace-id-ratio';
-    openTelemetrySampleRate?: number;
-    openTelemetrySpanProcessor?: 'batch' | 'simple';
-    honeycombApiKey?: string;
-    honeycombDataset?: string;
-    serviceName?: string;
-}
-/**
- * Should be called once we've loaded our config; this will allow us to set up
- * the correct metadata for the Honeycomb exporter. We don't actually have that
- * information available until we've loaded our config.
- */
-export declare function init(config: OpenTelemetryConfig): Promise<void>;
-/**
- * Gracefully shuts down the OpenTelemetry instrumentation. Should be called
- * when a `SIGTERM` signal is handled.
- */
-export declare function shutdown(): Promise<void>;
-export declare function instrumented<T>(name: string, fn: (span: Span) => Promise<T> | T): Promise<T>;
-export { trace, context, SpanStatusCode } from '@opentelemetry/api';
+export { trace, metrics, context, SpanStatusCode, ValueType } from '@opentelemetry/api';
 export { suppressTracing } from '@opentelemetry/core';
+export { init, shutdown } from './init';
+export { instrumented } from './tracing';
+export { instrumentedWithMetrics } from './metrics';

package/dist/index.js

@@ -1,255 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.suppressTracing = exports.SpanStatusCode = exports.context = exports.trace = exports.instrumented = exports.shutdown = exports.init = void 0;
-const grpc_js_1 = require("@grpc/grpc-js");
-const sdk_node_1 = require("@opentelemetry/sdk-node");
-const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
-const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
-const resources_1 = require("@opentelemetry/resources");
-const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
-const instrumentation_express_1 = require("@opentelemetry/instrumentation-express");
-const sdk_trace_base_2 = require("@opentelemetry/sdk-trace-base");
-const api_1 = require("@opentelemetry/api");
-const core_1 = require("@opentelemetry/core");
-// Exporters go here.
-const exporter_trace_otlp_grpc_1 = require("@opentelemetry/exporter-trace-otlp-grpc");
-const exporter_jaeger_1 = require("@opentelemetry/exporter-jaeger");
-// Instrumentations go here.
-const instrumentation_aws_sdk_1 = require("@opentelemetry/instrumentation-aws-sdk");
-const instrumentation_connect_1 = require("@opentelemetry/instrumentation-connect");
-const instrumentation_dns_1 = require("@opentelemetry/instrumentation-dns");
-const instrumentation_express_2 = require("@opentelemetry/instrumentation-express");
-const instrumentation_http_1 = require("@opentelemetry/instrumentation-http");
-const instrumentation_pg_1 = require("@opentelemetry/instrumentation-pg");
-const instrumentation_redis_1 = require("@opentelemetry/instrumentation-redis");
-// Resource detectors go here.
-const resource_detector_aws_1 = require("@opentelemetry/resource-detector-aws");
-const resources_2 = require("@opentelemetry/resources");
-/**
- * Extends `BatchSpanProcessor` to give it the ability to filter out spans
- * before they're queued up to send. This enhances our sampling process so
- * that we can filter spans _after_ they've been emitted.
- */
-class FilterBatchSpanProcessor extends sdk_trace_base_2.BatchSpanProcessor {
-    constructor(exporter, filter) {
-        super(exporter);
-        this.filter = filter;
-    }
-    /**
-     * This is invoked after a span is "finalized". `super.onEnd` will queue up
-     * the span to be exported, but if we don't call that, we can just drop the
-     * span and the parent will be none the wiser!
-     */
-    onEnd(span) {
-        if (!this.filter(span))
-            return;
-        super.onEnd(span);
-    }
-}
-/**
- * This will be used with our {@link FilterBatchSpanProcessor} to filter out
- * events that we're not interested in. This helps reduce our event volume
- * but still gives us fine-grained control over which events we keep.
- */
-function filter(span) {
-    if (span.name === 'pg-pool.connect') {
-        // Looking at historical data, this generally happens in under a millisecond,
-        // precisely because we maintain a pool of long-lived connections. The only
-        // time obtaining a client should take longer than that is if we're
-        // establishing a connection for the first time, which should happen only at
-        // bootup, or if a connection errors out. Those are the cases we're
-        // interested in, so we'll filter accordingly.
-        return (0, core_1.hrTimeToMilliseconds)(span.duration) > 1;
-    }
-    // Always return true so that we default to including a span.
-    return true;
-}
-const instrumentations = [
-    new instrumentation_aws_sdk_1.AwsInstrumentation(),
-    new instrumentation_connect_1.ConnectInstrumentation(),
-    new instrumentation_dns_1.DnsInstrumentation(),
-    new instrumentation_express_2.ExpressInstrumentation({
-        // We use a lot of middleware; it makes the traces way too noisy. If we
-        // want telemetry on a particular middleware, we should instrument it
-        // manually.
-        ignoreLayersType: [instrumentation_express_1.ExpressLayerType.MIDDLEWARE],
-        ignoreLayers: [
-            // These don't provide useful information to us.
-            'router - /',
-            'request handler - /*',
-        ],
-    }),
-    new instrumentation_http_1.HttpInstrumentation({
-        ignoreIncomingPaths: [
-            // socket.io requests are generally just long-polling; they don't add
-            // useful information for us.
-            /\/socket.io\//,
-            // We get several of these per second; they just chew through our event quota.
-            // They don't really do anything interesting anyways.
-            /\/pl\/webhooks\/ping/,
-        ],
-    }),
-    new instrumentation_pg_1.PgInstrumentation(),
-    new instrumentation_redis_1.RedisInstrumentation(),
-];
-// Enable all instrumentations now, even though we haven't configured our
-// span processors or trace exporters yet. We'll set those up later.
-instrumentations.forEach((i) => {
-    i.enable();
-});
-let tracerProvider;
-/**
- * Should be called once we've loaded our config; this will allow us to set up
- * the correct metadata for the Honeycomb exporter. We don't actually have that
- * information available until we've loaded our config.
- */
-async function init(config) {
-    if (!config.openTelemetryEnabled) {
-        // If not enabled, do nothing. We used to disable the instrumentations, but
-        // per maintainers, that can actually be problematic. See the comments on
-        // https://github.com/open-telemetry/opentelemetry-js-contrib/issues/970
-        // The Express instrumentation also logs a benign error, which can be
-        // confusing to users. There's a fix in progress if we want to switch back
-        // to disabling instrumentations in the future:
-        // https://github.com/open-telemetry/opentelemetry-js-contrib/pull/972
-        return;
-    }
-    let exporter;
-    if (typeof config.openTelemetryExporter === 'object') {
-        exporter = config.openTelemetryExporter;
-    }
-    else {
-        switch (config.openTelemetryExporter) {
-            case 'console': {
-                // Export spans to the console for testing purposes.
-                exporter = new sdk_node_1.tracing.ConsoleSpanExporter();
-                break;
-            }
-            case 'honeycomb': {
-                if (!config.honeycombApiKey)
-                    throw new Error('Missing Honeycomb API key');
-                if (!config.honeycombDataset)
-                    throw new Error('Missing Honeycomb dataset');
-                // Create a Honeycomb exporter with the appropriate metadata from the
-                // config we've been provided with.
-                const metadata = new grpc_js_1.Metadata();
-                metadata.set('x-honeycomb-team', config.honeycombApiKey);
-                metadata.set('x-honeycomb-dataset', config.honeycombDataset);
-                exporter = new exporter_trace_otlp_grpc_1.OTLPTraceExporter({
-                    url: 'grpc://api.honeycomb.io:443/',
-                    credentials: grpc_js_1.credentials.createSsl(),
-                    metadata,
-                });
-                break;
-            }
-            case 'jaeger': {
-                exporter = new exporter_jaeger_1.JaegerExporter({
-                    // By default, the UDP sender will be used, but that causes issues
-                    // with packet sizes when Jaeger is running in Docker. We'll instead
-                    // configure it to use the HTTP sender, which shouldn't face those
-                    // same issues. We'll still allow the endpoint to be overridden via
-                    // environment variable if needed.
-                    endpoint: process.env.OTEL_EXPORTER_JAEGER_ENDPOINT ?? 'http://localhost:14268/api/traces',
-                });
-                break;
-            }
-            default:
-                throw new Error(`Unknown OpenTelemetry exporter: ${config.openTelemetryExporter}`);
-        }
-    }
-    let sampler;
-    switch (config.openTelemetrySamplerType ?? 'always-on') {
-        case 'always-on': {
-            sampler = new sdk_trace_base_1.AlwaysOnSampler();
-            break;
-        }
-        case 'always-off': {
-            sampler = new sdk_trace_base_1.AlwaysOffSampler();
-            break;
-        }
-        case 'trace-id-ratio': {
-            sampler = new sdk_trace_base_1.ParentBasedSampler({
-                root: new sdk_trace_base_1.TraceIdRatioBasedSampler(config.openTelemetrySampleRate),
-            });
-            break;
-        }
-        default:
-            throw new Error(`Unknown OpenTelemetry sampler type: ${config.openTelemetrySamplerType}`);
-    }
-    let spanProcessor;
-    switch (config.openTelemetrySpanProcessor ?? 'batch') {
-        case 'batch': {
-            spanProcessor = new FilterBatchSpanProcessor(exporter, filter);
-            break;
-        }
-        case 'simple': {
-            spanProcessor = new sdk_trace_base_1.SimpleSpanProcessor(exporter);
-            break;
-        }
-        default: {
-            throw new Error(`Unknown OpenTelemetry span processor: ${config.openTelemetrySpanProcessor}`);
-        }
-    }
-    // Much of this functionality is copied from `@opentelemetry/sdk-node`, but
-    // we can't use the SDK directly because of the fact that we load our config
-    // asynchronously. We need to initialize our instrumentations first; only
-    // then can we actually start requiring all of our code that loads our config
-    // and ultimately tells us how to configure OpenTelemetry.
-    let resource = await (0, resources_1.detectResources)({
-        detectors: [resource_detector_aws_1.awsEc2Detector, resources_2.processDetector, resources_2.envDetector],
-    });
-    if (config.serviceName) {
-        resource = resource.merge(new resources_1.Resource({ [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: config.serviceName }));
-    }
-    const nodeTracerProvider = new sdk_trace_node_1.NodeTracerProvider({
-        sampler,
-        resource,
-    });
-    nodeTracerProvider.addSpanProcessor(spanProcessor);
-    nodeTracerProvider.register();
-    instrumentations.forEach((i) => i.setTracerProvider(nodeTracerProvider));
-    // Save the provider so we can shut it down later.
-    tracerProvider = tracerProvider;
-}
-exports.init = init;
-/**
- * Gracefully shuts down the OpenTelemetry instrumentation. Should be called
- * when a `SIGTERM` signal is handled.
- */
-async function shutdown() {
-    if (tracerProvider) {
-        await tracerProvider.shutdown();
-        tracerProvider = null;
-    }
-}
-exports.shutdown = shutdown;
-async function instrumented(name, fn) {
-    return api_1.trace
-        .getTracer('default')
-        .startActiveSpan(name, async (span) => {
-        try {
-            const result = await fn(span);
-            span.setStatus({ code: api_1.SpanStatusCode.OK });
-            return result;
-        }
-        catch (e) {
-            span.setStatus({
-                code: api_1.SpanStatusCode.ERROR,
-                message: e.message,
-            });
-            span.recordException(e);
-            throw e;
-        }
-        finally {
-            span.end();
-        }
-    });
-}
-exports.instrumented = instrumented;
-var api_2 = require("@opentelemetry/api");
-Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return api_2.trace; } });
-Object.defineProperty(exports, "context", { enumerable: true, get: function () { return api_2.context; } });
-Object.defineProperty(exports, "SpanStatusCode", { enumerable: true, get: function () { return api_2.SpanStatusCode; } });
-var core_2 = require("@opentelemetry/core");
-Object.defineProperty(exports, "suppressTracing", { enumerable: true, get: function () { return core_2.suppressTracing; } });
+exports.instrumentedWithMetrics = exports.instrumented = exports.shutdown = exports.init = exports.suppressTracing = exports.ValueType = exports.SpanStatusCode = exports.context = exports.metrics = exports.trace = void 0;
+var api_1 = require("@opentelemetry/api");
+Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return api_1.trace; } });
+Object.defineProperty(exports, "metrics", { enumerable: true, get: function () { return api_1.metrics; } });
+Object.defineProperty(exports, "context", { enumerable: true, get: function () { return api_1.context; } });
+Object.defineProperty(exports, "SpanStatusCode", { enumerable: true, get: function () { return api_1.SpanStatusCode; } });
+Object.defineProperty(exports, "ValueType", { enumerable: true, get: function () { return api_1.ValueType; } });
+var core_1 = require("@opentelemetry/core");
+Object.defineProperty(exports, "suppressTracing", { enumerable: true, get: function () { return core_1.suppressTracing; } });
+var init_1 = require("./init");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
+Object.defineProperty(exports, "shutdown", { enumerable: true, get: function () { return init_1.shutdown; } });
+var tracing_1 = require("./tracing");
+Object.defineProperty(exports, "instrumented", { enumerable: true, get: function () { return tracing_1.instrumented; } });
+var metrics_1 = require("./metrics");
+Object.defineProperty(exports, "instrumentedWithMetrics", { enumerable: true, get: function () { return metrics_1.instrumentedWithMetrics; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,0CAAwF;AAA/E,4FAAA,KAAK,OAAA;AAAE,8FAAA,OAAO,OAAA;AAAE,8FAAA,OAAO,OAAA;AAAE,qGAAA,cAAc,OAAA;AAAE,gGAAA,SAAS,OAAA;AAC3D,4CAAsD;AAA7C,uGAAA,eAAe,OAAA;AAExB,+BAAwC;AAA/B,4FAAA,IAAI,OAAA;AAAE,gGAAA,QAAQ,OAAA;AACvB,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AACrB,qCAAoD;AAA3C,kHAAA,uBAAuB,OAAA"}

package/dist/init.d.ts

@@ -0,0 +1,25 @@
+import { PushMetricExporter } from '@opentelemetry/sdk-metrics';
+import { SpanExporter } from '@opentelemetry/sdk-trace-base';
+export interface OpenTelemetryConfig {
+    openTelemetryEnabled: boolean;
+    openTelemetryExporter: 'console' | 'honeycomb' | 'jaeger' | SpanExporter;
+    openTelemetryMetricExporter?: 'console' | 'honeycomb' | PushMetricExporter;
+    openTelemetryMetricExportIntervalMillis?: number;
+    openTelemetrySamplerType: 'always-on' | 'always-off' | 'trace-id-ratio';
+    openTelemetrySampleRate?: number;
+    openTelemetrySpanProcessor?: 'batch' | 'simple';
+    honeycombApiKey?: string;
+    honeycombDataset?: string;
+    serviceName?: string;
+}
+/**
+ * Should be called once we've loaded our config; this will allow us to set up
+ * the correct metadata for the Honeycomb exporter. We don't actually have that
+ * information available until we've loaded our config.
+ */
+export declare function init(config: OpenTelemetryConfig): Promise<void>;
+/**
+ * Gracefully shuts down the OpenTelemetry instrumentation. Should be called
+ * when a `SIGTERM` signal is handled.
+ */
+export declare function shutdown(): Promise<void>;

package/dist/init.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shutdown = exports.init = void 0;
+const grpc_js_1 = require("@grpc/grpc-js");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const instrumentation_express_1 = require("@opentelemetry/instrumentation-express");
+const api_1 = require("@opentelemetry/api");
+const core_1 = require("@opentelemetry/core");
+// Exporters go here.
+const exporter_trace_otlp_grpc_1 = require("@opentelemetry/exporter-trace-otlp-grpc");
+const exporter_jaeger_1 = require("@opentelemetry/exporter-jaeger");
+const exporter_metrics_otlp_grpc_1 = require("@opentelemetry/exporter-metrics-otlp-grpc");
+// Instrumentations go here.
+const instrumentation_aws_sdk_1 = require("@opentelemetry/instrumentation-aws-sdk");
+const instrumentation_connect_1 = require("@opentelemetry/instrumentation-connect");
+const instrumentation_dns_1 = require("@opentelemetry/instrumentation-dns");
+const instrumentation_express_2 = require("@opentelemetry/instrumentation-express");
+const instrumentation_http_1 = require("@opentelemetry/instrumentation-http");
+const instrumentation_pg_1 = require("@opentelemetry/instrumentation-pg");
+const instrumentation_redis_1 = require("@opentelemetry/instrumentation-redis");
+// Resource detectors go here.
+const resource_detector_aws_1 = require("@opentelemetry/resource-detector-aws");
+const resources_2 = require("@opentelemetry/resources");
+/**
+ * Extends `BatchSpanProcessor` to give it the ability to filter out spans
+ * before they're queued up to send. This enhances our sampling process so
+ * that we can filter spans _after_ they've been emitted.
+ */
+class FilterBatchSpanProcessor extends sdk_trace_base_1.BatchSpanProcessor {
+    constructor(exporter, filter) {
+        super(exporter);
+        this.filter = filter;
+    }
+    /**
+     * This is invoked after a span is "finalized". `super.onEnd` will queue up
+     * the span to be exported, but if we don't call that, we can just drop the
+     * span and the parent will be none the wiser!
+     */
+    onEnd(span) {
+        if (!this.filter(span))
+            return;
+        super.onEnd(span);
+    }
+}
+/**
+ * This will be used with our {@link FilterBatchSpanProcessor} to filter out
+ * events that we're not interested in. This helps reduce our event volume
+ * but still gives us fine-grained control over which events we keep.
+ */
+function filter(span) {
+    if (span.name === 'pg-pool.connect') {
+        // Looking at historical data, this generally happens in under a millisecond,
+        // precisely because we maintain a pool of long-lived connections. The only
+        // time obtaining a client should take longer than that is if we're
+        // establishing a connection for the first time, which should happen only at
+        // bootup, or if a connection errors out. Those are the cases we're
+        // interested in, so we'll filter accordingly.
+        return (0, core_1.hrTimeToMilliseconds)(span.duration) > 1;
+    }
+    // Always return true so that we default to including a span.
+    return true;
+}
+const instrumentations = [
+    new instrumentation_aws_sdk_1.AwsInstrumentation(),
+    new instrumentation_connect_1.ConnectInstrumentation(),
+    new instrumentation_dns_1.DnsInstrumentation(),
+    new instrumentation_express_2.ExpressInstrumentation({
+        // We use a lot of middleware; it makes the traces way too noisy. If we
+        // want telemetry on a particular middleware, we should instrument it
+        // manually.
+        ignoreLayersType: [instrumentation_express_1.ExpressLayerType.MIDDLEWARE],
+        ignoreLayers: [
+            // These don't provide useful information to us.
+            'router - /',
+            'request handler - /*',
+        ],
+    }),
+    new instrumentation_http_1.HttpInstrumentation({
+        ignoreIncomingPaths: [
+            // socket.io requests are generally just long-polling; they don't add
+            // useful information for us.
+            /\/socket.io\//,
+            // We get several of these per second; they just chew through our event quota.
+            // They don't really do anything interesting anyways.
+            /\/pl\/webhooks\/ping/,
+        ],
+    }),
+    new instrumentation_pg_1.PgInstrumentation(),
+    new instrumentation_redis_1.RedisInstrumentation(),
+];
+// Enable all instrumentations now, even though we haven't configured our
+// span processors or trace exporters yet. We'll set those up later.
+instrumentations.forEach((i) => {
+    i.enable();
+});
+let tracerProvider;
+function getHoneycombMetadata(config, datasetSuffix = '') {
+    if (!config.honeycombApiKey)
+        throw new Error('Missing Honeycomb API key');
+    if (!config.honeycombDataset)
+        throw new Error('Missing Honeycomb dataset');
+    const metadata = new grpc_js_1.Metadata();
+    metadata.set('x-honeycomb-team', config.honeycombApiKey);
+    metadata.set('x-honeycomb-dataset', config.honeycombDataset + datasetSuffix);
+    return metadata;
+}
+function getTraceExporter(config) {
+    if (typeof config.openTelemetryExporter === 'object') {
+        return config.openTelemetryExporter;
+    }
+    switch (config.openTelemetryExporter) {
+        case 'console':
+            return new sdk_trace_base_1.ConsoleSpanExporter();
+        case 'honeycomb':
+            return new exporter_trace_otlp_grpc_1.OTLPTraceExporter({
+                url: 'grpc://api.honeycomb.io:443/',
+                credentials: grpc_js_1.credentials.createSsl(),
+                metadata: getHoneycombMetadata(config),
+            });
+            break;
+        case 'jaeger':
+            return new exporter_jaeger_1.JaegerExporter({
+                // By default, the UDP sender will be used, but that causes issues
+                // with packet sizes when Jaeger is running in Docker. We'll instead
+                // configure it to use the HTTP sender, which shouldn't face those
+                // same issues. We'll still allow the endpoint to be overridden via
+                // environment variable if needed.
+                endpoint: process.env.OTEL_EXPORTER_JAEGER_ENDPOINT ?? 'http://localhost:14268/api/traces',
+            });
+        default:
+            throw new Error(`Unknown OpenTelemetry exporter: ${config.openTelemetryExporter}`);
+    }
+}
+function getMetricExporter(config) {
+    if (!config.openTelemetryMetricExporter)
+        return null;
+    if (typeof config.openTelemetryMetricExporter === 'object') {
+        return config.openTelemetryMetricExporter;
+    }
+    switch (config.openTelemetryMetricExporter) {
+        case 'console':
+            return new sdk_metrics_1.ConsoleMetricExporter();
+        case 'honeycomb':
+            return new exporter_metrics_otlp_grpc_1.OTLPMetricExporter({
+                url: 'grpc://api.honeycomb.io:443/',
+                credentials: grpc_js_1.credentials.createSsl(),
+                // Honeycomb recommends using a separate dataset for metrics, so we'll
+                // adopt the convention of appending '-metrics' to the dataset name.
+                metadata: getHoneycombMetadata(config, '-metrics'),
+                // Delta temporality means that sums, histograms, etc. will reset each
+                // time data is collected. This more closely matches how we want to
+                // observe our metrics than the default cumulative temporality.
+                temporalityPreference: sdk_metrics_1.AggregationTemporality.DELTA,
+            });
+        default:
+            throw new Error(`Unknown OpenTelemetry metric exporter: ${config.openTelemetryMetricExporter}`);
+    }
+}
+/**
+ * Should be called once we've loaded our config; this will allow us to set up
+ * the correct metadata for the Honeycomb exporter. We don't actually have that
+ * information available until we've loaded our config.
+ */
+async function init(config) {
+    if (!config.openTelemetryEnabled) {
+        // If not enabled, do nothing. We used to disable the instrumentations, but
+        // per maintainers, that can actually be problematic. See the comments on
+        // https://github.com/open-telemetry/opentelemetry-js-contrib/issues/970
+        // The Express instrumentation also logs a benign error, which can be
+        // confusing to users. There's a fix in progress if we want to switch back
+        // to disabling instrumentations in the future:
+        // https://github.com/open-telemetry/opentelemetry-js-contrib/pull/972
+        return;
+    }
+    const traceExporter = getTraceExporter(config);
+    const metricExporter = getMetricExporter(config);
+    let sampler;
+    switch (config.openTelemetrySamplerType ?? 'always-on') {
+        case 'always-on': {
+            sampler = new sdk_trace_base_1.AlwaysOnSampler();
+            break;
+        }
+        case 'always-off': {
+            sampler = new sdk_trace_base_1.AlwaysOffSampler();
+            break;
+        }
+        case 'trace-id-ratio': {
+            sampler = new sdk_trace_base_1.ParentBasedSampler({
+                root: new sdk_trace_base_1.TraceIdRatioBasedSampler(config.openTelemetrySampleRate),
+            });
+            break;
+        }
+        default:
+            throw new Error(`Unknown OpenTelemetry sampler type: ${config.openTelemetrySamplerType}`);
+    }
+    let spanProcessor;
+    switch (config.openTelemetrySpanProcessor ?? 'batch') {
+        case 'batch': {
+            spanProcessor = new FilterBatchSpanProcessor(traceExporter, filter);
+            break;
+        }
+        case 'simple': {
+            spanProcessor = new sdk_trace_base_1.SimpleSpanProcessor(traceExporter);
+            break;
+        }
+        default: {
+            throw new Error(`Unknown OpenTelemetry span processor: ${config.openTelemetrySpanProcessor}`);
+        }
+    }
+    // Much of this functionality is copied from `@opentelemetry/sdk-node`, but
+    // we can't use the SDK directly because of the fact that we load our config
+    // asynchronously. We need to initialize our instrumentations first; only
+    // then can we actually start requiring all of our code that loads our config
+    // and ultimately tells us how to configure OpenTelemetry.
+    let resource = await (0, resources_1.detectResources)({
+        detectors: [resource_detector_aws_1.awsEc2Detector, resources_2.processDetector, resources_2.envDetector],
+    });
+    if (config.serviceName) {
+        resource = resource.merge(new resources_1.Resource({ [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: config.serviceName }));
+    }
+    // Set up tracing instrumentation.
+    const nodeTracerProvider = new sdk_trace_node_1.NodeTracerProvider({
+        sampler,
+        resource,
+    });
+    nodeTracerProvider.addSpanProcessor(spanProcessor);
+    nodeTracerProvider.register();
+    instrumentations.forEach((i) => i.setTracerProvider(nodeTracerProvider));
+    // Save the provider so we can shut it down later.
+    tracerProvider = nodeTracerProvider;
+    // Set up metrics instrumentation if it's enabled.
+    if (metricExporter) {
+        const meterProvider = new sdk_metrics_1.MeterProvider({ resource });
+        api_1.metrics.setGlobalMeterProvider(meterProvider);
+        const metricReader = new sdk_metrics_1.PeriodicExportingMetricReader({
+            exporter: metricExporter,
+            exportIntervalMillis: config.openTelemetryMetricExportIntervalMillis ?? 30000,
+        });
+        meterProvider.addMetricReader(metricReader);
+    }
+}
+exports.init = init;
+/**
+ * Gracefully shuts down the OpenTelemetry instrumentation. Should be called
+ * when a `SIGTERM` signal is handled.
+ */
+async function shutdown() {
+    if (tracerProvider) {
+        await tracerProvider.shutdown();
+        tracerProvider = null;
+    }
+}
+exports.shutdown = shutdown;
+//# sourceMappingURL=init.js.map