@illuma-ai/observability-node 0.1.0 → 0.2.1

package/dist/otel.js

@@ -0,0 +1,405 @@
+/**
+ * OpenTelemetry span processor that converts OTel spans to Illuma Observe traces.
+ * Drop-in replacement for @langfuse/otel's LangfuseSpanProcessor.
+ *
+ * Supports both OpenTelemetry Semantic Conventions for GenAI (`gen_ai.*`)
+ * and Vercel AI SDK conventions (`ai.*`).
+ *
+ * @example
+ * ```ts
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * import { IllumaSpanProcessor } from '@illuma-ai/observability-node/otel';
+ *
+ * const provider = new NodeTracerProvider();
+ * provider.addSpanProcessor(new IllumaSpanProcessor({
+ *   // Reads from ILLUMA_* / LANGFUSE_* env vars if omitted
+ * }));
+ * provider.register();
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { Observability } from './client.js';
+import { ObservationLevel } from '@illuma-ai/observability-core';
+/**
+ * OpenTelemetry SpanProcessor that converts OTel spans into Illuma Observe
+ * traces and observations (generations / spans).
+ *
+ * Implements the four-method SpanProcessor contract:
+ *   - `onStart(span)` — no-op; we process completed spans only
+ *   - `onEnd(span)`    — converts the span to Illuma trace / generation / span
+ *   - `shutdown()`     — flushes and tears down the underlying Observability client
+ *   - `forceFlush()`   — flushes all buffered events immediately
+ *
+ * Attribute mapping (GenAI Semantic Conventions + Vercel AI SDK):
+ *   gen_ai.system                     -> provider
+ *   gen_ai.request.model / response.model -> model
+ *   gen_ai.usage.input_tokens / ai.usage.promptTokens -> usage.input
+ *   gen_ai.usage.output_tokens / ai.usage.completionTokens -> usage.output
+ *   gen_ai.prompt / ai.prompt.*       -> input
+ *   ai.response.text                  -> output
+ *   exception span events             -> errorInfo
+ */
+export class IllumaSpanProcessor {
+    observability;
+    /**
+     * Maps OTel traceId -> IllumaTraceClient so child spans within the same
+     * trace reuse the same Illuma trace.
+     */
+    traceMap = new Map();
+    /**
+     * Maps OTel spanId -> Illuma observationId so child spans can reference
+     * their parent observation.
+     */
+    spanIdMap = new Map();
+    constructor(options = {}) {
+        this.observability = new Observability(options);
+    }
+    // -------------------------------------------------------------------------
+    // SpanProcessor interface
+    // -------------------------------------------------------------------------
+    /**
+     * Called when a span is started.
+     * No-op — we only process spans once they are complete (in `onEnd`).
+     *
+     * @param _span - The started span (unused).
+     */
+    onStart(_span) {
+        // Intentional no-op
+    }
+    /**
+     * Called when a span ends. Converts the OTel span into Illuma Observe
+     * trace / generation / span events.
+     *
+     * @param span - The completed OTel span.
+     */
+    onEnd(span) {
+        const { traceId, spanId } = span.spanContext();
+        const parentSpanId = span.parentSpanId;
+        const startTime = hrtimeToISO(span.startTime);
+        const endTime = hrtimeToISO(span.endTime);
+        const input = getSpanInput(span);
+        const output = getSpanOutput(span);
+        const metadata = getSpanMetadata(span);
+        const errorInfo = getErrorInfo(span);
+        const isLLMSpan = hasGenAIAttributes(span);
+        // 1. Ensure a trace exists for this traceId
+        let trace = this.traceMap.get(traceId);
+        if (!trace) {
+            const traceName = asString(span.attributes['ai.telemetry.metadata.traceName']) ??
+                span.name;
+            trace = this.observability.trace({
+                name: traceName,
+                metadata: {
+                    ...metadata,
+                    'otel.traceId': traceId,
+                },
+                tags: getTraceTags(span),
+                ...(span.attributes['ai.telemetry.metadata.threadId'] != null && {
+                    threadId: String(span.attributes['ai.telemetry.metadata.threadId']),
+                }),
+            });
+            this.traceMap.set(traceId, trace);
+        }
+        // 2. Resolve parent observation ID (if this span has a parent within our map)
+        const parentObservationId = parentSpanId
+            ? this.spanIdMap.get(parentSpanId)
+            : undefined;
+        // 3. Create a generation (LLM call) or a generic span
+        if (isLLMSpan) {
+            const model = getModel(span);
+            const provider = getProvider(span);
+            const usage = getUsage(span);
+            const gen = trace.generation({
+                name: span.name,
+                startTime,
+                endTime,
+                model,
+                provider,
+                input,
+                output,
+                usage,
+                metadata: {
+                    ...metadata,
+                    'otel.spanId': spanId,
+                },
+                parentObservationId,
+                ...(errorInfo && { level: ObservationLevel.ERROR, statusMessage: errorInfo.message }),
+                ...(errorInfo && { errorInfo }),
+            });
+            this.spanIdMap.set(spanId, gen.id);
+        }
+        else {
+            const s = trace.span({
+                name: span.name,
+                startTime,
+                endTime,
+                input,
+                output,
+                metadata: {
+                    ...metadata,
+                    'otel.spanId': spanId,
+                },
+                parentObservationId,
+                ...(errorInfo && { level: ObservationLevel.ERROR, statusMessage: errorInfo.message }),
+                ...(errorInfo && { errorInfo }),
+            });
+            this.spanIdMap.set(spanId, s.id);
+        }
+    }
+    /**
+     * Flush all buffered events and shut down the underlying Observability client.
+     * After this call, no further spans should be processed.
+     */
+    async shutdown() {
+        await this.observability.shutdown();
+        this.traceMap.clear();
+        this.spanIdMap.clear();
+    }
+    /**
+     * Force-flush all buffered events without shutting down.
+     */
+    async forceFlush() {
+        await this.observability.flush();
+    }
+}
+// ---------------------------------------------------------------------------
+// Attribute extraction helpers
+// ---------------------------------------------------------------------------
+/** OTel SpanStatusCode.ERROR = 2 */
+const SPAN_STATUS_ERROR = 2;
+/**
+ * Convert OTel hrtime [seconds, nanoseconds] to an ISO-8601 timestamp string.
+ *
+ * @param hrtime - Tuple of [seconds, nanoseconds] from OTel span.
+ * @returns ISO-8601 formatted timestamp with millisecond precision.
+ */
+function hrtimeToISO(hrtime) {
+    const ms = hrtime[0] * 1e3 + hrtime[1] / 1e6;
+    return new Date(ms).toISOString();
+}
+/**
+ * Check whether a span has gen_ai.* attributes, indicating it wraps an LLM call.
+ */
+function hasGenAIAttributes(span) {
+    return Object.keys(span.attributes).some((key) => key.startsWith('gen_ai.') || key === 'ai.model.id');
+}
+/**
+ * Extract the model identifier from OTel attributes.
+ * Checks multiple conventions in priority order.
+ */
+function getModel(span) {
+    const attrs = span.attributes;
+    return (asString(attrs['gen_ai.response.model']) ??
+        asString(attrs['gen_ai.request.model']) ??
+        asString(attrs['ai.model.id']) ??
+        undefined);
+}
+/**
+ * Extract the LLM provider from OTel attributes.
+ */
+function getProvider(span) {
+    const attrs = span.attributes;
+    return (asString(attrs['gen_ai.system']) ??
+        asString(attrs['ai.model.provider']) ??
+        undefined);
+}
+/**
+ * Extract token usage from OTel attributes.
+ * Supports both GenAI semantic conventions and Vercel AI SDK conventions.
+ *
+ * @returns Usage object with input/output/total counts, or undefined if no usage data found.
+ */
+function getUsage(span) {
+    const attrs = span.attributes;
+    const inputTokens = asNumber(attrs['gen_ai.usage.input_tokens']) ??
+        asNumber(attrs['ai.usage.promptTokens']);
+    const outputTokens = asNumber(attrs['gen_ai.usage.output_tokens']) ??
+        asNumber(attrs['ai.usage.completionTokens']);
+    if (inputTokens == null && outputTokens == null) {
+        return undefined;
+    }
+    return {
+        input: inputTokens ?? undefined,
+        output: outputTokens ?? undefined,
+        total: inputTokens != null || outputTokens != null
+            ? (inputTokens ?? 0) + (outputTokens ?? 0)
+            : undefined,
+    };
+}
+/**
+ * Extract the input payload from OTel span attributes.
+ * Checks gen_ai.prompt, ai.prompt, gen_ai.request.*, and ai.prompt.* keys.
+ *
+ * @returns Parsed input object, or undefined if no input data found.
+ */
+function getSpanInput(span) {
+    const attrs = span.attributes;
+    const input = {};
+    // Top-level prompt attributes (may be JSON-encoded strings)
+    for (const key of ['gen_ai.prompt', 'ai.prompt']) {
+        const parsed = tryParseJSON(attrs[key]);
+        if (parsed) {
+            Object.assign(input, parsed);
+        }
+    }
+    // Namespaced request attributes: gen_ai.request.* -> strip prefix
+    for (const [key, value] of Object.entries(attrs)) {
+        if (key.startsWith('gen_ai.request.')) {
+            input[key.replace('gen_ai.request.', '')] = safeParseJSON(value);
+        }
+        if (key.startsWith('ai.prompt.')) {
+            input[key.replace('ai.prompt.', '')] = safeParseJSON(value);
+        }
+    }
+    if (Object.keys(input).length > 0) {
+        return input;
+    }
+    // Tool call inputs
+    if (attrs['ai.toolCall.name'] != null) {
+        input.toolName = attrs['ai.toolCall.name'];
+    }
+    if (attrs['ai.toolCall.args'] != null) {
+        input.args = safeParseJSON(attrs['ai.toolCall.args']);
+    }
+    return Object.keys(input).length > 0 ? input : undefined;
+}
+/**
+ * Extract the output payload from OTel span attributes.
+ *
+ * @returns Parsed output object, or undefined if no output data found.
+ */
+function getSpanOutput(span) {
+    const attrs = span.attributes;
+    if (attrs['ai.response.text'] != null) {
+        return { text: attrs['ai.response.text'] };
+    }
+    if (attrs['ai.response.object'] != null) {
+        return { object: safeParseJSON(attrs['ai.response.object']) };
+    }
+    if (attrs['ai.toolCall.result'] != null) {
+        return { result: attrs['ai.toolCall.result'] };
+    }
+    if (attrs['ai.response.toolCalls'] != null) {
+        return { toolCalls: safeParseJSON(attrs['ai.response.toolCalls']) };
+    }
+    return undefined;
+}
+/**
+ * Extract metadata from OTel span attributes (model info, system, etc.).
+ */
+function getSpanMetadata(span) {
+    const attrs = span.attributes;
+    const metadata = {};
+    if (attrs['gen_ai.response.model'] != null) {
+        metadata.model = attrs['gen_ai.response.model'];
+    }
+    if (attrs['gen_ai.system'] != null) {
+        metadata.system = attrs['gen_ai.system'];
+    }
+    // Propagate any ai.telemetry.metadata.* keys
+    for (const [key, value] of Object.entries(attrs)) {
+        if (key.startsWith('ai.telemetry.metadata.') && key !== 'ai.telemetry.metadata.traceName' && key !== 'ai.telemetry.metadata.threadId') {
+            metadata[key.replace('ai.telemetry.metadata.', '')] = value;
+        }
+    }
+    return metadata;
+}
+/**
+ * Extract structured error information from an OTel span.
+ * Looks for `exception` events and falls back to span status message.
+ *
+ * @returns ErrorInfo if the span has an error status, otherwise undefined.
+ */
+function getErrorInfo(span) {
+    if (span.status.code !== SPAN_STATUS_ERROR) {
+        return undefined;
+    }
+    const exceptionEvent = span.events.find((event) => event.name === 'exception');
+    if (!exceptionEvent) {
+        return {
+            exceptionType: 'Error',
+            message: span.status.message || 'An error occurred',
+            traceback: '',
+        };
+    }
+    const eventAttrs = exceptionEvent.attributes ?? {};
+    return {
+        exceptionType: String(eventAttrs['exception.type'] ?? 'Error'),
+        message: eventAttrs['exception.message'] != null
+            ? String(eventAttrs['exception.message'])
+            : undefined,
+        traceback: String(eventAttrs['exception.stacktrace'] ?? ''),
+    };
+}
+/**
+ * Extract tags from telemetry metadata attributes.
+ */
+function getTraceTags(span) {
+    const raw = span.attributes['ai.telemetry.metadata.tags'];
+    if (raw == null)
+        return undefined;
+    if (Array.isArray(raw)) {
+        return raw.map(String);
+    }
+    if (typeof raw === 'string') {
+        const parsed = safeParseJSON(raw);
+        if (Array.isArray(parsed)) {
+            return parsed.map(String);
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// JSON / type coercion helpers
+// ---------------------------------------------------------------------------
+/**
+ * Safely cast an unknown value to string, returning null if not a string.
+ */
+function asString(value) {
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Safely cast an unknown value to number, returning null if not numeric.
+ */
+function asNumber(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string') {
+        const n = Number(value);
+        return Number.isNaN(n) ? null : n;
+    }
+    return null;
+}
+/**
+ * Parse a JSON string, returning the parsed value or the original if parsing fails.
+ */
+function safeParseJSON(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Attempt to parse a value as a JSON object. Returns the parsed object
+ * only if the result is a non-array, non-null object; otherwise undefined.
+ */
+function tryParseJSON(input) {
+    if (typeof input !== 'string')
+        return undefined;
+    try {
+        const parsed = JSON.parse(input);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Not valid JSON — ignore
+    }
+    return undefined;
+}
+//# sourceMappingURL=otel.js.map

package/dist/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAA6B,MAAM,aAAa,CAAC;AACvE,OAAO,EAAoB,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAiDnF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,mBAAmB;IACb,aAAa,CAAgB;IAE9C;;;OAGG;IACc,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE3D;;;OAGG;IACc,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEvD,YAAY,UAAsC,EAAE;QAClD,IAAI,CAAC,aAAa,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IAClD,CAAC;IAED,4EAA4E;IAC5E,0BAA0B;IAC1B,4EAA4E;IAE5E;;;;;OAKG;IACH,OAAO,CAAC,KAAe;QACrB,oBAAoB;IACtB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAsB;QAC1B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAEvC,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE1C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QAE3C,4CAA4C;QAC5C,IAAI,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,SAAS,GACb,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,iCAAiC,CAAC,CAAC;gBAC5D,IAAI,CAAC,IAAI,CAAC;YAEZ,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;gBAC/B,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE;oBACR,GAAG,QAAQ;oBACX,cAAc,EAAE,OAAO;iBACxB;gBACD,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC;gBACxB,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,gCAAgC,CAAC,IAAI,IAAI,IAAI;oBAC/D,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,gCAAgC,CAAC,CAAC;iBACpE,CAAC;aACH,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,8EAA8E;QAC9E,MAAM,mBAAmB,GAAG,YAAY;YACtC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC;YAClC,CAAC,CAAC,SAAS,CAAC;QAEd,sDAAsD;QACtD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC7B,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;YACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAE7B,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC;gBAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS;gBACT,OAAO;gBACP,KAAK;gBACL,QAAQ;gBACR,KAAK;gBACL,MAAM;gBACN,KAAK;gBACL,QAAQ,EAAE;oBACR,GAAG,QAAQ;oBACX,aAAa,EAAE,MAAM;iBACtB;gBACD,mBAAmB;gBACnB,GAAG,CAAC,SAAS,IAAI,EAAE,KAAK,EAAE,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;gBACrF,GAAG,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;aAChC,CAAC,CAAC;YAEH,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;gBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS;gBACT,OAAO;gBACP,KAAK;gBACL,MAAM;gBACN,QAAQ,EAAE;oBACR,GAAG,QAAQ;oBACX,aAAa,EAAE,MAAM;iBACtB;gBACD,mBAAmB;gBACnB,GAAG,CAAC,SAAS,IAAI,EAAE,KAAK,EAAE,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;gBACrF,GAAG,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;aAChC,CAAC,CAAC;YAEH,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;IACnC,CAAC;CACF;AAED,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E,oCAAoC;AACpC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B;;;;;GAKG;AACH,SAAS,WAAW,CAAC,MAAwB;IAC3C,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAC7C,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,IAAsB;IAChD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CACtC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,KAAK,aAAa,CAC5D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,IAAsB;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;IAC9B,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACxC,QAAQ,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QACvC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC9B,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,IAAsB;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;IAC9B,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QAChC,QAAQ,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACpC,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CACf,IAAsB;IAEtB,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;IAE9B,MAAM,WAAW,GACf,QAAQ,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC5C,QAAQ,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAE3C,MAAM,YAAY,GAChB,QAAQ,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC7C,QAAQ,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC;IAE/C,IAAI,WAAW,IAAI,IAAI,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;QAChD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,KAAK,EAAE,WAAW,IAAI,SAAS;QAC/B,MAAM,EAAE,YAAY,IAAI,SAAS;QACjC,KAAK,EACH,WAAW,IAAI,IAAI,IAAI,YAAY,IAAI,IAAI;YACzC,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC;YAC1C,CAAC,CAAC,SAAS;KAChB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,IAAsB;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;IAC9B,MAAM,KAAK,GAA4B,EAAE,CAAC;IAE1C,4DAA4D;IAC5D,KAAK,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,WAAW,CAAU,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACxC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACtC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACjC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mBAAmB;IACnB,IAAI,KAAK,CAAC,kBAAkB,CAAC,IAAI,IAAI,EAAE,CAAC;QACtC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,KAAK,CAAC,kBAAkB,CAAC,IAAI,IAAI,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAsB;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;IAE9B,IAAI,KAAK,CAAC,kBAAkB,CAAC,IAAI,IAAI,EAAE,CAAC;QACtC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,kBAAkB,CAAC,EAAE,CAAC;IAC7C,CAAC;IACD,IAAI,KAAK,CAAC,oBAAoB,CAAC,IAAI,IAAI,EAAE,CAAC;QACxC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,KAAK,CAAC,oBAAoB,CAAC,IAAI,IAAI,EAAE,CAAC;QACxC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,oBAAoB,CAAC,EAAE,CAAC;IACjD,CAAC;IACD,IAAI,KAAK,CAAC,uBAAuB,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3C,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,EAAE,CAAC;IACtE,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,IAAsB;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;IAC9B,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAE7C,IAAI,KAAK,CAAC,uBAAuB,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3C,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,CAAC,IAAI,IAAI,EAAE,CAAC;QACnC,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;IAC3C,CAAC;IAED,6CAA6C;IAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,GAAG,CAAC,UAAU,CAAC,wBAAwB,CAAC,IAAI,GAAG,KAAK,iCAAiC,IAAI,GAAG,KAAK,gCAAgC,EAAE,CAAC;YACtI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CACnB,IAAsB;IAEtB,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;QAC3C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAE/E,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO;YACL,aAAa,EAAE,OAAO;YACtB,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,mBAAmB;YACnD,SAAS,EAAE,EAAE;SACd,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,cAAc,CAAC,UAAU,IAAI,EAAE,CAAC;IACnD,OAAO;QACL,aAAa,EAAE,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,IAAI,OAAO,CAAC;QAC9D,OAAO,EAAE,UAAU,CAAC,mBAAmB,CAAC,IAAI,IAAI;YAC9C,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;YACzC,CAAC,CAAC,SAAS;QACb,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,IAAsB;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,4BAA4B,CAAC,CAAC;IAC1D,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IAElC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;GAEG;AACH,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5E,OAAO,MAAiC,CAAC;QAC3C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/track.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @track decorator for automatic function tracing.
+ *
+ * Uses `AsyncLocalStorage` from `node:async_hooks` for context propagation,
+ * enabling nested decorators to automatically create child spans under a
+ * parent trace. Supports both decorator syntax and function wrapping.
+ *
+ * Inspired by Opik's track decorator pattern.
+ *
+ * @example Function wrapping
+ * ```ts
+ * const tracedFn = track(myFunction, { name: 'my-operation' });
+ * await tracedFn(arg1, arg2);
+ * ```
+ *
+ * @example TC39 method decorator
+ * ```ts
+ * class MyService {
+ *   @track({ name: 'process' })
+ *   async process(input: string) { ... }
+ * }
+ * ```
+ *
+ * @example Nested tracing (child spans auto-linked to parent trace)
+ * ```ts
+ * const outer = track(async (x: number) => {
+ *   return await inner(x + 1);   // inner becomes a child span
+ * }, { name: 'outer' });
+ *
+ * const inner = track(async (x: number) => {
+ *   return x * 2;
+ * }, { name: 'inner' });
+ * ```
+ *
+ * @module
+ */
+import type { Observability } from './client.js';
+import type { TraceClient, SpanClient } from '@illuma-ai/observability-core';
+/** Internal context propagated via AsyncLocalStorage between nested @track calls. */
+interface TrackContext {
+    /** Root trace for this execution tree. */
+    trace: TraceClient;
+    /** The most recent span in the call stack (undefined at trace root level). */
+    currentSpan?: SpanClient;
+    /** The Observability client that owns this context. */
+    observability: Observability;
+}
+/** Options accepted by the `track` function / decorator. */
+export interface TrackOptions {
+    /** Name for the span/trace. Defaults to the wrapped function's name. */
+    name?: string;
+    /** Custom metadata attached to the span/trace. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Callback invoked with the function's return value before the span is finalized.
+     * The returned record is merged into the span/trace update.
+     *
+     * @param result - The successful return value of the tracked function.
+     * @returns Key-value pairs to merge into the span update (e.g. model, usage).
+     */
+    enrichSpan?: (result: unknown) => Record<string, unknown>;
+    /** Observability client instance. If not provided, a singleton is lazily created from env vars. */
+    client?: Observability;
+}
+/**
+ * Track a function execution as a trace or span.
+ *
+ * If called within an existing tracked context, creates a child span.
+ * Otherwise, creates a new root trace.
+ *
+ * **Usage patterns:**
+ *
+ * 1. **Function wrapper** (no options):
+ *    ```ts
+ *    const traced = track(myFn);
+ *    ```
+ *
+ * 2. **Function wrapper** (with options):
+ *    ```ts
+ *    const traced = track(myFn, { name: 'myOp' });
+ *    ```
+ *
+ * 3. **Higher-order** (returns a wrapper):
+ *    ```ts
+ *    const traced = track({ name: 'myOp' })(myFn);
+ *    ```
+ *
+ * 4. **TC39 method decorator**:
+ *    ```ts
+ *    class Svc {
+ *      @track({ name: 'myOp' })
+ *      async run() { ... }
+ *    }
+ *    ```
+ *
+ * 5. **Legacy (experimental) method decorator**:
+ *    ```ts
+ *    class Svc {
+ *      @track({ name: 'myOp' })
+ *      async run() { ... }
+ *    }
+ *    ```
+ *
+ * @param fnOrOptions  - Either the function to wrap, or a TrackOptions config object.
+ * @param optionsOrNothing - When `fnOrOptions` is a function, optional TrackOptions.
+ * @returns The wrapped function, or a decorator function.
+ */
+export declare function track<T extends (...args: any[]) => any>(fnOrOptions?: T | TrackOptions, optionsOrNothing?: TrackOptions): any;
+/**
+ * Retrieve the current tracking context from AsyncLocalStorage.
+ *
+ * Useful for manual instrumentation when you need access to the active
+ * trace or span without using the @track decorator.
+ *
+ * @returns The current TrackContext, or undefined if not inside a tracked call.
+ */
+export declare function getCurrentTrackContext(): TrackContext | undefined;
+/**
+ * Reset the cached singleton Observability client.
+ *
+ * Intended for testing — allows the next `track` call to create a fresh client
+ * from environment variables.
+ */
+export declare function resetTrackClient(): void;
+export type { TrackContext };
+//# sourceMappingURL=track.d.ts.map

package/dist/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../src/track.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAM7E,qFAAqF;AACrF,UAAU,YAAY;IACpB,0CAA0C;IAC1C,KAAK,EAAE,WAAW,CAAC;IACnB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,uDAAuD;IACvD,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1D,mGAAmG;IACnG,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AA+LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,wBAAgB,KAAK,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrD,WAAW,CAAC,EAAE,CAAC,GAAG,YAAY,EAC9B,gBAAgB,CAAC,EAAE,YAAY,GAE9B,GAAG,CAkDL;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,GAAG,SAAS,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,YAAY,EAAE,YAAY,EAAE,CAAC"}