@aws/durable-execution-sdk-js-otel 1.0.0 → 1.2.0

package/dist-cjs/{global-id-generator.js → plugin-registration.js}

@@ -227,7 +227,8 @@ function hasValidTraceId(extracted) {
     return extracted != null && isValidTraceId(extracted.traceId);
 }
 /**
- * Reads the X-Ray trace header from the `_X_AMZN_TRACE_ID` environment variable.
+ * Parses an X-Ray trace header into the context used by the execution trace
+ * resolver.
  *
  * The durable execution backend propagates the same Root trace ID to every
  * invocation, so all invocations of the same execution share one traceId.
@@ -244,10 +245,9 @@ function hasValidTraceId(extracted) {
  * as invalid (it is well-formed hex but not a usable ID). A valid Root with no
  * usable Parent is still returned (the trace ID is usable on its own).
  *
- * Returns undefined when _X_AMZN_TRACE_ID is missing or has no valid Root.
+ * Returns undefined when the header is missing or has no valid Root.
  */
-function xRayContextExtractor(_info) {
-    const header = process.env._X_AMZN_TRACE_ID;
+function parseXRayTraceHeader(header) {
     if (!header) {
         return undefined;
     }
@@ -289,6 +289,12 @@ function xRayContextExtractor(_info) {
             : "UNDECIDED";
     return { traceId, parentSpanId, sampling };
 }
+/**
+ * Reads the X-Ray trace header from the `_X_AMZN_TRACE_ID` environment variable.
+ */
+function xRayContextExtractor(_info) {
+    return parseXRayTraceHeader(process.env._X_AMZN_TRACE_ID);
+}
 /**
  * Reads W3C traceparent from `context.clientContext.custom.traceparent`.
  *
@@ -409,6 +415,17 @@ function tryInstallDurableSampler(tracer) {
         return undefined;
     }
 }
+/** Whether this tracer still uses the bridge that controls SDK span decisions. */
+function isDurableSamplerInstalled(tracer, sampler) {
+    if (!sampler)
+        return false;
+    try {
+        return Reflect.get(tracer, SAMPLER_FIELD) === sampler;
+    }
+    catch {
+        return false;
+    }
+}
 function getConfiguredSampler(tracer) {
     try {
         const sampler = Reflect.get(tracer, SAMPLER_FIELD);
@@ -443,6 +460,26 @@ function canonicalTraceId(extracted, executionArn, executionStartTimestamp) {
     }
     return deriveTraceIdFromArn(executionArn, executionStartTimestamp);
 }
+/**
+ * Derives the trace ID used by the OpenTelemetry plugins for a durable
+ * execution with the default X-Ray context extractor.
+ *
+ * A valid `Root` from `_X_AMZN_TRACE_ID` takes precedence. When the header is
+ * missing or malformed, the trace ID is derived from the execution ARN and
+ * stable execution start timestamp using the same resolver as the plugins.
+ *
+ * Pass the same execution start timestamp supplied to the plugin when no valid
+ * X-Ray Root is available. If the timestamp is unavailable to both callers,
+ * omit it to use the deterministic ARN-only fallback.
+ *
+ * @param environment - Environment containing the optional X-Ray trace header
+ * @param executionArn - The durable execution ARN
+ * @param executionStartTimestamp - Stable start time of the durable execution
+ * @returns The 32-character lowercase hexadecimal execution trace ID
+ */
+function deriveExecutionTraceId(environment, executionArn, executionStartTimestamp) {
+    return canonicalTraceId(parseXRayTraceHeader(environment._X_AMZN_TRACE_ID), executionArn, executionStartTimestamp);
+}
 /**
  * Flags for an explicit upstream decision, or the sampler's decision
  * (`whenUndecided`) when the upstream did not decide. The supplier is consulted
@@ -508,9 +545,15 @@ function resolveExecutionTraceContext(extracted, canonical, executionArn, rootSa
     const samplingContext = hasValidTraceId(extracted) ? extracted : undefined;
     const decision = explicitDecision(samplingContext, rootSamplingDecision);
     const flags = traceFlagsFromDecision(decision);
+    // This synthetic root is created and exported by one durable execution,
+    // so its span identity must remain owned by that execution. Multiple
+    // executions may legitimately share a propagated trace ID, but reusing one
+    // span ID across independently timed/resource-scoped roots would create
+    // conflicting OpenTelemetry span identities.
+    const syntheticRootSpanId = deriveExecutionRootSpanId(executionArn);
     const syntheticRoot = {
         traceId: canonical,
-        spanId: deriveExecutionRootSpanId(executionArn),
+        spanId: syntheticRootSpanId,
         traceFlags: flags,
         isRemote: false,
     };
@@ -620,18 +663,82 @@ function tryInstallGlobalIdGenerator(tracer) {
     }
 }
 
+function isExternalOperation(info) {
+    return (info.type === "WAIT" ||
+        info.type === "INVOKE" ||
+        info.type === "CHAINED_INVOKE" ||
+        info.type === "CALLBACK");
+}
+/** Invocation-local bookkeeping; no export acknowledgement is persisted. */
+class ExternalCompletions {
+    pending = new Map();
+    exported = new Set();
+    observe(operations = {}) {
+        for (const info of Object.values(operations)) {
+            if (info.id &&
+                isExternalOperation(info) &&
+                (info.status === "SUCCEEDED" ||
+                    info.status === "FAILED" ||
+                    info.status === "TIMED_OUT" ||
+                    info.status === "STOPPED" ||
+                    info.status === "CANCELLED") &&
+                !this.exported.has(info.id)) {
+                this.pending.set(info.id, info);
+            }
+        }
+    }
+    shouldSkip(info) {
+        // Replay describes the SDK's initial state, not whether a completion that
+        // arrived later in a checkpoint response has already been exported.
+        return (isExternalOperation(info) &&
+            (this.exported.has(info.id) ||
+                (info.isReplay && !this.pending.has(info.id))));
+    }
+    markExported(info) {
+        if (isExternalOperation(info)) {
+            this.exported.add(info.id);
+            this.pending.delete(info.id);
+        }
+    }
+    clear() {
+        this.pending.clear();
+        this.exported.clear();
+    }
+}
+
+/** Encodes the already resolved execution state without creating a span. */
+function createPropagationMetadata(input, executionArn, traceId, traceFlags) {
+    if (input.executionArn !== executionArn || !isValidTraceId(traceId))
+        return undefined;
+    const spanId = deriveSpanIdFromOperationId(input.operationId, executionArn);
+    if (!isValidSpanId(spanId))
+        return undefined;
+    return Object.freeze({
+        xAmznTraceId: `Root=1-${traceId.slice(0, 8)}-${traceId.slice(8)};Parent=${spanId};Sampled=${traceFlags & 1 ? "1" : "0"}`,
+    });
+}
+
+// Match the SDK-owned opt-in protocol without a runtime import of the core SDK.
+// A local symbol declaration also keeps old-core TypeScript consumers compatible.
+const PLUGIN_REGISTRATION = Symbol.for("aws.lambda.durable.instrumentation.plugin-registration");
+
 exports.DeterministicIdGenerator = DeterministicIdGenerator;
+exports.ExternalCompletions = ExternalCompletions;
+exports.PLUGIN_REGISTRATION = PLUGIN_REGISTRATION;
 exports.canonicalTraceId = canonicalTraceId;
+exports.createPropagationMetadata = createPropagationMetadata;
 exports.createTracerProvider = createTracerProvider;
 exports.deriveExecutionRootSpanId = deriveExecutionRootSpanId;
+exports.deriveExecutionTraceId = deriveExecutionTraceId;
 exports.deriveSpanIdFromOperationId = deriveSpanIdFromOperationId;
 exports.deriveTraceIdFromArn = deriveTraceIdFromArn;
 exports.deriveTraceIdFromXRayRoot = deriveTraceIdFromXRayRoot;
 exports.deriveWorkflowSpanId = deriveWorkflowSpanId;
+exports.isDurableSamplerInstalled = isDurableSamplerInstalled;
 exports.resolveExecutionTraceContext = resolveExecutionTraceContext;
 exports.rootSamplingDecision = rootSamplingDecision;
 exports.tryInstallDurableSampler = tryInstallDurableSampler;
 exports.tryInstallGlobalIdGenerator = tryInstallGlobalIdGenerator;
 exports.w3cClientContextExtractor = w3cClientContextExtractor;
 exports.xRayContextExtractor = xRayContextExtractor;
-//# sourceMappingURL=global-id-generator.js.map
+//# sourceMappingURL=plugin-registration.js.map

package/dist-cjs/plugin-registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registration.js","sources":["../src/deterministic-id-generator.ts","../src/context-extractors.ts","../src/global-sampler.ts","../src/execution-trace-context.ts","../src/otel-plugin-provider.ts","../src/global-id-generator.ts","../src/external-completions.ts","../src/propagation-metadata.ts","../src/plugin-registration.ts"],"names":["AsyncLocalStorage","RandomIdGenerator","createHash","SamplingDecision","TraceFlags","ROOT_CONTEXT","SpanKind","trace"],"mappings":"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"}

package/dist-types/context-extractors.d.ts

@@ -0,0 +1,111 @@
+import type { InvocationInfo } from "@aws/durable-execution-sdk-js";
+/**
+ * The upstream sampling decision carried by a propagated context.
+ *
+ * Tri-state so that "no usable decision" is distinct from an explicit
+ * "do not sample". Extractors use `SAMPLED` / `NOT_SAMPLED` only for explicit
+ * upstream values (for example X-Ray `Sampled=1` / `Sampled=0`, or a W3C
+ * `traceparent` sampled bit); anything absent or unusable is `UNDECIDED`, which
+ * lets the configured sampler decide.
+ */
+export type Sampling = "SAMPLED" | "NOT_SAMPLED" | "UNDECIDED";
+/**
+ * Result type returned by context extractors.
+ *
+ * `sampling` is the tri-state upstream decision. `traceFlags` is retained for
+ * backward compatibility with custom extractors: when `sampling` is omitted it
+ * is derived from `traceFlags` (sampled bit set -> `SAMPLED`, clear ->
+ * `NOT_SAMPLED`), and when neither is provided the decision is `UNDECIDED`.
+ *
+ * The resolver adopts the trace ID and parent span ID only when they are valid
+ * (well-formed, non-zero); an extractor that cannot supply a usable value
+ * returns `undefined` for it so the resolver falls back to a deterministic
+ * ARN-derived trace and synthetic root.
+ */
+export type ContextExtractorResult = {
+    traceId: string;
+    parentSpanId?: string;
+    traceFlags?: number;
+    sampling?: Sampling;
+} | undefined;
+/**
+ * True when `traceId` is a well-formed, non-zero 32-char hex OTel trace ID.
+ *
+ * Validity is stricter than a format match: an all-zero ID is well-formed hex
+ * but invalid, and anchoring an execution on it would split the trace.
+ */
+export declare function isValidTraceId(traceId: string | undefined): traceId is string;
+/**
+ * True when `spanId` is a well-formed, non-zero 16-char hex OTel span ID.
+ */
+export declare function isValidSpanId(spanId: string | undefined): spanId is string;
+/**
+ * Resolves the tri-state sampling decision for an extracted context.
+ *
+ * Prefers an explicit `sampling` value; otherwise derives from `traceFlags`
+ * when present; otherwise `UNDECIDED`.
+ */
+export declare function resolveSampling(extracted: {
+    traceFlags?: number;
+    sampling?: Sampling;
+}): Sampling;
+/**
+ * True when the extracted context carries a complete remote parent: a valid
+ * trace ID and a valid parent span ID, so it can serve as a remote parent.
+ */
+export declare function hasCompleteRemoteParent(extracted: ContextExtractorResult): extracted is {
+    traceId: string;
+    parentSpanId: string;
+} & NonNullable<ContextExtractorResult>;
+/**
+ * True when the extracted context carries a valid (well-formed, non-zero) trace
+ * ID that the resolver can anchor the durable execution trace on.
+ */
+export declare function hasValidTraceId(extracted: ContextExtractorResult): extracted is {
+    traceId: string;
+} & NonNullable<ContextExtractorResult>;
+/**
+ * A function that extracts upstream trace context from the invocation environment.
+ */
+export type ContextExtractor = (info: InvocationInfo) => ContextExtractorResult;
+/**
+ * Parses an X-Ray trace header into the context used by the execution trace
+ * resolver.
+ *
+ * The durable execution backend propagates the same Root trace ID to every
+ * invocation, so all invocations of the same execution share one traceId.
+ *
+ * X-Ray Header format:
+ *   Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
+ *
+ * - Extract Root value, strip "1-" prefix and all "-" to get 32-char hex traceId
+ * - Extract Parent value for parentSpanId (16-char hex)
+ * - Extract Sampled: `1` -> SAMPLED, `0` -> NOT_SAMPLED, anything else undecided
+ *
+ * `Root`, `Parent`, and `Sampled` are parsed independently: only `Sampled=1`
+ * and `Sampled=0` are authoritative, and an all-zero Root or Parent is rejected
+ * as invalid (it is well-formed hex but not a usable ID). A valid Root with no
+ * usable Parent is still returned (the trace ID is usable on its own).
+ *
+ * Returns undefined when the header is missing or has no valid Root.
+ */
+export declare function parseXRayTraceHeader(header: string | undefined): ContextExtractorResult;
+/**
+ * Reads the X-Ray trace header from the `_X_AMZN_TRACE_ID` environment variable.
+ */
+export declare function xRayContextExtractor(_info: InvocationInfo): ContextExtractorResult;
+/**
+ * Reads W3C traceparent from `context.clientContext.custom.traceparent`.
+ *
+ * W3C traceparent format:
+ *   00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ *   Format: version-traceId-parentId-traceFlags
+ *
+ * - traceId is 32 hex chars
+ * - parentId is 16 hex chars
+ * - flags is 2 hex chars (parsed to number)
+ *
+ * Returns undefined when clientContext or traceparent is missing or malformed.
+ */
+export declare function w3cClientContextExtractor(info: InvocationInfo): ContextExtractorResult;
+//# sourceMappingURL=context-extractors.d.ts.map

package/dist-types/context-extractors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-extractors.d.ts","sourceRoot":"","sources":["../src/context-extractors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IACE,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GACD,SAAS,CAAC;AAOd;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,IAAI,MAAM,CAM7E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,IAAI,MAAM,CAM1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GAAG,QAAQ,CAQX;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,sBAAsB,GAChC,SAAS,IAAI;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,WAAW,CAAC,sBAAsB,CAAC,CAMtC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,sBAAsB,GAChC,SAAS,IAAI;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,WAAW,CAAC,sBAAsB,CAAC,CAEtC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,sBAAsB,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,sBAAsB,CAiDxB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,GACpB,sBAAsB,CAExB;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,cAAc,GACnB,sBAAsB,CASxB"}

package/dist-types/deterministic-id-generator.d.ts

@@ -0,0 +1,95 @@
+import { type IdGenerator } from "@opentelemetry/sdk-trace-node";
+export interface IdOverride {
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * An OpenTelemetry IdGenerator with execution-scoped deterministic overrides.
+ *
+ * Overrides are active only while {@link withIds} runs. All other ID generation
+ * is delegated to the fallback generator. AsyncLocalStorage makes the override
+ * visible to the provider-owned generator without leaking it to unrelated spans
+ * or concurrent durable executions.
+ */
+export declare class DeterministicIdGenerator implements IdGenerator {
+    private readonly fallbackIdGenerator;
+    private static readonly idOverrides;
+    constructor(fallbackIdGenerator?: IdGenerator);
+    /**
+     * Runs a synchronous span-creation callback with deterministic IDs.
+     *
+     * The span ID is consumed on its first use so re-entrant ID generation cannot
+     * accidentally assign the same ID to more than one span.
+     */
+    withIds<T>(ids: IdOverride, fn: () => T): T;
+    /** Generate a 32-char lowercase hex trace ID. */
+    generateTraceId(): string;
+    /** Generate a 16-char lowercase hex span ID. */
+    generateSpanId(): string;
+}
+/**
+ * Derive a deterministic trace ID from an X-Ray Root field.
+ * Strips the `Root=1-` prefix and all `-` separators to produce
+ * a valid 32-character lowercase hex OpenTelemetry trace ID.
+ *
+ * @param xRayRoot - The Root field value, e.g. "1-5759e988-bd862e3fe1be46a994272793"
+ * @returns A 32-char lowercase hex string, or undefined if the input is invalid
+ */
+export declare function deriveTraceIdFromXRayRoot(xRayRoot: string): string | undefined;
+/**
+ * Derive a deterministic trace ID from an execution ARN and its durable start
+ * timestamp by hashing them with SHA-256 and truncating to the first 32
+ * lowercase hex characters.
+ *
+ * The timestamp is optional for callers that do not have it. When omitted, the
+ * ARN-only derivation is retained as a deterministic fallback.
+ *
+ * @param executionArn - The execution ARN string
+ * @param executionStartTimestamp - Stable start time of the durable execution
+ * @returns A 32-char lowercase hex string
+ */
+export declare function deriveTraceIdFromArn(executionArn: string, executionStartTimestamp?: Date): string;
+/**
+ * Derive a deterministic span ID from an operation ID scoped to a specific execution.
+ * Hashes `executionArn + ":" + operationId` with SHA-256 and truncates to the first
+ * 16 lowercase hex characters.
+ *
+ * The executionArn is included in the hash input to avoid span ID collisions when
+ * different executions (e.g., a parent and child workflow) share the same trace and
+ * have operations at the same positional ID.
+ *
+ * @param operationId - The operation ID string (positional identifier within an execution)
+ * @param executionArn - The execution ARN, used to scope span IDs per execution
+ * @returns A 16-char lowercase hex string
+ */
+export declare function deriveSpanIdFromOperationId(operationId: string, executionArn: string): string;
+/**
+ * Derive a deterministic span ID for a Workflow_Span from an execution ARN.
+ * Hashes `"workflow:" + executionArn` with SHA-256 and truncates to the first
+ * 16 lowercase hex characters.
+ *
+ * The "workflow:" prefix acts as a salt to ensure the resulting span ID is
+ * distinct from IDs produced by `deriveSpanIdFromOperationId` for the same ARN.
+ *
+ * @param executionArn - The execution ARN string (must be non-empty)
+ * @returns A 16-char lowercase hex string, never equal to "0000000000000000"
+ * @throws Error if the execution ARN is an empty string
+ */
+export declare function deriveWorkflowSpanId(executionArn: string): string;
+/**
+ * Derive a deterministic span ID for the synthetic execution root from an
+ * execution ARN. Hashes `"execution-root:" + executionArn` with SHA-256 and
+ * truncates to the first 16 lowercase hex characters.
+ *
+ * The `"execution-root:"` prefix is a distinct namespace from
+ * `deriveWorkflowSpanId` (`"workflow:"`) and `deriveSpanIdFromOperationId`
+ * (`"<arn>:<opId>"`), so the synthetic root never collides with the Workflow or
+ * operation spans that share the execution trace. Stable across reinvocations
+ * so the same synthetic root is the common ancestor every invocation.
+ *
+ * @param executionArn - The execution ARN string (must be non-empty)
+ * @returns A 16-char lowercase hex string, never equal to "0000000000000000"
+ * @throws Error if the execution ARN is an empty string
+ */
+export declare function deriveExecutionRootSpanId(executionArn: string): string;
+//# sourceMappingURL=deterministic-id-generator.d.ts.map

package/dist-types/deterministic-id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic-id-generator.d.ts","sourceRoot":"","sources":["../src/deterministic-id-generator.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAyB,YAAW,WAAW;IAIxD,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAHtC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAuC;gBAGvD,mBAAmB,GAAE,WAAqC;IAG7E;;;;;OAKG;IACH,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAI3C,iDAAiD;IACjD,eAAe,IAAI,MAAM;IAQzB,gDAAgD;IAChD,cAAc,IAAI,MAAM;CASzB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAuBpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,uBAAuB,CAAC,EAAE,IAAI,GAC7B,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM,CAKR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAiBjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAetE"}

package/dist-types/execution-plugin-provider.d.ts

@@ -0,0 +1,7 @@
+import { ExecutionOtelPlugin } from "./execution-plugin";
+export declare const durableExecutionPluginProvider: {
+    pluginApiVersion: 1;
+    pluginType: typeof ExecutionOtelPlugin;
+    createPlugin: () => ExecutionOtelPlugin;
+};
+//# sourceMappingURL=execution-plugin-provider.d.ts.map

package/dist-types/execution-plugin-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-plugin-provider.d.ts","sourceRoot":"","sources":["../src/execution-plugin-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,eAAO,MAAM,8BAA8B;;;;CAI0B,CAAC"}

package/dist-types/execution-plugin.d.ts

@@ -0,0 +1,88 @@
+import type { DurableInstrumentationPlugin, InvocationInfo, InvocationEndInfo, OperationInfo, OperationEndInfo, AttemptInfo, AttemptEndInfo, OperationChangeInfo } from "@aws/durable-execution-sdk-js";
+import type { DurableExecutionInvocationOutput } from "@aws/durable-execution-sdk-js";
+import type { OtelPluginConfig } from "./otel-plugin-config";
+import type { PropagationInput, PropagationMetadata } from "./propagation-metadata";
+import { PLUGIN_REGISTRATION } from "./plugin-registration";
+/**
+ * OpenTelemetry instrumentation plugin for durable executions.
+ *
+ * Implements the DurableInstrumentationPlugin interface. The Workflow span joins
+ * the execution trace by parenting onto the resolved execution ancestor (a
+ * propagated remote parent or a synthetic execution root), so the whole
+ * execution shares one trace. Operation spans parent onto the Workflow span and
+ * the per-invocation Invocation span is a correlation sibling (linked from, not
+ * a parent of, the operation spans). Both the Workflow span and each operation
+ * span are deferred: their identity is carried as a non-recording context and
+ * the single recording span is created and ended together at terminal /
+ * onOperationEnd, so nothing is left un-ended across invocations (issue #831).
+ */
+export declare class ExecutionOtelPlugin implements DurableInstrumentationPlugin {
+    private static readonly [PLUGIN_REGISTRATION];
+    private idGenerator;
+    private readonly contextExtractor;
+    private tracerProvider;
+    private tracer;
+    private readonly instrumentationName;
+    private workflowSpan;
+    private invocationSpan;
+    private spanMap;
+    private operationContexts;
+    private operationStarts;
+    private executionArn;
+    private executionTraceId;
+    private executionTraceFlags;
+    private executionSamplingDecision;
+    private executionAncestor;
+    private executionStartTimestamp;
+    private syntheticRootAnchorTimestamp;
+    private syntheticRootMaterialized;
+    private readonly usesGlobalProvider;
+    private globalIdGeneratorInstalled;
+    private durableSampler;
+    private tracingEnabled;
+    private readonly externalCompletions;
+    private readonly workflowSpanName;
+    private readonly enrichLogger;
+    constructor(config?: OtelPluginConfig);
+    onInvocationStart(info: InvocationInfo): Promise<void>;
+    providePropagationMetadata(input: PropagationInput): PropagationMetadata | undefined;
+    wrapInvocation(_info: InvocationInfo, fn: () => Promise<DurableExecutionInvocationOutput>): Promise<DurableExecutionInvocationOutput>;
+    onInvocationEnd(info: InvocationEndInfo): Promise<void>;
+    /** Creates at most one SDK-owned root per invocation; the caller ends it. */
+    private createSyntheticRoot;
+    private ensureGlobalIdGeneratorInstalled;
+    private resetInvocationState;
+    private startSpan;
+    /**
+     * The parent context for the Invocation span: the active ambient span when it
+     * is already on the execution trace, otherwise the execution ancestor so the
+     * Invocation span stays within the same trace.
+     */
+    private invocationParentContext;
+    /**
+     * Builds span links to the invocation span for child spans.
+     *
+     * Always links to the plugin-created Invocation_Span (this.invocationSpan),
+     * which is created in both default-provider and non-default modes.
+     */
+    private buildInvocationLinks;
+    onOperationStart(info: OperationInfo): Promise<void>;
+    wrapChildContextFn(info: OperationInfo, fn: () => unknown): unknown;
+    onOperationEnd(info: OperationEndInfo): Promise<void>;
+    /**
+     * The parent context for an operation or attempt span: the parent operation's
+     * deterministic identity, or the Workflow identity for a top-level operation.
+     * A completion notification can arrive without traversing its parent in this
+     * invocation (for example, a completed child context skipped during replay).
+     */
+    private resolveOperationParentContext;
+    /** The earlier of two timestamps, ignoring undefined; undefined only when both are. */
+    private earliestStart;
+    private getAttemptKey;
+    onOperationAttemptStart(info: AttemptInfo): Promise<void>;
+    wrapOperationAttemptFn(info: AttemptInfo, fn: () => unknown): unknown;
+    onOperationAttemptEnd(info: AttemptEndInfo): Promise<void>;
+    onOperationChange(info: OperationChangeInfo): Promise<void>;
+    enrichLogContext(): Record<string, string | number | boolean> | undefined;
+}
+//# sourceMappingURL=execution-plugin.d.ts.map

package/dist-types/execution-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-plugin.d.ts","sourceRoot":"","sources":["../src/execution-plugin.ts"],"names":[],"mappings":"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"}