agentfootprint 2.8.2 → 2.9.0

package/dist/adapters/observability/otel.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * otelObservability — OpenTelemetry distributed-tracing adapter.
+ *
+ * Ships every agentfootprint event as OpenTelemetry spans + log
+ * records via a consumer-supplied OTel API. Same hierarchical
+ * mapping as the X-Ray adapter, but the destination is whichever
+ * OTel-compat backend the consumer's SDK exports to:
+ *
+ *   - **Honeycomb** (OTLP/HTTP)
+ *   - **Grafana Cloud / Tempo / Mimir** (OTLP)
+ *   - **AWS Distro for OTel** → AWS X-Ray (alternative to xrayObservability)
+ *   - **Datadog APM** (OTLP endpoint)
+ *   - **Splunk Observability Cloud** (OTLP)
+ *   - **New Relic** (OTLP endpoint)
+ *   - **Lightstep / ServiceNow Cloud Observability** (OTLP)
+ *   - any custom OTel collector / processor pipeline
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@opentelemetry/api` (OPTIONAL — installed only when
+ *           this adapter is used. The consumer ALSO installs the
+ *           OTel SDK + exporter of their choice — that's the BYO
+ *           contract that makes this adapter backend-agnostic.).
+ *
+ * **Why BYO SDK:** OTel's SDK is heavyweight and exporter-specific
+ * (each backend has its own exporter package). Forcing a particular
+ * exporter would defeat the "OTel is portable" guarantee. Consumers
+ * configure the SDK + exporter once at app startup; we just speak
+ * the typed OTel API.
+ *
+ * Mapping:
+ *
+ *   agent.turn_start          ↦  start root span (one trace per turn)
+ *   agent.turn_end            ↦  end root span
+ *   agent.iteration_start     ↦  start child span under root
+ *   agent.iteration_end       ↦  end iteration span
+ *   stream.llm_start          ↦  start child span (model call)
+ *   stream.llm_end            ↦  end llm span
+ *   stream.tool_start         ↦  start child span (tool call)
+ *   stream.tool_end           ↦  end tool span (with `error: true` if errored)
+ *   cost.tick                 ↦  setAttribute on topmost active span
+ *
+ * @example Basic — Honeycomb via OTLP
+ * ```ts
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+ * import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+ * import { trace } from '@opentelemetry/api';
+ * import { otelObservability } from 'agentfootprint/observability-providers';
+ *
+ * // Set up OTel ONCE at app startup.
+ * const provider = new NodeTracerProvider();
+ * provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter({
+ *   url: 'https://api.honeycomb.io/v1/traces',
+ *   headers: { 'x-honeycomb-team': process.env.HONEYCOMB_KEY },
+ * })));
+ * provider.register();
+ *
+ * agent.enable.observability({
+ *   strategy: otelObservability({
+ *     serviceName: 'my-agent',
+ *     // tracer optional — defaults to trace.getTracer('agentfootprint').
+ *   }),
+ * });
+ * ```
+ *
+ * @example Test injection
+ * ```ts
+ * otelObservability({
+ *   serviceName: 'test',
+ *   tracer: mockTracer, // anything matching the OTel Tracer interface
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.otelObservability = void 0;
+const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+// ─── Strategy factory ────────────────────────────────────────────────
+function otelObservability(opts) {
+    if (!opts.serviceName) {
+        throw new TypeError(`[otelObservability] \`serviceName\` is required. ` +
+            `Pass an identifier visible in your OTel backend's service map, e.g. 'my-agent-prod'.`);
+    }
+    const sampleRate = opts.sampleRate ?? 1;
+    // Lazy-resolve tracer if not injected. Defer the API import until
+    // first event so consumers who don't actually fire events (no agent
+    // run yet) don't even hit the OTel API surface.
+    let tracer = opts.tracer;
+    let otelApi;
+    function ensureTracer() {
+        if (tracer)
+            return tracer;
+        if (!otelApi) {
+            try {
+                otelApi = (0, lazyRequire_js_1.lazyRequire)('@opentelemetry/api');
+            }
+            catch {
+                throw new Error('otelObservability requires the `@opentelemetry/api` peer dependency.\n' +
+                    '  Install:  npm install @opentelemetry/api\n' +
+                    '  Plus an OTel SDK + exporter for your backend (e.g.,\n' +
+                    '  `@opentelemetry/sdk-trace-node` + `@opentelemetry/exporter-trace-otlp-http`).\n' +
+                    '  Or pass `tracer` for test injection.');
+            }
+        }
+        if (!otelApi.trace?.getTracer) {
+            throw new Error('otelObservability: `@opentelemetry/api` is installed but `trace.getTracer` not found. Update the package.');
+        }
+        tracer = otelApi.trace.getTracer('agentfootprint');
+        return tracer;
+    }
+    // Per-turn state — same pattern as xrayObservability. Events for
+    // multiple in-flight turns interleave correctly because we key by
+    // `runId` from the event payload.
+    const activeTurns = new Map();
+    let stopped = false;
+    let onErrorHook;
+    function pushSpan(turnState, name, attrs) {
+        // OTel parent-context wiring: we capture the parent in a context
+        // and start the new span under it. (For BYO SDK setups, the
+        // `trace.setSpan` + `context.with` pattern is canonical. For
+        // the test-injected tracer path, we just pass the parent as
+        // implicit context.)
+        const parent = turnState.stack[turnState.stack.length - 1]?.span;
+        let ctx;
+        if (parent && otelApi?.trace?.setSpan && otelApi?.context?.active) {
+            ctx = otelApi.trace.setSpan(otelApi.context.active(), parent);
+        }
+        const span = ensureTracer().startSpan(name, attrs ? { attributes: attrs } : undefined, ctx);
+        turnState.stack.push({ name, span });
+        return span;
+    }
+    function popSpan(turnState, expectedName) {
+        let idx = turnState.stack.length - 1;
+        if (expectedName) {
+            while (idx >= 0 && turnState.stack[idx].name !== expectedName)
+                idx--;
+        }
+        if (idx < 0)
+            return undefined;
+        return turnState.stack.splice(idx, 1)[0].span;
+    }
+    function endSpan(span, opts) {
+        if (opts?.error) {
+            const code = otelApi?.SpanStatusCode?.ERROR ?? 2;
+            try {
+                span.setStatus({ code });
+            }
+            catch {
+                /* mock tracers may not implement setStatus — ignore */
+            }
+        }
+        span.end();
+    }
+    // ─── Event-to-span dispatch ────────────────────────────────────────
+    function handleEvent(event) {
+        if (stopped)
+            return;
+        const runId = event.payload?.runId;
+        if (!runId)
+            return; // Events without a turn anchor — skip.
+        switch (event.type) {
+            case 'agentfootprint.agent.turn_start': {
+                const sampled = sampleRate >= 1 || Math.random() < sampleRate;
+                const turnState = { stack: [], sampled };
+                activeTurns.set(runId, turnState);
+                if (sampled)
+                    pushSpan(turnState, opts.serviceName, { 'service.name': opts.serviceName });
+                break;
+            }
+            case 'agentfootprint.agent.turn_end': {
+                const t = activeTurns.get(runId);
+                if (!t)
+                    break;
+                // Defensive: end everything still on the stack.
+                while (t.stack.length > 0) {
+                    const span = popSpan(t);
+                    if (span)
+                        endSpan(span);
+                }
+                activeTurns.delete(runId);
+                break;
+            }
+            case 'agentfootprint.agent.iteration_start': {
+                const t = activeTurns.get(runId);
+                if (t?.sampled) {
+                    const iteration = event.payload.iteration;
+                    pushSpan(t, `iteration:${iteration ?? '?'}`, {
+                        ...(typeof iteration === 'number' && { 'iteration.number': iteration }),
+                    });
+                }
+                break;
+            }
+            case 'agentfootprint.agent.iteration_end': {
+                const t = activeTurns.get(runId);
+                if (t?.sampled) {
+                    const span = popSpan(t);
+                    if (span)
+                        endSpan(span);
+                }
+                break;
+            }
+            case 'agentfootprint.stream.llm_start': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                const model = event.payload.model;
+                pushSpan(t, 'llm', model ? { 'gen_ai.request.model': model } : undefined);
+                break;
+            }
+            case 'agentfootprint.stream.llm_end': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                const span = popSpan(t, 'llm');
+                if (span)
+                    endSpan(span);
+                break;
+            }
+            case 'agentfootprint.stream.tool_start': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                const toolName = event.payload.toolName ?? 'tool';
+                pushSpan(t, `tool:${toolName}`, { 'tool.name': toolName });
+                break;
+            }
+            case 'agentfootprint.stream.tool_end': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                const toolName = event.payload.toolName;
+                const errored = event.payload.error !== undefined;
+                const span = popSpan(t, toolName ? `tool:${toolName}` : undefined);
+                if (span)
+                    endSpan(span, { error: errored });
+                break;
+            }
+            // Other events — annotate the topmost active span.
+            default: {
+                const t = activeTurns.get(runId);
+                const top = t?.stack[t.stack.length - 1]?.span;
+                if (!t?.sampled || !top)
+                    break;
+                // Cost ticks are particularly valuable as attributes.
+                if (event.type === 'agentfootprint.cost.tick') {
+                    const p = event.payload;
+                    if (typeof p.cumulativeCostUsd === 'number') {
+                        try {
+                            top.setAttribute('cost.cumulative_usd', p.cumulativeCostUsd);
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }
+                }
+                break;
+            }
+        }
+    }
+    return {
+        name: 'otel',
+        capabilities: { events: true, traces: true },
+        exportEvent: handleEvent,
+        flush() {
+            // OTel SDKs handle their own flushing (the consumer-configured
+            // SpanProcessor's `forceFlush()`). We don't cross that boundary
+            // here — calling `provider.forceFlush()` is the consumer's
+            // responsibility on shutdown. Documented in the README.
+        },
+        stop() {
+            stopped = true;
+            // Defensive: end any spans the agent loop didn't close.
+            for (const [, t] of activeTurns) {
+                while (t.stack.length > 0) {
+                    const span = popSpan(t);
+                    if (span)
+                        endSpan(span);
+                }
+            }
+            activeTurns.clear();
+        },
+        _onError(err, event) {
+            onErrorHook =
+                onErrorHook ??
+                    ((e) => {
+                        // eslint-disable-next-line no-console
+                        console.error(`[otelObservability] error:`, e.message);
+                    });
+            onErrorHook(err, event);
+        },
+    };
+}
+exports.otelObservability = otelObservability;
+//# sourceMappingURL=otel.js.map

package/dist/adapters/observability/otel.js.map

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

package/dist/adapters/observability/xray.js

@@ -0,0 +1,370 @@
+"use strict";
+/**
+ * xrayObservability — AWS X-Ray distributed-tracing adapter.
+ *
+ * Maps agentfootprint's event taxonomy onto AWS X-Ray segment trees:
+ *
+ *     agent.turn_start          ↦  root segment (one trace per turn)
+ *     agent.turn_end            ↦  close root segment + flush
+ *     agent.iteration_start     ↦  push subsegment under root
+ *     agent.iteration_end       ↦  close iteration subsegment
+ *     stream.llm_start          ↦  push leaf subsegment (model call)
+ *     stream.llm_end            ↦  close llm subsegment
+ *     stream.tool_start         ↦  push leaf subsegment (tool call)
+ *     stream.tool_end           ↦  close tool subsegment
+ *
+ * The result in the X-Ray Trace Map: a hierarchical timeline of every
+ * agent run — turn → iteration → llm-call/tool-call — queryable in
+ * X-Ray Insights, joinable with the rest of your AWS distributed
+ * trace via `AWSTraceHeader` propagation (consumer's responsibility
+ * to wire upstream/downstream IDs).
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@aws-sdk/client-xray` (OPTIONAL — installed only when
+ *           this adapter is used).
+ *
+ * Sampling:
+ *   By default every turn produces one trace. Pass `sampleRate: 0.1`
+ *   to sample 10% of turns — sampling decisions are made at
+ *   `turn_start` and persist for the whole turn (so partial traces
+ *   never reach X-Ray).
+ *
+ * @example
+ * ```ts
+ * import { xrayObservability } from 'agentfootprint/observability-providers';
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ *
+ * agent.enable.observability({
+ *   strategy: xrayObservability({
+ *     region: 'us-east-1',
+ *     serviceName: 'my-agent',
+ *     sampleRate: 0.1,                    // 10% sampling
+ *   }),
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ *
+ * @example Test injection
+ * ```ts
+ * xrayObservability({
+ *   serviceName: 'test',
+ *   _client: {
+ *     putTraceSegments: async (input) => { capturedDocs.push(input); },
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.xrayObservability = void 0;
+const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+// ─── Strategy factory ────────────────────────────────────────────────
+function xrayObservability(opts) {
+    if (!opts.serviceName) {
+        throw new TypeError(`[xrayObservability] \`serviceName\` is required. ` +
+            `Pass an identifier visible in your X-Ray service map, e.g. 'my-agent-prod'.`);
+    }
+    const sampleRate = opts.sampleRate ?? 1;
+    const maxBatchSegments = opts.maxBatchSegments ?? 25;
+    const flushIntervalMs = opts.flushIntervalMs ?? 1000;
+    // Per-turn state. agentfootprint events arrive interleaved across
+    // multiple in-flight turns; we key the active stack by `runId`
+    // (every event payload carries it after enrichment).
+    const activeTurns = new Map();
+    // Outbound segment buffer (flat list of closed segments ready for
+    // PutTraceSegments). Drained by flush() / size-trigger / time-trigger.
+    const outbox = [];
+    let lastFlushPromise = Promise.resolve();
+    let timer;
+    let stopped = false;
+    let onErrorHook;
+    // Lazy SDK client.
+    let client = opts._client;
+    function ensureClient() {
+        if (client)
+            return client;
+        client = createXRayClient(opts.region);
+        return client;
+    }
+    function scheduleTimedFlush() {
+        if (timer || flushIntervalMs <= 0 || stopped)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void doFlush();
+        }, flushIntervalMs);
+    }
+    async function doFlush() {
+        if (outbox.length === 0 || stopped)
+            return;
+        const batch = outbox.splice(0, maxBatchSegments);
+        try {
+            await ensureClient().putTraceSegments({
+                TraceSegmentDocuments: batch.map((s) => JSON.stringify(s)),
+            });
+        }
+        catch (err) {
+            onErrorHook?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        // If outbox grew during the put (size > maxBatchSegments emits
+        // arrived), chain another flush.
+        if (outbox.length > 0 && !stopped) {
+            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+        }
+    }
+    function pushSegment(turnState, name) {
+        const parent = turnState.stack[turnState.stack.length - 1];
+        const seg = {
+            name,
+            id: hexId(16),
+            trace_id: turnState.traceId,
+            ...(parent && { parent_id: parent.id }),
+            start_time: nowSeconds(),
+            in_progress: true,
+        };
+        turnState.stack.push(seg);
+        return seg;
+    }
+    function popSegment(turnState, expectedName) {
+        // Defensive: pop the topmost segment whose name matches (if
+        // provided). Out-of-order events would otherwise leave dangling
+        // segments. If no match, pop the topmost.
+        let idx = turnState.stack.length - 1;
+        if (expectedName) {
+            while (idx >= 0 && turnState.stack[idx].name !== expectedName)
+                idx--;
+        }
+        if (idx < 0)
+            return undefined;
+        const seg = turnState.stack.splice(idx, 1)[0];
+        seg.end_time = nowSeconds();
+        delete seg.in_progress;
+        return seg;
+    }
+    function closeSegment(turnState, expectedName, extra) {
+        const seg = popSegment(turnState, expectedName);
+        if (!seg)
+            return;
+        if (extra?.error)
+            seg.error = true;
+        if (extra?.annotations)
+            seg.annotations = { ...seg.annotations, ...extra.annotations };
+        if (extra?.metadata)
+            seg.metadata = { default: { ...(seg.metadata?.default ?? {}), ...extra.metadata } };
+        if (turnState.sampled) {
+            turnState.closed.push(seg);
+            // Once the root closes, the whole turn graduates to outbox.
+            if (turnState.stack.length === 0) {
+                outbox.push(...turnState.closed);
+                if (outbox.length >= maxBatchSegments) {
+                    lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+                }
+                else {
+                    scheduleTimedFlush();
+                }
+            }
+        }
+    }
+    // ─── Event-to-segment dispatch ─────────────────────────────────────
+    function handleEvent(event) {
+        if (stopped)
+            return;
+        const runId = event.payload?.runId;
+        if (!runId)
+            return; // Events without a turn anchor — skip.
+        switch (event.type) {
+            case 'agentfootprint.agent.turn_start': {
+                const sampled = sampleRate >= 1 || Math.random() < sampleRate;
+                const turnState = {
+                    traceId: makeTraceId(),
+                    stack: [],
+                    closed: [],
+                    sampled,
+                };
+                activeTurns.set(runId, turnState);
+                if (sampled)
+                    pushSegment(turnState, opts.serviceName);
+                break;
+            }
+            case 'agentfootprint.agent.turn_end': {
+                const t = activeTurns.get(runId);
+                if (!t)
+                    break;
+                // Close everything still on the stack — defensive against
+                // missing `_end` events (e.g., pause/resume mid-turn).
+                while (t.stack.length > 0)
+                    closeSegment(t, undefined);
+                activeTurns.delete(runId);
+                break;
+            }
+            case 'agentfootprint.agent.iteration_start': {
+                const t = activeTurns.get(runId);
+                if (t?.sampled)
+                    pushSegment(t, `iteration:${event.payload.iteration ?? '?'}`);
+                break;
+            }
+            case 'agentfootprint.agent.iteration_end': {
+                const t = activeTurns.get(runId);
+                if (t?.sampled)
+                    closeSegment(t, undefined);
+                break;
+            }
+            case 'agentfootprint.stream.llm_start': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                const seg = pushSegment(t, 'llm');
+                const model = event.payload.model;
+                if (model)
+                    seg.annotations = { model };
+                break;
+            }
+            case 'agentfootprint.stream.llm_end': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                closeSegment(t, 'llm', {
+                    metadata: { event: event.payload },
+                });
+                break;
+            }
+            case 'agentfootprint.stream.tool_start': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                const toolName = event.payload.toolName ?? 'tool';
+                const seg = pushSegment(t, `tool:${toolName}`);
+                seg.annotations = { toolName };
+                break;
+            }
+            case 'agentfootprint.stream.tool_end': {
+                const t = activeTurns.get(runId);
+                if (!t?.sampled)
+                    break;
+                const toolName = event.payload.toolName;
+                closeSegment(t, toolName ? `tool:${toolName}` : undefined, {
+                    error: event.payload.error !== undefined,
+                });
+                break;
+            }
+            // Other events become annotations on the topmost active segment
+            // (cheaper than spawning a subsegment per event).
+            default: {
+                const t = activeTurns.get(runId);
+                const top = t?.stack[t.stack.length - 1];
+                if (!t?.sampled || !top)
+                    break;
+                // Annotate cost ticks specially so they're queryable in
+                // X-Ray Insights.
+                if (event.type === 'agentfootprint.cost.tick') {
+                    const p = event.payload;
+                    if (typeof p.cumulativeCostUsd === 'number') {
+                        top.annotations = { ...top.annotations, cumulativeCostUsd: p.cumulativeCostUsd };
+                    }
+                }
+                break;
+            }
+        }
+    }
+    return {
+        name: 'xray',
+        capabilities: { events: true, traces: true },
+        exportEvent: handleEvent,
+        async flush() {
+            // Force-close any in-flight turn segments so partial traces
+            // make it into X-Ray on shutdown.
+            for (const [, t] of activeTurns) {
+                if (!t.sampled)
+                    continue;
+                while (t.stack.length > 0)
+                    closeSegment(t, undefined);
+            }
+            while (outbox.length > 0) {
+                const before = lastFlushPromise;
+                await before;
+                if (outbox.length > 0) {
+                    lastFlushPromise = doFlush();
+                }
+                if (lastFlushPromise === before && outbox.length === 0)
+                    break;
+            }
+        },
+        stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+        _onError(err, event) {
+            onErrorHook =
+                onErrorHook ??
+                    ((e) => {
+                        // eslint-disable-next-line no-console
+                        console.error(`[xrayObservability] flush failed:`, e.message);
+                    });
+            onErrorHook(err, event);
+        },
+    };
+}
+exports.xrayObservability = xrayObservability;
+// ─── ID + time helpers ───────────────────────────────────────────────
+/**
+ * Generate an X-Ray trace ID. Format:
+ *   `1-{8-hex-of-unix-timestamp}-{24-hex-random}`
+ * (Note X-Ray's docs say "12 hex" for the random part; the actual
+ * spec is 24 hex / 96-bit. AWS examples use 24.)
+ */
+function makeTraceId() {
+    const seconds = Math.floor(Date.now() / 1000);
+    return `1-${seconds.toString(16).padStart(8, '0')}-${hexId(24)}`;
+}
+/** Generate a hex string of `len` chars, cryptographically-strong
+ *  where available, falling back to Math.random for environments
+ *  without `crypto.getRandomValues` (older runtimes). */
+function hexId(len) {
+    const bytes = Math.ceil(len / 2);
+    // Try the Web Crypto / Node Crypto API first.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.getRandomValues) {
+        const buf = new Uint8Array(bytes);
+        cryptoApi.getRandomValues(buf);
+        return Array.from(buf, (b) => b.toString(16).padStart(2, '0'))
+            .join('')
+            .slice(0, len);
+    }
+    // Fallback (deterministic-quality, NOT for security-critical IDs —
+    // X-Ray IDs aren't security boundaries, just trace correlation).
+    let s = '';
+    while (s.length < len)
+        s += Math.random().toString(16).slice(2);
+    return s.slice(0, len);
+}
+/** X-Ray timestamps are unix seconds with fractional precision. */
+function nowSeconds() {
+    return Date.now() / 1000;
+}
+// ─── SDK construction (lazy) ─────────────────────────────────────────
+function createXRayClient(region) {
+    let mod;
+    try {
+        mod = (0, lazyRequire_js_1.lazyRequire)('@aws-sdk/client-xray');
+    }
+    catch {
+        throw new Error('xrayObservability requires the `@aws-sdk/client-xray` peer dependency.\n' +
+            '  Install:  npm install @aws-sdk/client-xray\n' +
+            '  Or pass `_client` for test injection.');
+    }
+    if (!mod.XRayClient || !mod.PutTraceSegmentsCommand) {
+        throw new Error('xrayObservability: `@aws-sdk/client-xray` is installed but `XRayClient` / ' +
+            '`PutTraceSegmentsCommand` was not found. Update the SDK.');
+    }
+    const sdkClient = new mod.XRayClient({ ...(region && { region }) });
+    return {
+        async putTraceSegments(input) {
+            const cmd = new mod.PutTraceSegmentsCommand(input);
+            await sdkClient.send(cmd);
+        },
+    };
+}
+//# sourceMappingURL=xray.js.map