@temporalio/interceptors-opentelemetry 1.13.1 → 1.14.0

package/src/workflow/index.ts

@@ -3,27 +3,40 @@
 import './runtime'; // Patch the Workflow isolate runtime for opentelemetry
 import * as otel from '@opentelemetry/api';
 import * as tracing from '@opentelemetry/sdk-trace-base';
-import {
+import type {
   ActivityInput,
-  ContinueAsNew,
   ContinueAsNewInput,
   DisposeInput,
   GetLogAttributesInput,
+  GetMetricTagsInput,
   LocalActivityInput,
   Next,
+  QueryInput,
   SignalInput,
   SignalWorkflowInput,
   StartChildWorkflowExecutionInput,
+  UpdateInput,
   WorkflowExecuteInput,
   WorkflowInboundCallsInterceptor,
-  workflowInfo,
   WorkflowInternalsInterceptor,
   WorkflowOutboundCallsInterceptor,
+  StartNexusOperationInput,
+  StartNexusOperationOutput,
 } from '@temporalio/workflow';
-import { instrument, extractContextFromHeaders, headersWithContext } from '../instrumentation';
+import {
+  instrument,
+  instrumentSync,
+  extractContextFromHeaders,
+  headersWithContext,
+  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 { ensureWorkflowModuleLoaded, getWorkflowModule, hasSdkFlag } from './workflow-module-loader';
 
 export * from './definitions';
 
@@ -48,15 +61,25 @@ function getTracer(): otel.Tracer {
  *
  * 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.
  */
 export class OpenTelemetryInboundInterceptor implements WorkflowInboundCallsInterceptor {
   protected readonly tracer = getTracer();
 
+  public constructor() {
+    ensureWorkflowModuleLoaded();
+  }
+
   public async execute(
     input: WorkflowExecuteInput,
     next: Next<WorkflowInboundCallsInterceptor, 'execute'>
   ): Promise<unknown> {
-    const context = await extractContextFromHeaders(input.headers);
+    const { workflowInfo, ContinueAsNew } = getWorkflowModule();
+
+    const context = extractContextFromHeaders(input.headers);
+    if (!hasSdkFlag('OpenTelemetryInterceporsAvoidsExtraYields')) await Promise.resolve();
+
     return await instrument({
       tracer: this.tracer,
       spanName: `${SpanName.WORKFLOW_EXECUTE}${SPAN_DELIMITER}${workflowInfo().workflowType}`,
@@ -70,10 +93,65 @@ export class OpenTelemetryInboundInterceptor implements WorkflowInboundCallsInte
     input: SignalInput,
     next: Next<WorkflowInboundCallsInterceptor, 'handleSignal'>
   ): Promise<void> {
-    const context = await extractContextFromHeaders(input.headers);
+    // Tracing of inbound signals was added in v1.11.5.
+    if (!hasSdkFlag('OpenTelemetryInterceptorsTracesInboundSignals')) return next(input);
+
+    const context = extractContextFromHeaders(input.headers);
+    if (!hasSdkFlag('OpenTelemetryInterceporsAvoidsExtraYields')) await Promise.resolve();
+
     return await instrument({
       tracer: this.tracer,
-      spanName: `${SpanName.WORKFLOW_SIGNAL}${SPAN_DELIMITER}${input.signalName}`,
+      spanName: `${SpanName.WORKFLOW_HANDLE_SIGNAL}${SPAN_DELIMITER}${input.signalName}`,
+      fn: () => next(input),
+      context,
+    });
+  }
+
+  public async handleUpdate(
+    input: UpdateInput,
+    next: Next<WorkflowInboundCallsInterceptor, 'handleUpdate'>
+  ): Promise<unknown> {
+    if (!hasSdkFlag('OpenTelemetryInterceptorsInstrumentsAllMethods')) return next(input);
+
+    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 {
+    if (!hasSdkFlag('OpenTelemetryInterceptorsInstrumentsAllMethods')) return next(input);
+
+    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> {
+    if (!hasSdkFlag('OpenTelemetryInterceptorsInstrumentsAllMethods')) return next(input);
+
+    const context = extractContextFromHeaders(input.headers);
+
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.WORKFLOW_HANDLE_QUERY}${SPAN_DELIMITER}${input.queryName}`,
       fn: () => next(input),
       context,
     });
@@ -84,10 +162,16 @@ export class OpenTelemetryInboundInterceptor implements WorkflowInboundCallsInte
  * 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.
  */
 export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsInterceptor {
   protected readonly tracer = getTracer();
 
+  public constructor() {
+    ensureWorkflowModuleLoaded();
+  }
+
   public async scheduleActivity(
     input: ActivityInput,
     next: Next<WorkflowOutboundCallsInterceptor, 'scheduleActivity'>
@@ -96,7 +180,9 @@ export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsIn
       tracer: this.tracer,
       spanName: `${SpanName.ACTIVITY_START}${SPAN_DELIMITER}${input.activityType}`,
       fn: async () => {
-        const headers = await headersWithContext(input.headers);
+        const headers = headersWithContext(input.headers);
+        if (!hasSdkFlag('OpenTelemetryInterceporsAvoidsExtraYields')) await Promise.resolve();
+
         return next({
           ...input,
           headers,
@@ -109,11 +195,16 @@ export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsIn
     input: LocalActivityInput,
     next: Next<WorkflowOutboundCallsInterceptor, 'scheduleLocalActivity'>
   ): Promise<unknown> {
+    // Tracing of local activities was added in v1.11.6.
+    if (!hasSdkFlag('OpenTelemetryInterceptorsTracesLocalActivities')) return next(input);
+
     return await instrument({
       tracer: this.tracer,
       spanName: `${SpanName.ACTIVITY_START}${SPAN_DELIMITER}${input.activityType}`,
       fn: async () => {
-        const headers = await headersWithContext(input.headers);
+        const headers = headersWithContext(input.headers);
+        if (!hasSdkFlag('OpenTelemetryInterceporsAvoidsExtraYields')) await Promise.resolve();
+
         return next({
           ...input,
           headers,
@@ -122,6 +213,24 @@ export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsIn
     });
   }
 
+  public async startNexusOperation(
+    input: StartNexusOperationInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'startNexusOperation'>
+  ): Promise<StartNexusOperationOutput> {
+    if (!hasSdkFlag('OpenTelemetryInterceptorsInstrumentsAllMethods')) return next(input);
+
+    return await instrument({
+      tracer: this.tracer,
+      spanName: `${SpanName.NEXUS_OPERATION_START}${SPAN_DELIMITER}${input.service}${SPAN_DELIMITER}${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);
+        return await next(input);
+      },
+    });
+  }
+
   public async startChildWorkflowExecution(
     input: StartChildWorkflowExecutionInput,
     next: Next<WorkflowOutboundCallsInterceptor, 'startChildWorkflowExecution'>
@@ -130,7 +239,9 @@ export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsIn
       tracer: this.tracer,
       spanName: `${SpanName.CHILD_WORKFLOW_START}${SPAN_DELIMITER}${input.workflowType}`,
       fn: async () => {
-        const headers = await headersWithContext(input.headers);
+        const headers = headersWithContext(input.headers);
+        if (!hasSdkFlag('OpenTelemetryInterceporsAvoidsExtraYields')) await Promise.resolve();
+
         return next({
           ...input,
           headers,
@@ -143,11 +254,14 @@ export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsIn
     input: ContinueAsNewInput,
     next: Next<WorkflowOutboundCallsInterceptor, 'continueAsNew'>
   ): Promise<never> {
+    const { ContinueAsNew } = getWorkflowModule();
     return await instrument({
       tracer: this.tracer,
       spanName: `${SpanName.CONTINUE_AS_NEW}${SPAN_DELIMITER}${input.options.workflowType}`,
       fn: async () => {
-        const headers = await headersWithContext(input.headers);
+        const headers = headersWithContext(input.headers);
+        if (!hasSdkFlag('OpenTelemetryInterceporsAvoidsExtraYields')) await Promise.resolve();
+
         return next({
           ...input,
           headers,
@@ -165,7 +279,9 @@ export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsIn
       tracer: this.tracer,
       spanName: `${SpanName.WORKFLOW_SIGNAL}${SPAN_DELIMITER}${input.signalName}`,
       fn: async () => {
-        const headers = await headersWithContext(input.headers);
+        const headers = headersWithContext(input.headers);
+        if (!hasSdkFlag('OpenTelemetryInterceporsAvoidsExtraYields')) await Promise.resolve();
+
         return next({
           ...input,
           headers,
@@ -191,6 +307,24 @@ export class OpenTelemetryOutboundInterceptor implements WorkflowOutboundCallsIn
       return next(input);
     }
   }
+
+  public getMetricTags(
+    input: GetMetricTagsInput,
+    next: Next<WorkflowOutboundCallsInterceptor, 'getMetricTags'>
+  ): GetMetricTagsInput {
+    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);
+    }
+  }
 }
 
 export class OpenTelemetryInternalsInterceptor implements WorkflowInternalsInterceptor {

package/src/workflow/runtime.ts

@@ -2,9 +2,11 @@
  * Sets global variables required for importing opentelemetry in isolate
  * @module
  */
-import { inWorkflowContext } from '@temporalio/workflow';
+import { getWorkflowModuleIfAvailable } from './workflow-module-loader';
 
-if (inWorkflowContext()) {
+const inWorkflowContext = getWorkflowModuleIfAvailable()?.inWorkflowContext;
+
+if (inWorkflowContext?.()) {
   // Required by opentelemetry (pretend to be a browser)
   Object.assign(globalThis, {
     performance: {

package/src/workflow/span-exporter.ts

@@ -1,13 +1,17 @@
 import * as tracing from '@opentelemetry/sdk-trace-base';
 import { ExportResult, ExportResultCode } from '@opentelemetry/core';
-import * as wf from '@temporalio/workflow';
 import { OpenTelemetrySinks, SerializableSpan } from './definitions';
+import { ensureWorkflowModuleLoaded, getWorkflowModuleIfAvailable } from './workflow-module-loader';
 
-const { exporter } = wf.proxySinks<OpenTelemetrySinks>();
+const exporter = getWorkflowModuleIfAvailable()?.proxySinks<OpenTelemetrySinks>()?.exporter;
 
 export class SpanExporter implements tracing.SpanExporter {
+  public constructor() {
+    ensureWorkflowModuleLoaded();
+  }
+
   public export(spans: tracing.ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
-    exporter.export(spans.map((span) => this.makeSerializable(span)));
+    exporter!.export(spans.map((span) => this.makeSerializable(span)));
     resultCallback({ code: ExportResultCode.SUCCESS });
   }
 

package/src/workflow/workflow-module-loader.ts

@@ -0,0 +1,64 @@
+/**
+ * Utilities for working with a possibly missing `@temporalio/workflow` peer dependency
+ * @module
+ */
+import type * as WorkflowModule from '@temporalio/workflow';
+import type { SdkFlags as SdkFlagsT } from '@temporalio/workflow/lib/flags';
+
+type SdkFlags = typeof SdkFlagsT;
+
+// @temporalio/workflow is an optional peer dependency.
+// It can be missing as long as the user isn't attempting to construct a workflow interceptor.
+// If we start shipping ES modules alongside CJS, we will have to reconsider
+// this dynamic import as `import` is async for ES modules.
+let workflowModule: typeof WorkflowModule | undefined;
+let workflowModuleLoadError: any | undefined;
+
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  workflowModule = require('@temporalio/workflow');
+} catch (err) {
+  // Capture the module not found error to rethrow if the module is required
+  workflowModuleLoadError = err;
+}
+
+/**
+ * Returns `@temporalio/workflow` module if present.
+ * Throws if the module failed to load
+ */
+export function getWorkflowModule(): typeof WorkflowModule {
+  if (workflowModuleLoadError) {
+    throw workflowModuleLoadError;
+  }
+  return workflowModule!;
+}
+
+/**
+ * Returns if an SDK flag was set
+ *
+ * Expects to be called only after `ensureWorkflowModuleLoaded`.
+ * Will throw if `@temporalio/workflow` is not available
+ */
+export function hasSdkFlag(flag: keyof SdkFlags): boolean {
+  const { SdkFlags } = require('@temporalio/workflow/lib/flags') as typeof import('@temporalio/workflow/lib/flags'); // eslint-disable-line @typescript-eslint/no-require-imports
+  const { getActivator } =
+    require('@temporalio/workflow/lib/global-attributes') as typeof import('@temporalio/workflow/lib/global-attributes'); // eslint-disable-line @typescript-eslint/no-require-imports
+
+  return getActivator().hasFlag(SdkFlags[flag]);
+}
+
+/**
+ * Checks if the workflow module loaded successfully and throws if not.
+ */
+export function ensureWorkflowModuleLoaded(): void {
+  if (workflowModuleLoadError) {
+    throw workflowModuleLoadError;
+  }
+}
+
+/**
+ * Returns the workflow module if available, or undefined if it failed to load.
+ */
+export function getWorkflowModuleIfAvailable(): typeof WorkflowModule | undefined {
+  return workflowModule;
+}