@temporalio/interceptors-opentelemetry-v2 1.19.0

package/src/workflow/index.ts

@@ -0,0 +1,312 @@
+// eslint-disable-next-line import/no-unassigned-import
+import './performance-polyfill'; // Zero-import polyfill; must run before OTel modules access `performance`
+// eslint-disable-next-line import/no-unassigned-import
+import './runtime'; // Patch the Workflow isolate runtime for opentelemetry
+import * as otel from '@opentelemetry/api';
+import * as tracing from '@opentelemetry/sdk-trace-base';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import type {
+  ActivityInput,
+  ContinueAsNewInput,
+  DisposeInput,
+  GetLogAttributesInput,
+  GetMetricTagsInput,
+  LocalActivityInput,
+  Next,
+  QueryInput,
+  SignalInput,
+  SignalWorkflowInput,
+  StartChildWorkflowExecutionInput,
+  UpdateInput,
+  WorkflowExecuteInput,
+  WorkflowInboundCallsInterceptor,
+  WorkflowInternalsInterceptor,
+  WorkflowOutboundCallsInterceptor,
+  StartNexusOperationInput,
+  StartNexusOperationOutput,
+} from '@temporalio/workflow';
+import {
+  instrument,
+  instrumentSync,
+  extractContextFromHeaders,
+  headersWithContext,
+  nexusHeadersWithContext,
+  UPDATE_ID_ATTR_KEY,
+  NEXUS_SERVICE_ATTR_KEY,
+  NEXUS_OPERATION_ATTR_KEY,
+  NEXUS_ENDPOINT_ATTR_KEY,
+} from '../instrumentation';
+import { ContextManager } from './context-manager';
+import { SpanName, SPAN_DELIMITER } from './definitions';
+import { SpanExporter } from './span-exporter';
+import { DeterministicIdGenerator } from './id-generator';
+import { workflowInfo, ContinueAsNew } from './workflow-imports';
+
+export * from './definitions';
+
+let tracer: undefined | otel.Tracer = undefined;
+let contextManager: undefined | ContextManager = undefined;
+
+function getTracer(): otel.Tracer {
+  if (contextManager === undefined) {
+    contextManager = new ContextManager();
+  }
+  if (tracer === undefined) {
+    const provider = new tracing.BasicTracerProvider({
+      idGenerator: new DeterministicIdGenerator(),
+      spanProcessors: [new tracing.SimpleSpanProcessor(new SpanExporter())],
+    });
+    otel.propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+    otel.trace.setGlobalTracerProvider(provider);
+    otel.context.setGlobalContextManager(contextManager);
+    tracer = provider.getTracer('@temporalio/interceptor-workflow');
+  }
+  return tracer;
+}
+
+/**
+ * Intercepts calls to run a Workflow
+ *
+ * Wraps the operation in an opentelemetry Span and links it to a parent Span context if one is
+ * provided in the Workflow input headers.
+ *
+ * `@temporalio/workflow` must be provided by host package in order to function.
+ *
+ * @experimental This interceptor is experimental and APIs may change without notice.
+ */
+export class OpenTelemetryInboundInterceptor implements WorkflowInboundCallsInterceptor {
+  protected readonly tracer = getTracer();
+
+  public async execute(
+    input: WorkflowExecuteInput,
+    next: Next<WorkflowInboundCallsInterceptor, 'execute'>
+  ): Promise<unknown> {
+    const context = extractContextFromHeaders(input.headers);
+
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.WORKFLOW_EXECUTE}${SPAN_DELIMITER}${workflowInfo().workflowType}`,
+      fn: () => next(input),
+      context,
+      acceptableErrors: (err) => err instanceof ContinueAsNew,
+    });
+  }
+
+  public async handleSignal(
+    input: SignalInput,
+    next: Next<WorkflowInboundCallsInterceptor, 'handleSignal'>
+  ): Promise<void> {
+    const context = extractContextFromHeaders(input.headers);
+
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.WORKFLOW_HANDLE_SIGNAL}${SPAN_DELIMITER}${input.signalName}`,
+      fn: () => next(input),
+      context,
+    });
+  }
+
+  public async handleUpdate(
+    input: UpdateInput,
+    next: Next<WorkflowInboundCallsInterceptor, 'handleUpdate'>
+  ): Promise<unknown> {
+    const context = extractContextFromHeaders(input.headers);
+
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.WORKFLOW_HANDLE_UPDATE}${SPAN_DELIMITER}${input.name}`,
+      fn: (span) => {
+        span.setAttribute(UPDATE_ID_ATTR_KEY, input.updateId);
+        return next(input);
+      },
+      context,
+    });
+  }
+
+  public validateUpdate(input: UpdateInput, next: Next<WorkflowInboundCallsInterceptor, 'validateUpdate'>): void {
+    const context = extractContextFromHeaders(input.headers);
+    instrumentSync({
+      tracer: this.tracer,
+      spanName: `${SpanName.WORKFLOW_VALIDATE_UPDATE}${SPAN_DELIMITER}${input.name}`,
+      fn: (span) => {
+        span.setAttribute(UPDATE_ID_ATTR_KEY, input.updateId);
+        return next(input);
+      },
+      context,
+    });
+  }
+
+  public async handleQuery(
+    input: QueryInput,
+    next: Next<WorkflowInboundCallsInterceptor, 'handleQuery'>
+  ): Promise<unknown> {
+    const context = extractContextFromHeaders(input.headers);
+
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.WORKFLOW_HANDLE_QUERY}${SPAN_DELIMITER}${input.queryName}`,
+      fn: () => next(input),
+      context,
+    });
+  }
+}
+
+/**
+ * Intercepts outbound calls to schedule an Activity
+ *
+ * Wraps the operation in an opentelemetry Span and passes it to the Activity via headers.
+ *
+ * `@temporalio/workflow` must be provided by host package in order to function.
+ *
+ * @experimental This interceptor is experimental and APIs may change without notice.
+ */
+export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsInterceptor {
+  protected readonly tracer = getTracer();
+
+  public async scheduleActivity(
+    input: ActivityInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'scheduleActivity'>
+  ): Promise<unknown> {
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.ACTIVITY_START}${SPAN_DELIMITER}${input.activityType}`,
+      fn: async () => {
+        const headers = headersWithContext(input.headers);
+
+        return next({
+          ...input,
+          headers,
+        });
+      },
+    });
+  }
+
+  public async scheduleLocalActivity(
+    input: LocalActivityInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'scheduleLocalActivity'>
+  ): Promise<unknown> {
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.ACTIVITY_START}${SPAN_DELIMITER}${input.activityType}`,
+      fn: async () => {
+        const headers = headersWithContext(input.headers);
+
+        return next({
+          ...input,
+          headers,
+        });
+      },
+    });
+  }
+
+  public async startNexusOperation(
+    input: StartNexusOperationInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'startNexusOperation'>
+  ): Promise<StartNexusOperationOutput> {
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.NEXUS_OPERATION_START}${SPAN_DELIMITER}${input.service}/${input.operation}`,
+      fn: async (span) => {
+        span.setAttribute(NEXUS_SERVICE_ATTR_KEY, input.service);
+        span.setAttribute(NEXUS_OPERATION_ATTR_KEY, input.operation);
+        span.setAttribute(NEXUS_ENDPOINT_ATTR_KEY, input.endpoint);
+        const headers = nexusHeadersWithContext(input.headers);
+        return await next({ ...input, headers });
+      },
+    });
+  }
+
+  public async startChildWorkflowExecution(
+    input: StartChildWorkflowExecutionInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'startChildWorkflowExecution'>
+  ): Promise<[Promise<string>, Promise<unknown>]> {
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.CHILD_WORKFLOW_START}${SPAN_DELIMITER}${input.workflowType}`,
+      fn: async () => {
+        const headers = headersWithContext(input.headers);
+
+        return next({
+          ...input,
+          headers,
+        });
+      },
+    });
+  }
+
+  public async continueAsNew(
+    input: ContinueAsNewInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'continueAsNew'>
+  ): Promise<never> {
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.CONTINUE_AS_NEW}${SPAN_DELIMITER}${input.options.workflowType}`,
+      fn: async () => {
+        const headers = headersWithContext(input.headers);
+
+        return next({
+          ...input,
+          headers,
+        });
+      },
+      acceptableErrors: (err) => err instanceof ContinueAsNew,
+    });
+  }
+
+  public async signalWorkflow(
+    input: SignalWorkflowInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'signalWorkflow'>
+  ): Promise<void> {
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.WORKFLOW_SIGNAL}${SPAN_DELIMITER}${input.signalName}`,
+      fn: async () => {
+        const headers = headersWithContext(input.headers);
+
+        return next({
+          ...input,
+          headers,
+        });
+      },
+    });
+  }
+
+  public getLogAttributes(
+    input: GetLogAttributesInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'getLogAttributes'>
+  ): Record<string, unknown> {
+    const span = otel.trace.getSpan(otel.context.active());
+    const spanContext = span?.spanContext();
+    if (spanContext && otel.isSpanContextValid(spanContext)) {
+      return next({
+        trace_id: spanContext.traceId,
+        span_id: spanContext.spanId,
+        trace_flags: `0${spanContext.traceFlags.toString(16)}`,
+        ...input,
+      });
+    } else {
+      return next(input);
+    }
+  }
+
+  public getMetricTags(
+    input: GetMetricTagsInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'getMetricTags'>
+  ): GetMetricTagsInput {
+    return next(input);
+  }
+}
+
+/**
+ * Intercepts Workflow lifecycle internals.
+ *
+ * @experimental This interceptor is experimental and APIs may change without notice.
+ */
+export class OpenTelemetryInternalsInterceptor implements WorkflowInternalsInterceptor {
+  async dispose(input: DisposeInput, next: Next<WorkflowInternalsInterceptor, 'dispose'>): Promise<void> {
+    if (contextManager !== undefined) {
+      contextManager.disable();
+    }
+    next(input);
+  }
+}

package/src/workflow/performance-polyfill.ts

@@ -0,0 +1,31 @@
+/**
+ * Polyfill performance for the workflow isolate.
+ *
+ * OTel v2's browser platform accesses `performance` at module scope.
+ * This file MUST have zero imports so webpack initializes it before any
+ * OTel module that references `performance`.
+ *
+ * The guard uses two checks:
+ * - `__webpack_module_cache__` on globalThis is a positive indicator of the
+ *   workflow sandbox (set by the SDK's VM creators before the bundle evaluates).
+ * - `performance` being undefined confirms polyfilling is needed. The polyfill
+ *   reads workflow time from the activator so it is safe during preload.
+ *
+ * @module
+ */
+
+if ('__webpack_module_cache__' in globalThis && typeof performance === 'undefined') {
+  const now = () => ((globalThis as any).__TEMPORAL_ACTIVATOR__?.now as number | undefined) ?? 0;
+  Object.assign(globalThis, {
+    performance: {
+      timeOrigin: now(),
+      now() {
+        return now() - this.timeOrigin;
+      },
+    },
+  });
+}
+
+// Empty export to mark this as a module for ESLint's import/unambiguous rule.
+// This file intentionally has no imports to ensure it initializes before OTel.
+export {};

package/src/workflow/runtime.ts

@@ -0,0 +1,12 @@
+/**
+ * Sets global variables required for importing opentelemetry in isolate
+ * @module
+ */
+import { inWorkflowContext } from './workflow-imports';
+
+if (inWorkflowContext()) {
+  // OTel uses `window` to detect a browser environment
+  Object.assign(globalThis, {
+    window: globalThis,
+  });
+}

package/src/workflow/span-exporter.ts

@@ -0,0 +1,60 @@
+import type * as tracing from '@opentelemetry/sdk-trace-base';
+import type { ExportResult } from '@opentelemetry/core';
+import { ExportResultCode } from '@opentelemetry/core';
+import type { OpenTelemetrySinks, SerializableSpan, SerializableSpanContext } from './definitions';
+import { proxySinks } from './workflow-imports';
+
+export class SpanExporter implements tracing.SpanExporter {
+  private exporter?: OpenTelemetrySinks['exporter'];
+
+  public export(spans: tracing.ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
+    if (!this.exporter) {
+      this.exporter = proxySinks<OpenTelemetrySinks>().exporter;
+    }
+    this.exporter.export(spans.map((span) => this.makeSerializable(span)));
+    resultCallback({ code: ExportResultCode.SUCCESS });
+  }
+
+  public async shutdown(): Promise<void> {
+    // Nothing to shut down
+  }
+
+  public makeSerializable(span: tracing.ReadableSpan): SerializableSpan {
+    const { traceState, ...restSpanContext } = span.spanContext();
+    // Serialize traceState to a string because TraceState objects lose their
+    // prototype methods when crossing the V8 isolate boundary.
+    // See: https://github.com/temporalio/sdk-typescript/issues/1738
+    const serializableSpanContext: SerializableSpanContext = {
+      traceState: traceState?.serialize(),
+      ...restSpanContext,
+    };
+
+    let serializableParentSpanContext: SerializableSpanContext | undefined;
+    if (span.parentSpanContext) {
+      const { traceState: parentTraceState, ...restParentSpanContext } = span.parentSpanContext;
+      serializableParentSpanContext = {
+        traceState: parentTraceState?.serialize(),
+        ...restParentSpanContext,
+      };
+    }
+
+    return {
+      name: span.name,
+      kind: span.kind,
+      spanContext: serializableSpanContext,
+      parentSpanContext: serializableParentSpanContext,
+      startTime: span.startTime,
+      endTime: span.endTime,
+      status: span.status,
+      attributes: span.attributes,
+      links: span.links,
+      events: span.events,
+      duration: span.duration,
+      ended: span.ended,
+      droppedAttributesCount: span.droppedAttributesCount,
+      droppedEventsCount: span.droppedEventsCount,
+      droppedLinksCount: span.droppedLinksCount,
+      instrumentationScope: span.instrumentationScope,
+    };
+  }
+}

package/src/workflow/workflow-imports-impl.ts

@@ -0,0 +1,14 @@
+/**
+ * Real workflow imports for otel interceptors.
+ * This replaces the stub via webpack alias when bundled.
+ *
+ * @module
+ */
+export {
+  inWorkflowContext,
+  proxySinks,
+  workflowInfo,
+  AsyncLocalStorage,
+  ContinueAsNew,
+  getRandomStream,
+} from '@temporalio/workflow';

package/src/workflow/workflow-imports.ts

@@ -0,0 +1,39 @@
+/**
+ * Workflow imports stub module.
+ *
+ * This module provides stubs for workflow functionality needed by interceptors.
+ * When bundled by the workflow bundler, this is replaced with the real
+ * implementation via NormalModuleReplacementPlugin.
+ *
+ * @module
+ */
+import type {
+  inWorkflowContext as inWorkflowContextT,
+  workflowInfo as workflowInfoT,
+  proxySinks as proxySinksT,
+  AsyncLocalStorage as AsyncLocalStorageT,
+  ContinueAsNew as ContinueAsNewT,
+  getRandomStream as getRandomStreamT,
+} from '@temporalio/workflow';
+
+import { IllegalStateError } from '@temporalio/common';
+
+// always returns false since if using this implementation, we are outside of workflow context
+export const inWorkflowContext: typeof inWorkflowContextT = () => false;
+
+// All of the following stubs will throw if used
+export const workflowInfo: typeof workflowInfoT = () => {
+  throw new IllegalStateError('Workflow.workflowInfo(...) may only be used from a Workflow Execution.');
+};
+
+export const ContinueAsNew = class ContinueAsNew {} as unknown as typeof ContinueAsNewT;
+
+export const AsyncLocalStorage = class AsyncLocalStorage {} as unknown as typeof AsyncLocalStorageT;
+
+export const proxySinks: typeof proxySinksT = () => {
+  throw new IllegalStateError('Proxied sinks functions may only be used from a Workflow Execution.');
+};
+
+export const getRandomStream: typeof getRandomStreamT = () => {
+  throw new IllegalStateError('Workflow.getRandomStream(...) may only be used from a Workflow Execution.');
+};

package/src/workflow-interceptors.ts

@@ -0,0 +1,14 @@
+/** Not a workflow, just interceptors */
+
+import type { WorkflowInterceptors } from '@temporalio/workflow';
+import {
+  OpenTelemetryInboundInterceptor,
+  OpenTelemetryOutboundInterceptor,
+  OpenTelemetryInternalsInterceptor,
+} from './workflow';
+
+export const interceptors = (): WorkflowInterceptors => ({
+  inbound: [new OpenTelemetryInboundInterceptor()],
+  outbound: [new OpenTelemetryOutboundInterceptor()],
+  internals: [new OpenTelemetryInternalsInterceptor()],
+});