@superblocksteam/telemetry 2.0.173-next.4 → 2.0.174

package/dist-esm/lint/forbidden-attributes.js

@@ -0,0 +1,210 @@
+/**
+ * ESLint Rule: No Forbidden Telemetry Attributes
+ *
+ * This rule detects usage of forbidden attributes in span/metric instrumentation.
+ * It catches common leak paths before code is merged.
+ *
+ * Usage in eslint.config.js:
+ * ```
+ * import { noForbiddenTelemetryAttributes } from '@superblocksteam/telemetry/lint';
+ *
+ * export default [
+ *   {
+ *     plugins: {
+ *       telemetry: { rules: { 'no-forbidden-attributes': noForbiddenTelemetryAttributes } }
+ *     },
+ *     rules: {
+ *       'telemetry/no-forbidden-attributes': 'error'
+ *     }
+ *   }
+ * ];
+ * ```
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- ESLint rule APIs use untyped AST nodes */
+import { TIER2_FORBIDDEN_ATTRIBUTES } from "../common/contracts/tier2-traces.js";
+import { RESOURCE_ONLY_ATTRIBUTES } from "../common/resource.js";
+/**
+ * Forbidden attribute patterns for static analysis.
+ */
+export const FORBIDDEN_ATTRIBUTE_PATTERNS = [
+    // Direct string literals
+    ...Array.from(TIER2_FORBIDDEN_ATTRIBUTES),
+    // Resource-only attributes
+    ...Array.from(RESOURCE_ONLY_ATTRIBUTES),
+];
+/**
+ * ESLint rule metadata.
+ */
+export const noForbiddenTelemetryAttributesMeta = {
+    type: "problem",
+    docs: {
+        description: "Disallow forbidden telemetry attributes in Tier 2 paths",
+        category: "Security",
+        recommended: true,
+    },
+    messages: {
+        forbiddenAttribute: "Attribute '{{name}}' is forbidden in Tier 2 telemetry. " +
+            "This data should only be in Tier 1 (local retention).",
+        resourceOnlyAttribute: "Attribute '{{name}}' should be a RESOURCE attribute, not a span attribute. " +
+            "Set it in initNodeTelemetry() config, not per-span.",
+    },
+    schema: [],
+};
+/**
+ * ESLint rule implementation.
+ *
+ * Detects patterns like:
+ * - span.setAttribute('prompt', value)
+ * - span.setAttributes({ prompt: value })
+ * - { 'prompt': value }
+ */
+export function noForbiddenTelemetryAttributesCreate(context) {
+    const forbiddenSet = new Set(FORBIDDEN_ATTRIBUTE_PATTERNS);
+    const resourceOnlySet = RESOURCE_ONLY_ATTRIBUTES;
+    function checkAttributeName(node, name) {
+        if (TIER2_FORBIDDEN_ATTRIBUTES.has(name)) {
+            context.report({
+                node,
+                messageId: "forbiddenAttribute",
+                data: { name },
+            });
+        }
+        else if (resourceOnlySet.has(name)) {
+            context.report({
+                node,
+                messageId: "resourceOnlyAttribute",
+                data: { name },
+            });
+        }
+    }
+    return {
+        // Check span.setAttribute('forbidden', value)
+        CallExpression(node) {
+            if (node.callee.type === "MemberExpression" &&
+                node.callee.property.name === "setAttribute" &&
+                node.arguments.length >= 1 &&
+                node.arguments[0].type === "Literal" &&
+                typeof node.arguments[0].value === "string") {
+                checkAttributeName(node.arguments[0], node.arguments[0].value);
+            }
+            // Check span.setAttributes({ forbidden: value })
+            if (node.callee.type === "MemberExpression" &&
+                node.callee.property.name === "setAttributes" &&
+                node.arguments.length >= 1 &&
+                node.arguments[0].type === "ObjectExpression") {
+                for (const prop of node.arguments[0].properties) {
+                    if (prop.key.type === "Literal" &&
+                        typeof prop.key.value === "string") {
+                        checkAttributeName(prop.key, prop.key.value);
+                    }
+                    else if (prop.key.type === "Identifier") {
+                        checkAttributeName(prop.key, prop.key.name);
+                    }
+                }
+            }
+        },
+        // Check object literals with forbidden keys in telemetry-related files
+        Property(node) {
+            // Only check if we're likely in a telemetry context
+            const filename = context.getFilename();
+            if (!filename.includes("telemetry") &&
+                !filename.includes("tracing") &&
+                !filename.includes("observability")) {
+                return;
+            }
+            let name = null;
+            if (node.key.type === "Literal" && typeof node.key.value === "string") {
+                name = node.key.value;
+            }
+            else if (node.key.type === "Identifier") {
+                name = node.key.name;
+            }
+            if (name && forbiddenSet.has(name)) {
+                checkAttributeName(node.key, name);
+            }
+        },
+    };
+}
+/**
+ * Complete ESLint rule export.
+ */
+export const noForbiddenTelemetryAttributes = {
+    meta: noForbiddenTelemetryAttributesMeta,
+    create: noForbiddenTelemetryAttributesCreate,
+};
+/**
+ * ESLint rule: No Direct OTEL SDK Usage
+ *
+ * Detects direct usage of NodeSDK or WebTracerProvider outside the telemetry package.
+ */
+export const noDirectOtelSdkMeta = {
+    type: "problem",
+    docs: {
+        description: "Disallow direct OpenTelemetry SDK usage outside telemetry package",
+        category: "Best Practices",
+        recommended: true,
+    },
+    messages: {
+        directSdkUsage: "Direct usage of '{{name}}' is not allowed. " +
+            "Use @superblocksteam/telemetry bootstrap functions instead.",
+    },
+    schema: [],
+};
+/**
+ * Forbidden OTEL SDK imports.
+ */
+const FORBIDDEN_SDK_IMPORTS = [
+    "NodeSDK",
+    "WebTracerProvider",
+    "NodeTracerProvider",
+    "BasicTracerProvider",
+];
+export function noDirectOtelSdkCreate(context) {
+    const filename = context.getFilename();
+    // Allow in telemetry package itself
+    if (filename.includes("packages/telemetry")) {
+        return {};
+    }
+    return {
+        ImportSpecifier(node) {
+            const importedName = node.imported.name;
+            if (FORBIDDEN_SDK_IMPORTS.includes(importedName)) {
+                context.report({
+                    node,
+                    messageId: "directSdkUsage",
+                    data: { name: importedName },
+                });
+            }
+        },
+        // Also check require() calls
+        CallExpression(node) {
+            if (node.callee.name === "require" &&
+                node.arguments.length === 1 &&
+                node.arguments[0].type === "Literal") {
+                const requirePath = node.arguments[0].value;
+                if (typeof requirePath === "string" &&
+                    (requirePath.includes("@opentelemetry/sdk-node") ||
+                        requirePath.includes("@opentelemetry/sdk-trace-node") ||
+                        requirePath.includes("@opentelemetry/sdk-trace-web"))) {
+                    context.report({
+                        node,
+                        messageId: "directSdkUsage",
+                        data: { name: requirePath },
+                    });
+                }
+            }
+        },
+    };
+}
+export const noDirectOtelSdk = {
+    meta: noDirectOtelSdkMeta,
+    create: noDirectOtelSdkCreate,
+};
+/**
+ * All telemetry ESLint rules.
+ */
+export const telemetryRules = {
+    "no-forbidden-attributes": noForbiddenTelemetryAttributes,
+    "no-direct-otel-sdk": noDirectOtelSdk,
+};
+//# sourceMappingURL=forbidden-attributes.js.map

package/dist-esm/lint/forbidden-attributes.js.map

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

package/dist-esm/lint/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Telemetry ESLint Rules
+ *
+ * Lint rules for enforcing telemetry best practices:
+ * - no-forbidden-attributes: Prevents Tier 1 data in Tier 2 paths
+ * - no-direct-otel-sdk: Enforces use of telemetry bootstrap
+ */
+export { noForbiddenTelemetryAttributes, noDirectOtelSdk, telemetryRules, FORBIDDEN_ATTRIBUTE_PATTERNS, } from "./forbidden-attributes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist-esm/lint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lint/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,8BAA8B,EAC9B,eAAe,EACf,cAAc,EACd,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC"}

package/dist-esm/lint/index.js

@@ -0,0 +1,9 @@
+/**
+ * Telemetry ESLint Rules
+ *
+ * Lint rules for enforcing telemetry best practices:
+ * - no-forbidden-attributes: Prevents Tier 1 data in Tier 2 paths
+ * - no-direct-otel-sdk: Enforces use of telemetry bootstrap
+ */
+export { noForbiddenTelemetryAttributes, noDirectOtelSdk, telemetryRules, FORBIDDEN_ATTRIBUTE_PATTERNS, } from "./forbidden-attributes.js";
+//# sourceMappingURL=index.js.map

package/dist-esm/lint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lint/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,8BAA8B,EAC9B,eAAe,EACf,cAAc,EACd,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC"}

package/dist-esm/llmobs/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * LLMObs Tiered Telemetry
+ *
+ * This module provides tiered telemetry for LLMObs (LLM Observability) data:
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createTier1LLMObsExporter,
+ *   LLMObsTier2Summarizer,
+ * } from '@superblocksteam/telemetry/llmobs';
+ *
+ * // Tier 1: Local storage
+ * const { exporter, store } = createTier1LLMObsExporter();
+ *
+ * // Tier 2: Summarize for OTEL-aligned metrics
+ * const summarizer = new LLMObsTier2Summarizer(metricsClient);
+ * ```
+ */
+export { Tier1LLMObsExporter, InMemoryLLMObsStore, createTier1LLMObsExporter, type LLMObsLocalStore, } from "./tier1-exporter.js";
+export { LLMObsTier2Summarizer, type LLMSpanSummary, type ToolSpanSummary, type LLMErrorCategory, type LLMFinishReason, type LLMProvider, type LLMRequestMetricLabels, type TokenMetricLabels, type ToolCallMetricLabels, type Tier2MetricsClient, } from "./tier2-summarizer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist-esm/llmobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llmobs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAC"}

package/dist-esm/llmobs/index.js

@@ -0,0 +1,22 @@
+/**
+ * LLMObs Tiered Telemetry
+ *
+ * This module provides tiered telemetry for LLMObs (LLM Observability) data:
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createTier1LLMObsExporter,
+ *   LLMObsTier2Summarizer,
+ * } from '@superblocksteam/telemetry/llmobs';
+ *
+ * // Tier 1: Local storage
+ * const { exporter, store } = createTier1LLMObsExporter();
+ *
+ * // Tier 2: Summarize for OTEL-aligned metrics
+ * const summarizer = new LLMObsTier2Summarizer(metricsClient);
+ * ```
+ */
+export { Tier1LLMObsExporter, InMemoryLLMObsStore, createTier1LLMObsExporter, } from "./tier1-exporter.js";
+export { LLMObsTier2Summarizer, } from "./tier2-summarizer.js";
+//# sourceMappingURL=index.js.map

package/dist-esm/llmobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llmobs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,GAE1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,GAUtB,MAAM,uBAAuB,CAAC"}

package/dist-esm/llmobs/tier1-exporter.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Tier 1 LLMObs Exporter
+ *
+ * Stores full-fidelity LLMObs spans locally for debugging.
+ * These spans contain prompts, code, tool IO - NEVER exported for cloud-prem.
+ *
+ * For cloud deployments, Tier 1 data can be exported (same trust boundary).
+ * For cloud-prem deployments, Tier 1 data stays local only.
+ */
+import type { ExportResult } from "@opentelemetry/core";
+import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+/**
+ * Storage interface for Tier 1 LLMObs spans.
+ *
+ * Provides queryable access for local debugging.
+ * Implementation can be in-memory, filesystem, or local database.
+ */
+export interface LLMObsLocalStore {
+    /**
+     * Store a span for later retrieval.
+     *
+     * @param span - The span to store
+     */
+    store(span: ReadableSpan): void;
+    /**
+     * Query spans by session ID.
+     *
+     * @param sessionId - Session ID to query
+     * @returns Matching spans
+     */
+    query(sessionId: string): ReadableSpan[];
+    /**
+     * Clear all stored spans.
+     */
+    clear(): void;
+    /**
+     * Get the count of stored spans.
+     */
+    size(): number;
+}
+/**
+ * In-memory implementation of LLMObsLocalStore.
+ *
+ * Suitable for development and short-lived processes.
+ * Spans are automatically evicted when limits are reached.
+ */
+export declare class InMemoryLLMObsStore implements LLMObsLocalStore {
+    private readonly spans;
+    private readonly maxSpansPerSession;
+    private readonly maxSessions;
+    private totalSpanCount;
+    /**
+     * Create an in-memory LLMObs store.
+     *
+     * @param options - Configuration options
+     * @param options.maxSpansPerSession - Maximum spans to retain per session (default: 1000)
+     * @param options.maxSessions - Maximum sessions to retain (default: 100)
+     */
+    constructor(options?: {
+        maxSpansPerSession?: number;
+        maxSessions?: number;
+    });
+    store(span: ReadableSpan): void;
+    query(sessionId: string): ReadableSpan[];
+    clear(): void;
+    size(): number;
+    /**
+     * Get all session IDs.
+     *
+     * @returns Array of session IDs
+     */
+    getSessions(): string[];
+    /**
+     * Extract session ID from span attributes.
+     */
+    private getSessionId;
+}
+/**
+ * Tier 1 LLMObs Exporter.
+ *
+ * Exports LLMObs spans to local storage only.
+ * These spans contain full fidelity debugging data (prompts, code, tool IO).
+ * NEVER exported to external backends in cloud-prem deployments.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryLLMObsStore();
+ * const exporter = new Tier1LLMObsExporter(store);
+ *
+ * // Later, query for debugging
+ * const spans = store.query(sessionId);
+ * ```
+ */
+export declare class Tier1LLMObsExporter implements SpanExporter {
+    private readonly localStore;
+    private readonly debugLogging;
+    private isShutdown;
+    /**
+     * Create a Tier 1 LLMObs exporter.
+     *
+     * @param localStore - Storage for local spans
+     * @param options - Configuration options
+     * @param options.debugLogging - Enable debug logging (default: false)
+     */
+    constructor(localStore: LLMObsLocalStore, options?: {
+        debugLogging?: boolean;
+    });
+    /**
+     * Export spans to local storage.
+     *
+     * @param spans - Spans to export
+     * @param resultCallback - Callback with export result
+     */
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * Shutdown the exporter.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force flush (no-op for local storage).
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Check if a span is an LLMObs span.
+     */
+    private isLLMObsSpan;
+    /**
+     * Get span duration in milliseconds.
+     */
+    private getDurationMs;
+}
+/**
+ * Create a Tier 1 LLMObs exporter with in-memory storage.
+ *
+ * @param options - Configuration options
+ * @returns Exporter and store instances
+ */
+export declare function createTier1LLMObsExporter(options?: {
+    maxSpansPerSession?: number;
+    maxSessions?: number;
+    debugLogging?: boolean;
+}): {
+    exporter: Tier1LLMObsExporter;
+    store: InMemoryLLMObsStore;
+};
+//# sourceMappingURL=tier1-exporter.d.ts.map

package/dist-esm/llmobs/tier1-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier1-exporter.d.ts","sourceRoot":"","sources":["../../src/llmobs/tier1-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAEhC;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAEzC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,cAAc,CAAK;IAE3B;;;;;;OAMG;gBAED,OAAO,GAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO;IAMrE,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IA4B/B,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE;IAIxC,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,OAAO,CAAC,YAAY;CAOrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;;;OAMG;gBAED,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAO;IAM1C;;;;;OAKG;IACH,MAAM,CACJ,KAAK,EAAE,YAAY,EAAE,EACrB,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAC7C,IAAI;IA4BP;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;OAEG;IACH,OAAO,CAAC,YAAY;IAWpB;;OAEG;IACH,OAAO,CAAC,aAAa;CAKtB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAClD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG;IAAE,QAAQ,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAShE"}

package/dist-esm/llmobs/tier1-exporter.js

@@ -0,0 +1,193 @@
+/**
+ * Tier 1 LLMObs Exporter
+ *
+ * Stores full-fidelity LLMObs spans locally for debugging.
+ * These spans contain prompts, code, tool IO - NEVER exported for cloud-prem.
+ *
+ * For cloud deployments, Tier 1 data can be exported (same trust boundary).
+ * For cloud-prem deployments, Tier 1 data stays local only.
+ */
+import { ExportResultCode } from "@opentelemetry/core";
+/**
+ * In-memory implementation of LLMObsLocalStore.
+ *
+ * Suitable for development and short-lived processes.
+ * Spans are automatically evicted when limits are reached.
+ */
+export class InMemoryLLMObsStore {
+    spans = new Map();
+    maxSpansPerSession;
+    maxSessions;
+    totalSpanCount = 0;
+    /**
+     * Create an in-memory LLMObs store.
+     *
+     * @param options - Configuration options
+     * @param options.maxSpansPerSession - Maximum spans to retain per session (default: 1000)
+     * @param options.maxSessions - Maximum sessions to retain (default: 100)
+     */
+    constructor(options = {}) {
+        this.maxSpansPerSession = options.maxSpansPerSession ?? 1000;
+        this.maxSessions = options.maxSessions ?? 100;
+    }
+    store(span) {
+        const sessionId = this.getSessionId(span) || "default";
+        // Create session if doesn't exist
+        if (!this.spans.has(sessionId)) {
+            // Evict oldest session if at capacity
+            if (this.spans.size >= this.maxSessions) {
+                const oldestSession = this.spans.keys().next().value;
+                if (oldestSession) {
+                    const evictedSpans = this.spans.get(oldestSession)?.length ?? 0;
+                    this.totalSpanCount -= evictedSpans;
+                    this.spans.delete(oldestSession);
+                }
+            }
+            this.spans.set(sessionId, []);
+        }
+        const sessionSpans = this.spans.get(sessionId);
+        sessionSpans.push(span);
+        this.totalSpanCount++;
+        // Evict oldest spans in session if at capacity
+        if (sessionSpans.length > this.maxSpansPerSession) {
+            sessionSpans.shift();
+            this.totalSpanCount--;
+        }
+    }
+    query(sessionId) {
+        return this.spans.get(sessionId) ?? [];
+    }
+    clear() {
+        this.spans.clear();
+        this.totalSpanCount = 0;
+    }
+    size() {
+        return this.totalSpanCount;
+    }
+    /**
+     * Get all session IDs.
+     *
+     * @returns Array of session IDs
+     */
+    getSessions() {
+        return Array.from(this.spans.keys());
+    }
+    /**
+     * Extract session ID from span attributes.
+     */
+    getSessionId(span) {
+        return (span.attributes["llmobs.session_id"] ||
+            span.attributes["session.id"] ||
+            span.attributes["session_id"]);
+    }
+}
+/**
+ * Tier 1 LLMObs Exporter.
+ *
+ * Exports LLMObs spans to local storage only.
+ * These spans contain full fidelity debugging data (prompts, code, tool IO).
+ * NEVER exported to external backends in cloud-prem deployments.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryLLMObsStore();
+ * const exporter = new Tier1LLMObsExporter(store);
+ *
+ * // Later, query for debugging
+ * const spans = store.query(sessionId);
+ * ```
+ */
+export class Tier1LLMObsExporter {
+    localStore;
+    debugLogging;
+    isShutdown = false;
+    /**
+     * Create a Tier 1 LLMObs exporter.
+     *
+     * @param localStore - Storage for local spans
+     * @param options - Configuration options
+     * @param options.debugLogging - Enable debug logging (default: false)
+     */
+    constructor(localStore, options = {}) {
+        this.localStore = localStore;
+        this.debugLogging = options.debugLogging ?? false;
+    }
+    /**
+     * Export spans to local storage.
+     *
+     * @param spans - Spans to export
+     * @param resultCallback - Callback with export result
+     */
+    export(spans, resultCallback) {
+        if (this.isShutdown) {
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: new Error("Exporter is shutdown"),
+            });
+            return;
+        }
+        for (const span of spans) {
+            // Only store LLMObs-related spans
+            if (this.isLLMObsSpan(span)) {
+                this.localStore.store(span);
+                if (this.debugLogging) {
+                    console.debug("[LLMObs Tier 1]", span.name, {
+                        traceId: span.spanContext().traceId,
+                        duration: this.getDurationMs(span),
+                        hasInput: !!span.attributes["llmobs.input"],
+                        hasOutput: !!span.attributes["llmobs.output"],
+                    });
+                }
+            }
+        }
+        resultCallback({ code: ExportResultCode.SUCCESS });
+    }
+    /**
+     * Shutdown the exporter.
+     */
+    async shutdown() {
+        this.isShutdown = true;
+    }
+    /**
+     * Force flush (no-op for local storage).
+     */
+    async forceFlush() {
+        // No-op for local storage
+    }
+    /**
+     * Check if a span is an LLMObs span.
+     */
+    isLLMObsSpan(span) {
+        return (span.name.startsWith("ai.") ||
+            span.name.startsWith("llmobs.") ||
+            span.name.startsWith("llm.") ||
+            span.name.startsWith("tool.") ||
+            span.name.startsWith("clark.") ||
+            !!span.attributes["llmobs.span_kind"]);
+    }
+    /**
+     * Get span duration in milliseconds.
+     */
+    getDurationMs(span) {
+        const [startSecs, startNanos] = span.startTime;
+        const [endSecs, endNanos] = span.endTime;
+        return (endSecs - startSecs) * 1000 + (endNanos - startNanos) / 1e6;
+    }
+}
+/**
+ * Create a Tier 1 LLMObs exporter with in-memory storage.
+ *
+ * @param options - Configuration options
+ * @returns Exporter and store instances
+ */
+export function createTier1LLMObsExporter(options) {
+    const store = new InMemoryLLMObsStore({
+        maxSpansPerSession: options?.maxSpansPerSession,
+        maxSessions: options?.maxSessions,
+    });
+    const exporter = new Tier1LLMObsExporter(store, {
+        debugLogging: options?.debugLogging,
+    });
+    return { exporter, store };
+}
+//# sourceMappingURL=tier1-exporter.js.map

package/dist-esm/llmobs/tier1-exporter.js.map

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