@aws/durable-execution-sdk-js-otel 0.0.1 → 0.1.1

package/dist-cjs/index.js

@@ -0,0 +1,546 @@
+'use strict';
+
+var api = require('@opentelemetry/api');
+var instrumentationAwsSdk = require('@opentelemetry/instrumentation-aws-sdk');
+var instrumentation = require('@opentelemetry/instrumentation');
+var node_crypto = require('node:crypto');
+
+/**
+ * A custom OpenTelemetry IdGenerator that produces deterministic trace and span IDs
+ * derived from execution metadata (X-Ray headers, execution ARNs, operation IDs)
+ * rather than random values.
+ *
+ * This ensures that spans from different Lambda invocations of the same durable
+ * execution are stitched into a single coherent trace.
+ */
+class DeterministicIdGenerator {
+    traceId;
+    nextSpanId;
+    /**
+     * Set the trace ID for all subsequent generateTraceId() calls.
+     * This is persistent until setTraceId is called again.
+     */
+    setTraceId(traceId) {
+        this.traceId = traceId;
+    }
+    /**
+     * Set the span ID to return on the next single generateSpanId() call.
+     * This is a one-shot override: it is consumed on the next call and then
+     * reverts to default behavior.
+     */
+    setNextSpanId(spanId) {
+        this.nextSpanId = spanId;
+    }
+    /**
+     * Generate a 32-char lowercase hex trace ID.
+     *
+     * If setTraceId has been called, returns that value persistently.
+     * Otherwise returns a random 32-char hex string as fallback.
+     */
+    generateTraceId() {
+        if (this.traceId) {
+            return this.traceId;
+        }
+        // Fallback: generate a random trace ID
+        return node_crypto.createHash("sha256")
+            .update(Math.random().toString())
+            .digest("hex")
+            .slice(0, 32);
+    }
+    /**
+     * Generate a 16-char lowercase hex span ID.
+     *
+     * If setNextSpanId has been called, returns that value once (one-shot)
+     * and then clears it. Otherwise returns a random 16-char hex string.
+     */
+    generateSpanId() {
+        if (this.nextSpanId) {
+            const spanId = this.nextSpanId;
+            this.nextSpanId = undefined;
+            return spanId;
+        }
+        // Fallback: generate a random span ID
+        return node_crypto.createHash("sha256")
+            .update(Math.random().toString())
+            .digest("hex")
+            .slice(0, 16);
+    }
+}
+/**
+ * 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
+ */
+function deriveTraceIdFromXRayRoot(xRayRoot) {
+    // Strip "Root=" prefix if present
+    let root = xRayRoot;
+    if (root.startsWith("Root=")) {
+        root = root.slice(5);
+    }
+    // Strip the version prefix "1-"
+    if (root.startsWith("1-")) {
+        root = root.slice(2);
+    }
+    else {
+        return undefined;
+    }
+    // Remove all dashes
+    const hex = root.replace(/-/g, "");
+    // Validate: must be exactly 32 lowercase hex characters
+    if (hex.length !== 32 || !/^[0-9a-f]{32}$/.test(hex)) {
+        return undefined;
+    }
+    return hex;
+}
+/**
+ * Derive a deterministic trace ID from an execution ARN by hashing it
+ * with SHA-256 and truncating to the first 32 lowercase hex characters.
+ *
+ * @param executionArn - The execution ARN string
+ * @returns A 32-char lowercase hex string
+ */
+function deriveTraceIdFromArn(executionArn) {
+    return node_crypto.createHash("sha256").update(executionArn).digest("hex").slice(0, 32);
+}
+/**
+ * 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
+ */
+function deriveSpanIdFromOperationId(operationId, executionArn) {
+    return node_crypto.createHash("sha256")
+        .update(executionArn + ":" + operationId)
+        .digest("hex")
+        .slice(0, 16);
+}
+
+/**
+ * Reads the X-Ray trace header from the `_X_AMZN_TRACE_ID` environment variable.
+ *
+ * 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)
+ *
+ * Returns undefined when _X_AMZN_TRACE_ID is missing or malformed.
+ */
+function xRayContextExtractor(_info) {
+    const header = process.env._X_AMZN_TRACE_ID;
+    if (!header) {
+        return undefined;
+    }
+    // Parse the header into key-value pairs separated by semicolons
+    const fields = new Map();
+    for (const part of header.split(";")) {
+        const eqIdx = part.indexOf("=");
+        if (eqIdx > 0) {
+            const key = part.slice(0, eqIdx).trim();
+            const value = part.slice(eqIdx + 1).trim();
+            fields.set(key, value);
+        }
+    }
+    const root = fields.get("Root");
+    if (!root) {
+        return undefined;
+    }
+    // Root format: 1-5759e988-bd862e3fe1be46a994272793
+    // Strip the "1-" prefix and remove all dashes to get 32-char hex
+    const rootValue = root.startsWith("1-") ? root.slice(2) : root;
+    const traceId = rootValue.replace(/-/g, "").toLowerCase();
+    // Validate: must be exactly 32 hex characters
+    if (!/^[0-9a-f]{32}$/.test(traceId)) {
+        return undefined;
+    }
+    const parent = fields.get("Parent");
+    let parentSpanId;
+    if (parent && /^[0-9a-f]{16}$/.test(parent.toLowerCase())) {
+        parentSpanId = parent.toLowerCase();
+    }
+    return { traceId, parentSpanId };
+}
+/**
+ * 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.
+ */
+function w3cClientContextExtractor(info) {
+    const extendedInfo = info;
+    const traceparent = extendedInfo.context?.clientContext?.custom?.traceparent;
+    if (!traceparent) {
+        return undefined;
+    }
+    return parseW3CTraceparent(traceparent);
+}
+/**
+ * Parses a W3C traceparent header value.
+ *
+ * Format: version-traceId-parentId-flags
+ * Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ */
+function parseW3CTraceparent(traceparent) {
+    const parts = traceparent.split("-");
+    // Must have exactly 4 parts: version, traceId, parentId, flags
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    const [version, traceId, parentId, flags] = parts;
+    // Version must be 2 hex chars
+    if (!/^[0-9a-f]{2}$/.test(version)) {
+        return undefined;
+    }
+    // TraceId must be 32 hex chars
+    if (!/^[0-9a-f]{32}$/.test(traceId)) {
+        return undefined;
+    }
+    // ParentId must be 16 hex chars
+    if (!/^[0-9a-f]{16}$/.test(parentId)) {
+        return undefined;
+    }
+    // Flags must be 2 hex chars
+    if (!/^[0-9a-f]{2}$/.test(flags)) {
+        return undefined;
+    }
+    const traceFlags = parseInt(flags, 16);
+    return {
+        traceId,
+        parentSpanId: parentId,
+        traceFlags,
+    };
+}
+
+const DEFAULT_INSTRUMENTATION_NAME = "aws-durable-execution-sdk-js";
+/**
+ * OpenTelemetry instrumentation plugin for durable executions.
+ *
+ * Implements the DurableInstrumentationPlugin interface to emit distributed
+ * traces that correlate across multiple Lambda invocations of a single
+ * durable execution.
+ */
+class OtelPlugin {
+    tracerProvider;
+    tracer;
+    idGenerator;
+    contextExtractor;
+    // Per-invocation state
+    spanMap = new Map();
+    spanStack = [];
+    invocationSpan;
+    executionArn = "";
+    attemptSpan;
+    constructor(config) {
+        const instrumentationName = config?.instrumentationName ?? DEFAULT_INSTRUMENTATION_NAME;
+        this.idGenerator = new DeterministicIdGenerator();
+        this.contextExtractor = config?.contextExtractor ?? xRayContextExtractor;
+        if (config?.tracerProvider) {
+            this.tracerProvider = config.tracerProvider;
+        }
+        else {
+            this.tracerProvider = api.trace.getTracerProvider();
+            instrumentation.registerInstrumentations({
+                tracerProvider: this.tracerProvider,
+                instrumentations: [
+                    new instrumentationAwsSdk.AwsInstrumentation({
+                        suppressInternalInstrumentation: true,
+                        sqsExtractContextPropagationFromPayload: true,
+                    }),
+                ],
+            });
+        }
+        this.tracer = this.tracerProvider.getTracer(instrumentationName);
+        // Monkey-patch the tracer's ID generator so spans use deterministic IDs.
+        // The _idGenerator field is internal to @opentelemetry/sdk-trace-base's Tracer class.
+        this.tracer._idGenerator = this.idGenerator;
+    }
+    async onInvocationStart(info) {
+        // 1. Store the execution ARN
+        this.executionArn = info.executionArn;
+        // 2. Invoke the context extractor
+        const extractedContext = this.contextExtractor(info);
+        // 3. Set the trace ID on the ID generator
+        if (extractedContext?.traceId) {
+            this.idGenerator.setTraceId(extractedContext.traceId);
+        }
+        else {
+            // Fallback: derive trace ID from ARN
+            const derivedId = deriveTraceIdFromArn(info.executionArn);
+            this.idGenerator.setTraceId(derivedId);
+        }
+        // 4. Create the invocation span
+        this.invocationSpan = this.tracer.startSpan("invocation", {
+            attributes: {
+                "durable.execution.arn": info.executionArn,
+            },
+        });
+    }
+    wrapInvocation(_info, fn) {
+        if (!this.invocationSpan) {
+            return fn();
+        }
+        return api.context.with(api.trace.setSpan(api.context.active(), this.invocationSpan), fn);
+    }
+    async onInvocationEnd(_info) {
+        // 1. End all spans in the stack in reverse order
+        while (this.spanStack.length > 0) {
+            const span = this.spanStack.pop();
+            span.end();
+        }
+        // 2. End the invocation span if it exists
+        if (this.invocationSpan) {
+            this.invocationSpan.end();
+        }
+        // 3. Force flush the tracer provider
+        if ("forceFlush" in this.tracerProvider) {
+            try {
+                await this.tracerProvider.forceFlush();
+            }
+            catch {
+                // Gracefully handle flush errors
+            }
+        }
+        // 4. Clear all per-invocation state
+        this.spanMap.clear();
+        this.spanStack = [];
+        this.invocationSpan = undefined;
+        this.executionArn = "";
+        this.attemptSpan = undefined;
+    }
+    async onOperationStart(info) {
+        const deterministicSpanId = deriveSpanIdFromOperationId(info.id, this.executionArn);
+        const spanName = info.name ?? info.type;
+        // Resolve parent span: use parentId from map, or fall back to invocation span
+        let parentSpan;
+        if (info.parentId && this.spanMap.has(info.parentId)) {
+            parentSpan = this.spanMap.get(info.parentId);
+        }
+        else {
+            parentSpan = this.invocationSpan;
+        }
+        const parentContext = parentSpan
+            ? api.trace.setSpan(api.context.active(), parentSpan)
+            : api.context.active();
+        const attributes = {
+            "durable.execution.arn": this.executionArn,
+            "durable.operation.id": info.id,
+            "durable.operation.type": info.type,
+        };
+        if (info.name) {
+            attributes["durable.operation.name"] = info.name;
+        }
+        if (info.subType) {
+            attributes["durable.operation.subtype"] = info.subType;
+        }
+        let span;
+        if (!info.isReplay) {
+            // Non-replay: use deterministic span ID
+            this.idGenerator.setNextSpanId(deterministicSpanId);
+            span = this.tracer.startSpan(spanName, {
+                attributes,
+                startTime: info.startTimestamp,
+            }, parentContext);
+        }
+        else if (info.type === "CONTEXT" || info.type === "STEP") {
+            // Replay: use random span ID, add Link to deterministic span
+            const traceId = this.invocationSpan?.spanContext().traceId ??
+                this.idGenerator.generateTraceId();
+            span = this.tracer.startSpan(spanName, {
+                attributes,
+                startTime: info.startTimestamp,
+                links: [
+                    {
+                        context: { traceId, spanId: deterministicSpanId, traceFlags: 1 },
+                    },
+                ],
+            }, parentContext);
+        }
+        // Push to map and stack
+        if (span != undefined) {
+            this.spanMap.set(info.id, span);
+            this.spanStack.push(span);
+        }
+    }
+    wrapChildContextFn(info, fn) {
+        const span = this.spanMap.get(info.id);
+        if (!span) {
+            return fn();
+        }
+        return api.context.with(api.trace.setSpan(api.context.active(), span), fn);
+    }
+    async onOperationEnd(info) {
+        // Skip span creation for WAIT, INVOKE, CHAINED_INVOKE, and CALLBACK operations on replay
+        if (info.isReplay &&
+            (info.type === "WAIT" ||
+                info.type === "INVOKE" ||
+                info.type === "CHAINED_INVOKE" ||
+                info.type === "CALLBACK")) {
+            return;
+        }
+        const deterministicSpanId = deriveSpanIdFromOperationId(info.id, this.executionArn);
+        if (this.spanMap.has(info.id)) {
+            // Operation was started in this invocation
+            const span = this.spanMap.get(info.id);
+            // Record error if present
+            if (info.error) {
+                span.setStatus({
+                    code: api.SpanStatusCode.ERROR,
+                    message: info.error.message,
+                });
+                span.recordException(info.error);
+            }
+            // End the span
+            span.end(info.endTimestamp);
+            // Remove from map
+            this.spanMap.delete(info.id);
+            // Remove from stack (find by reference)
+            const stackIndex = this.spanStack.indexOf(span);
+            if (stackIndex !== -1) {
+                this.spanStack.splice(stackIndex, 1);
+            }
+        }
+        else if (!info.isReplay) {
+            // Operation was started in a prior invocation — create Continuation_Span
+            const spanName = info.name ?? info.type;
+            const traceId = this.invocationSpan?.spanContext().traceId ??
+                this.idGenerator.generateTraceId();
+            const parentContext = this.invocationSpan
+                ? api.trace.setSpan(api.context.active(), this.invocationSpan)
+                : api.context.active();
+            const attributes = {
+                "durable.execution.arn": this.executionArn,
+                "durable.operation.id": info.id,
+                "durable.operation.type": info.type,
+            };
+            if (info.name) {
+                attributes["durable.operation.name"] = info.name;
+            }
+            if (info.subType) {
+                attributes["durable.operation.subtype"] = info.subType;
+            }
+            const continuationSpan = this.tracer.startSpan(spanName, {
+                attributes,
+                startTime: info.startTimestamp,
+                links: [
+                    {
+                        context: { traceId, spanId: deterministicSpanId, traceFlags: 1 },
+                    },
+                ],
+            }, parentContext);
+            // Record error if present
+            if (info.error) {
+                continuationSpan.setStatus({
+                    code: api.SpanStatusCode.ERROR,
+                    message: info.error.message,
+                });
+                continuationSpan.recordException(info.error);
+            }
+            // Immediately end
+            continuationSpan.end(info.endTimestamp);
+        }
+    }
+    async onOperationAttemptStart(info) {
+        const deterministicSpanId = deriveSpanIdFromOperationId(info.id, this.executionArn);
+        const baseName = info.name ?? info.type;
+        const spanName = `${baseName} attempt ${info.attempt}`;
+        // Find the parent Operation_Span for this operation
+        const parentSpan = this.spanMap.get(info.id);
+        const parentContext = parentSpan
+            ? api.trace.setSpan(api.context.active(), parentSpan)
+            : api.context.active();
+        // Get current trace ID for the link
+        const currentTraceId = this.invocationSpan?.spanContext().traceId ??
+            this.idGenerator.generateTraceId();
+        const attributes = {
+            "durable.execution.arn": this.executionArn,
+            "durable.operation.id": info.id,
+            "durable.operation.type": info.type,
+            "durable.operation.attempt": info.attempt,
+        };
+        if (info.name) {
+            attributes["durable.operation.name"] = info.name;
+        }
+        if (info.subType) {
+            attributes["durable.operation.subtype"] = info.subType;
+        }
+        // Create Attempt_Span as child of Operation_Span with Link to deterministic span
+        const attemptSpan = this.tracer.startSpan(spanName, {
+            attributes,
+            startTime: info.startTimestamp,
+            links: [
+                {
+                    context: {
+                        traceId: currentTraceId,
+                        spanId: deterministicSpanId,
+                        traceFlags: 1,
+                    },
+                },
+            ],
+        }, parentContext);
+        this.attemptSpan = attemptSpan;
+    }
+    wrapOperationAttemptFn(_info, fn) {
+        if (!this.attemptSpan) {
+            return fn();
+        }
+        return api.context.with(api.trace.setSpan(api.context.active(), this.attemptSpan), fn);
+    }
+    async onOperationAttemptEnd(info) {
+        if (this.attemptSpan) {
+            this.attemptSpan.setAttribute("durable.attempt.outcome", info.outcome);
+            if (info.error) {
+                this.attemptSpan.setStatus({
+                    code: api.SpanStatusCode.ERROR,
+                    message: info.error.message,
+                });
+                this.attemptSpan.recordException(info.error);
+            }
+            this.attemptSpan.end(info.endTimestamp);
+            this.attemptSpan = undefined;
+        }
+    }
+    async onOperationChange(_info) {
+        // No-op for this plugin
+    }
+    enrichLogContext() {
+        const span = api.trace.getSpan(api.context.active());
+        if (!span) {
+            return undefined;
+        }
+        const spanContext = span.spanContext();
+        return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            otelTraceSampled: (spanContext.traceFlags & 1) !== 0,
+        };
+    }
+}
+
+exports.DeterministicIdGenerator = DeterministicIdGenerator;
+exports.OtelPlugin = OtelPlugin;
+exports.deriveSpanIdFromOperationId = deriveSpanIdFromOperationId;
+exports.deriveTraceIdFromArn = deriveTraceIdFromArn;
+exports.deriveTraceIdFromXRayRoot = deriveTraceIdFromXRayRoot;
+exports.w3cClientContextExtractor = w3cClientContextExtractor;
+exports.xRayContextExtractor = xRayContextExtractor;
+//# sourceMappingURL=index.js.map

package/dist-cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/deterministic-id-generator.ts","../src/context-extractors.ts","../src/plugin.ts"],"names":["createHash","trace","registerInstrumentations","AwsInstrumentation","context","SpanStatusCode"],"mappings":"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"}

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

@@ -0,0 +1,43 @@
+import type { InvocationInfo } from "@aws/durable-execution-sdk-js";
+/**
+ * Result type returned by context extractors.
+ */
+export type ContextExtractorResult = {
+    traceId: string;
+    parentSpanId?: string;
+    traceFlags?: number;
+} | undefined;
+/**
+ * A function that extracts upstream trace context from the invocation environment.
+ */
+export type ContextExtractor = (info: InvocationInfo) => ContextExtractorResult;
+/**
+ * Reads the X-Ray trace header from the `_X_AMZN_TRACE_ID` environment variable.
+ *
+ * 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)
+ *
+ * Returns undefined when _X_AMZN_TRACE_ID is missing or malformed.
+ */
+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;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IACE,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACD,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,sBAAsB,CAAC;AAEhF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,GACpB,sBAAsB,CAuCxB;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,cAAc,GACnB,sBAAsB,CASxB"}

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

@@ -0,0 +1,70 @@
+import type { IdGenerator } from "@opentelemetry/sdk-trace-node";
+/**
+ * A custom OpenTelemetry IdGenerator that produces deterministic trace and span IDs
+ * derived from execution metadata (X-Ray headers, execution ARNs, operation IDs)
+ * rather than random values.
+ *
+ * This ensures that spans from different Lambda invocations of the same durable
+ * execution are stitched into a single coherent trace.
+ */
+export declare class DeterministicIdGenerator implements IdGenerator {
+    private traceId;
+    private nextSpanId;
+    /**
+     * Set the trace ID for all subsequent generateTraceId() calls.
+     * This is persistent until setTraceId is called again.
+     */
+    setTraceId(traceId: string): void;
+    /**
+     * Set the span ID to return on the next single generateSpanId() call.
+     * This is a one-shot override: it is consumed on the next call and then
+     * reverts to default behavior.
+     */
+    setNextSpanId(spanId: string): void;
+    /**
+     * Generate a 32-char lowercase hex trace ID.
+     *
+     * If setTraceId has been called, returns that value persistently.
+     * Otherwise returns a random 32-char hex string as fallback.
+     */
+    generateTraceId(): string;
+    /**
+     * Generate a 16-char lowercase hex span ID.
+     *
+     * If setNextSpanId has been called, returns that value once (one-shot)
+     * and then clears it. Otherwise returns a random 16-char hex string.
+     */
+    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 by hashing it
+ * with SHA-256 and truncating to the first 32 lowercase hex characters.
+ *
+ * @param executionArn - The execution ARN string
+ * @returns A 32-char lowercase hex string
+ */
+export declare function deriveTraceIdFromArn(executionArn: string): 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;
+//# sourceMappingURL=deterministic-id-generator.d.ts.map