agentfootprint 2.8.2 → 2.9.0

package/dist/esm/adapters/observability/xray.js

@@ -0,0 +1,366 @@
+/**
+ * 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); },
+ *   },
+ * });
+ * ```
+ */
+import { lazyRequire } from '../../lib/lazyRequire.js';
+// ─── Strategy factory ────────────────────────────────────────────────
+export 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);
+        },
+    };
+}
+// ─── 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 = 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

package/dist/esm/adapters/observability/xray.js.map

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

package/dist/esm/observability-providers.js

@@ -28,11 +28,18 @@
  *
  * Roadmap:
  *   - agentcoreObservability   ← v2.8.1
- *   - cloudwatchObservability  ← v2.8.2 (this release)
+ *   - cloudwatchObservability  ← v2.8.2
  *   - xrayObservability        ← v2.8.3
- *   - otelObservability        ← v2.9.x
- *   - datadogObservability     ← v2.9.x
+ *   - otelObservability        ← v2.9.0 (this release)
+ *
+ * Note: `datadogObservability` was on the v2.9 roadmap, but Datadog
+ * APM accepts OTLP — point your OTel SDK at Datadog's OTLP endpoint
+ * and `otelObservability` covers the Datadog use case. We'll ship a
+ * dedicated `dd-trace`-based adapter only if real-world feedback
+ * demands the native Datadog APM client.
  */
 export { agentcoreObservability, } from './adapters/observability/agentcore.js';
 export { cloudwatchObservability, } from './adapters/observability/cloudwatch.js';
+export { xrayObservability, } from './adapters/observability/xray.js';
+export { otelObservability, } from './adapters/observability/otel.js';
 //# sourceMappingURL=observability-providers.js.map

package/dist/esm/observability-providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,GAExB,MAAM,wCAAwC,CAAC"}
+{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,GAExB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,iBAAiB,GAGlB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,iBAAiB,GAKlB,MAAM,kCAAkC,CAAC"}

package/dist/observability-providers.js

@@ -29,15 +29,24 @@
  *
  * Roadmap:
  *   - agentcoreObservability   ← v2.8.1
- *   - cloudwatchObservability  ← v2.8.2 (this release)
+ *   - cloudwatchObservability  ← v2.8.2
  *   - xrayObservability        ← v2.8.3
- *   - otelObservability        ← v2.9.x
- *   - datadogObservability     ← v2.9.x
+ *   - otelObservability        ← v2.9.0 (this release)
+ *
+ * Note: `datadogObservability` was on the v2.9 roadmap, but Datadog
+ * APM accepts OTLP — point your OTel SDK at Datadog's OTLP endpoint
+ * and `otelObservability` covers the Datadog use case. We'll ship a
+ * dedicated `dd-trace`-based adapter only if real-world feedback
+ * demands the native Datadog APM client.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cloudwatchObservability = exports.agentcoreObservability = void 0;
+exports.otelObservability = exports.xrayObservability = exports.cloudwatchObservability = exports.agentcoreObservability = void 0;
 var agentcore_js_1 = require("./adapters/observability/agentcore.js");
 Object.defineProperty(exports, "agentcoreObservability", { enumerable: true, get: function () { return agentcore_js_1.agentcoreObservability; } });
 var cloudwatch_js_1 = require("./adapters/observability/cloudwatch.js");
 Object.defineProperty(exports, "cloudwatchObservability", { enumerable: true, get: function () { return cloudwatch_js_1.cloudwatchObservability; } });
+var xray_js_1 = require("./adapters/observability/xray.js");
+Object.defineProperty(exports, "xrayObservability", { enumerable: true, get: function () { return xray_js_1.xrayObservability; } });
+var otel_js_1 = require("./adapters/observability/otel.js");
+Object.defineProperty(exports, "otelObservability", { enumerable: true, get: function () { return otel_js_1.otelObservability; } });
 //# sourceMappingURL=observability-providers.js.map

package/dist/observability-providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../src/observability-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,sEAG+C;AAF7C,sHAAA,sBAAsB,OAAA;AAGxB,wEAGgD;AAF9C,wHAAA,uBAAuB,OAAA"}
+{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../src/observability-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;;;AAEH,sEAG+C;AAF7C,sHAAA,sBAAsB,OAAA;AAGxB,wEAGgD;AAF9C,wHAAA,uBAAuB,OAAA;AAGzB,4DAI0C;AAHxC,4GAAA,iBAAiB,OAAA;AAInB,4DAM0C;AALxC,4GAAA,iBAAiB,OAAA"}

package/dist/types/adapters/observability/otel.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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
+ * });
+ * ```
+ */
+import type { ObservabilityStrategy } from '../../strategies/types.js';
+export interface OtelObservabilityOptions {
+    /** Service name on every emitted span. Surfaces in your OTel
+     *  backend's service map. Required. */
+    readonly serviceName: string;
+    /** OTel Tracer to use. Defaults to
+     *  `trace.getTracer('agentfootprint', AGENTFOOTPRINT_VERSION)`
+     *  (where `trace` is the lazy-imported `@opentelemetry/api`). */
+    readonly tracer?: OtelTracerLike;
+    /** 0..1 — sample rate for turn-level spans. Default `1.0`.
+     *  Sampling decisions are normally an OTel SDK concern (via
+     *  `Sampler`); this option is a per-strategy override for cases
+     *  where the consumer wants agentfootprint to drop spans BEFORE
+     *  they reach the SDK (e.g., aggressive cost control). */
+    readonly sampleRate?: number;
+}
+/** Subset of `@opentelemetry/api`'s `Tracer` we depend on. */
+export interface OtelTracerLike {
+    startSpan(name: string, options?: OtelSpanOptions, context?: unknown): OtelSpanLike;
+}
+/** Subset of `@opentelemetry/api`'s `SpanOptions`. */
+export interface OtelSpanOptions {
+    attributes?: Record<string, string | number | boolean>;
+    startTime?: number;
+    kind?: number;
+}
+/** Subset of `@opentelemetry/api`'s `Span` we depend on. */
+export interface OtelSpanLike {
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(endTime?: number): void;
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+        traceFlags: number;
+    };
+}
+export declare function otelObservability(opts: OtelObservabilityOptions): ObservabilityStrategy;
+//# sourceMappingURL=otel.d.ts.map

package/dist/types/adapters/observability/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/otel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,wBAAwB;IACvC;2CACuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;qEAEiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC;;;;8DAI0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAID,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;CACrF;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACrE,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;IAC/D,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAgBD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,qBAAqB,CA0OvF"}

package/dist/types/adapters/observability/xray.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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); },
+ *   },
+ * });
+ * ```
+ */
+import type { ObservabilityStrategy } from '../../strategies/types.js';
+export interface XrayObservabilityOptions {
+    /** AWS region. Falls back to AWS_REGION / AWS_DEFAULT_REGION env. */
+    readonly region?: string;
+    /** Service name on every emitted segment. Surfaces in X-Ray's
+     *  service map. Required. */
+    readonly serviceName: string;
+    /** 0..1 — fraction of turns to sample. Default `1.0` (every turn).
+     *  Decisions are made at `turn_start` and persist for the whole
+     *  turn so partial traces never reach X-Ray. */
+    readonly sampleRate?: number;
+    /** Max segments buffered before forced flush. X-Ray's
+     *  `PutTraceSegments` API accepts up to 50 segments per call;
+     *  default 25 keeps latency tight. */
+    readonly maxBatchSegments?: number;
+    /** Forced flush window for low-traffic agents. Default 1000ms.
+     *  `0` disables time-based flush. */
+    readonly flushIntervalMs?: number;
+    /** Test injection — bypasses SDK lazy-require entirely. */
+    readonly _client?: XRayLikeClient;
+}
+export interface XRayLikeClient {
+    putTraceSegments(input: {
+        TraceSegmentDocuments: ReadonlyArray<string>;
+    }): Promise<unknown>;
+}
+export declare function xrayObservability(opts: XrayObservabilityOptions): ObservabilityStrategy;
+//# sourceMappingURL=xray.d.ts.map

package/dist/types/adapters/observability/xray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xray.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/xray.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;iCAC6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;oDAEgD;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;0CAEsC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;yCACqC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAID,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,KAAK,EAAE;QAAE,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7F;AA6BD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,qBAAqB,CAuQvF"}