feat: Add @netlify/otel affordances (#363)

* Allow consumer to specify instrumentations and span processors
* Add convenience withActiveSpan function so that consumers don't have to repeat themselves
* Remove default instrumentations in favour of allowing users to pass them in
* Remove extra packages

Author: chee

package-lock.json

@@ -72,6 +72,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/core": "1.30.1",
+    "@opentelemetry/instrumentation": "^0.203.0",
     "@opentelemetry/otlp-transformer": "0.57.2",
     "@opentelemetry/resources": "1.30.1",
     "@opentelemetry/sdk-trace-node": "1.30.1"

packages/otel/package.json

@@ -1,14 +1,23 @@
+import { type SpanProcessor } from '@opentelemetry/sdk-trace-node'
+import type { Instrumentation } from '@opentelemetry/instrumentation'
 import { GET_TRACER, SHUTDOWN_TRACERS } from '../constants.js'
 
-export const createTracerProvider = async (options: {
+export interface TracerProviderOptions {
+  /**
+   * The request headers (checked for presence of the `x-nf-enable-tracing` header)
+   */
   headers: Headers
   serviceName: string
   serviceVersion: string
   deploymentEnvironment: string
   siteUrl: string
   siteId: string
   siteName: string
-}) => {
+  instrumentations?: (Instrumentation | Promise<Instrumentation>)[]
+  extraSpanProcessors?: (SpanProcessor | Promise<SpanProcessor>)[]
+}
+
+export const createTracerProvider = async (options: TracerProviderOptions) => {
   if (!options.headers.has('x-nf-enable-tracing')) {
     return
   }
@@ -17,7 +26,9 @@ export const createTracerProvider = async (options: {
   const runtimeVersion = nodeVersion.slice(1)
 
   const { Resource } = await import('@opentelemetry/resources')
-  const { NodeTracerProvider, BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-node')
+  const { NodeTracerProvider, SimpleSpanProcessor } = await import('@opentelemetry/sdk-trace-node')
+
+  const { registerInstrumentations } = await import('@opentelemetry/instrumentation')
 
   const { NetlifySpanExporter } = await import('./netlify_span_exporter.js')
 
@@ -34,11 +45,21 @@ export const createTracerProvider = async (options: {
 
   const nodeTracerProvider = new NodeTracerProvider({
     resource,
-    spanProcessors: [new BatchSpanProcessor(new NetlifySpanExporter())],
+    spanProcessors: [
+      new SimpleSpanProcessor(new NetlifySpanExporter()),
+      ...(await Promise.all(options.extraSpanProcessors ?? [])),
+    ],
   })
 
   nodeTracerProvider.register()
 
+  const instrumentations = await Promise.all(options.instrumentations ?? [])
+
+  registerInstrumentations({
+    instrumentations,
+    tracerProvider: nodeTracerProvider,
+  })
+
   const { trace } = await import('@opentelemetry/api')
   const { SugaredTracer } = await import('@opentelemetry/api/experimental')
   const { default: pkg } = await import('../../package.json', { with: { type: 'json' } })

packages/otel/src/bootstrap/main.ts

@@ -1,5 +1,6 @@
-import { type SugaredTracer } from '@opentelemetry/api/experimental'
+import { type SugaredSpanOptions, type SugaredTracer } from '@opentelemetry/api/experimental'
 import { GET_TRACER, SHUTDOWN_TRACERS } from './constants.js'
+import type { Context, Span } from '@opentelemetry/api'
 
 type GlobalThisExtended = typeof globalThis & {
   [GET_TRACER]?: (name?: string, version?: string) => SugaredTracer | undefined
@@ -13,3 +14,38 @@ export const getTracer = (name?: string, version?: string): SugaredTracer | unde
 export const shutdownTracers = async (): Promise<void> => {
   return (globalThis as GlobalThisExtended)[SHUTDOWN_TRACERS]?.()
 }
+
+export function withActiveSpan<F extends (span?: Span) => ReturnType<F>>(
+  tracer: SugaredTracer | undefined,
+  name: string,
+  fn: F,
+): ReturnType<F>
+export function withActiveSpan<F extends (span?: Span) => ReturnType<F>>(
+  tracer: SugaredTracer | undefined,
+  name: string,
+  options: SugaredSpanOptions,
+  fn: F,
+): ReturnType<F>
+export function withActiveSpan<F extends (span?: Span) => ReturnType<F>>(
+  tracer: SugaredTracer | undefined,
+  name: string,
+  options: SugaredSpanOptions,
+  context: Context,
+  fn: F,
+): ReturnType<F>
+export function withActiveSpan<F extends (span?: Span) => ReturnType<F>>(
+  tracer: SugaredTracer | undefined,
+  name: string,
+  optionsOrFn: SugaredSpanOptions | F,
+  contextOrFn?: Context | F,
+  fn?: F,
+): ReturnType<F> {
+  const func = typeof contextOrFn === 'function' ? contextOrFn : typeof optionsOrFn === 'function' ? optionsOrFn : fn
+  if (!func) {
+    throw new Error('function to execute with active span is missing')
+  }
+  if (!tracer) {
+    return func()
+  }
+  return tracer.withActiveSpan(name, optionsOrFn as SugaredSpanOptions, contextOrFn as Context, func)
+}