@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/llmobs/tracer.d.ts

@@ -0,0 +1,130 @@
+import type { ExportedLLMObsSpan, LLMObsAnnotationOptions, LLMObsEvaluationOptions, LLMObsManualSpanOptions, LLMObsNamedSpanOptions, LLMObsNamelessSpanOptions, LLMObsRootPolicy, LLMObsSpan, LLMObsTraceHeaders } from "./types.js";
+/**
+ * Span tags that carry the CALLER's OpenTelemetry ids (parsed from the incoming
+ * W3C `traceparent`) onto the LLMObs generation trace.
+ *
+ * dd-trace's own `apm_trace_id` on LLMObs spans is a dd-native id that does not
+ * match the OTel APM journey: LLMObs runs as agentless dd-trace, the journey as
+ * OTel, so they are two separate id spaces and from an LLMObs span you cannot
+ * reach the connected APM trace. These tags record the real OTel journey ids so
+ * a generation can be correlated back to its APM trace by `superblocks.apm.trace_id`.
+ */
+export declare const APM_TRACE_ID_TAG = "superblocks.apm.trace_id";
+export declare const APM_SPAN_ID_TAG = "superblocks.apm.span_id";
+/** Parse a W3C `<version>-<traceId:32>-<spanId:16>-<flags>` into correlation tags. */
+export declare function apmCorrelationTags(traceHeaders: LLMObsTraceHeaders | undefined): Record<string, string> | undefined;
+/**
+ * Core tracer responsible for LLM observability within the AI service.
+ *
+ * Provides utilities for executing code within spans, managing span lifecycles,
+ * and decorating functions or classes with consistent instrumentation.
+ */
+export declare class LLMObsTracer {
+    private globalState;
+    private localStorage;
+    private globalTags;
+    private defaultRootPolicy;
+    private static _instance;
+    rootSpan?: LLMObsSpan;
+    protected constructor({ defaultRootPolicy, }?: {
+        defaultRootPolicy?: LLMObsRootPolicy;
+    });
+    static get instance(): LLMObsTracer;
+    /**
+     * Set the default root policy for spans created without an explicit policy.
+     * The default is 'allow'.
+     * @see LLMObsRootPolicy
+     */
+    setDefaultRootPolicy(policy: LLMObsRootPolicy): void;
+    /**
+     * Execute a function within a traced span context and finish the span
+     * automatically once the function resolves.
+     */
+    trace<T>(options: LLMObsNamedSpanOptions, fn: (span: LLMObsSpan) => T): T;
+    /**
+     * Wrap a function so each invocation runs inside an automatically managed span.
+     * When the function lacks a name, the span falls back to the provided kind.
+     */
+    wrap<T extends (...args: any[]) => any>(options: LLMObsNamelessSpanOptions, fn: T): T;
+    startActiveSpan(options: LLMObsManualSpanOptions): LLMObsSpan;
+    /**
+     * Flush any buffered spans.
+     */
+    flush(): void;
+    /**
+     * Export the supplied span (or the currently active span) into the
+     * DataDog-specific wire format for manual submission.
+     */
+    exportSpan(span?: LLMObsSpan): ExportedLLMObsSpan;
+    /**
+     * Annotate a span with tags, metadata, and optional error details.
+     * If only annotations are provided, the active span is annotated.
+     */
+    annotate(annotations: LLMObsAnnotationOptions): void;
+    annotate(span: LLMObsSpan, annotations: LLMObsAnnotationOptions): void;
+    /** Submit feedback or evaluation metrics for a completed span. */
+    submitEvaluation(spanContext: ExportedLLMObsSpan, option: LLMObsEvaluationOptions): void;
+    /**
+     * Create a decorator factory that wraps functions inside traced spans using
+     * the provided options as defaults.
+     */
+    decorate<T extends (...args: any[]) => any>(options: LLMObsNamelessSpanOptions): (target: T) => T;
+    /** Retrieve the currently active span, falling back to global state. */
+    active(): LLMObsSpan | undefined;
+    /**
+     * Merge globally-applied tags into those sent with every span that this tracer
+     * creates. Later tags override earlier ones when keys overlap.
+     */
+    setGlobalTags(tags: {
+        [key: string]: any;
+    }): void;
+    /**
+     * Register the span with local/global state, override its finish behaviour,
+     * and apply global tags so nested spans maintain proper hierarchy.
+     */
+    private register;
+    /** Runs tracing for both auto-finishing and manually finished spans. */
+    private _trace;
+    private static createNoopSpan;
+    /**
+     * Store the captured OTEL context in the registry if applicable.
+     * Shared between the auto-finish and manual-finish branches of _trace().
+     * Only called for root LLMObs spans (capturedOtelCtx is undefined for children).
+     * Noop spans are excluded — they have no real dd-trace span ID to key on.
+     */
+    private maybeCaptureRootOtelCtx;
+    /**
+     * Activate a span as the current parent context for downstream traces.
+     *
+     * Root spans use an undefined span to clear stale ambient LLMObs context
+     * without discarding other values held in Datadog's storage.
+     */
+    private activate;
+    private activateDatadogTraceContext;
+    private get localState();
+    private static _llmobs;
+    private static _otelExporterInitialized;
+    private static _isCloudPremCached;
+    private get llmobs();
+    /**
+     * Check if current deployment is CLOUD_PREM.
+     * In CLOUD_PREM, LLMObs spans are converted to OTEL spans instead of
+     * being sent directly to Datadog LLMObs API.
+     * Result is cached since deployment type is constant for process lifetime.
+     */
+    private static isCloudPrem;
+    private setModel;
+    private setTag;
+    /**
+     * Realign a child span created within a manual parent so it retains the
+     * correct trace/parent IDs; mirrors dd-trace's internal behaviour.
+     */
+    private static alignManualChildTrace;
+    /** True when a span was created via {@link startActiveSpan}. */
+    private static isManualSpan;
+    /** Normalize annotation payloads so tags and metadata are consistently shaped. */
+    private static normalizeAnnotationPayload;
+}
+declare const tracer: LLMObsTracer;
+export default tracer;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/ai-service/llmobs/tracer.d.ts.map

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

package/dist/ai-service/llmobs/tracer.js

@@ -0,0 +1,532 @@
+import { AsyncLocalStorage } from "async_hooks";
+import { context as otelContextApi, trace as otelTrace, } from "@opentelemetry/api";
+import ddTrace from "dd-trace";
+import { storage as llmobsStorage } from "dd-trace/packages/dd-trace/src/llmobs/storage.js";
+import { safeJsonStringify } from "../../util/log-sanitizer.js";
+import { getErrorMeta, getLogger } from "../../util/logger.js";
+import { otelContextRegistry } from "./context-registry.js";
+const ddTraceInternal = ddTrace;
+/**
+ * Lazily initialize dd-trace with LLMObs if not already configured.
+ * This is needed when running via turbo (start:all:obs) which bypasses
+ * the CLI's configureTelemetry() that normally initializes LLMObs.
+ *
+ * Called from `get llmobs()` to avoid module-level side effects that
+ * create test hazards (any transitive import would trigger dd-trace init).
+ */
+let _llmobsInitAttempted = false;
+function ensureLlmobsInitialized() {
+    if (_llmobsInitAttempted)
+        return;
+    _llmobsInitAttempted = true;
+    const shouldEnableLlmobs = (process.env.DD_LLMOBS_ENABLED === "1" ||
+        process.env.SUPERBLOCKS_LLMOBS_ENABLED === "true") &&
+        process.env.DD_LLMOBS_ML_APP;
+    if (shouldEnableLlmobs && !ddTrace.llmobs.enabled) {
+        // dd-trace was auto-initialized without LLMObs. Re-init with LLMObs config.
+        // Note: dd-trace.init() is idempotent for most settings but will enable LLMObs.
+        ddTrace.init({
+            // Don't override existing service config if already set
+            service: ddTraceInternal._tracer?._config?.service || "superblocks-ai-code-gen",
+            // Enable LLMObs with env var config
+            llmobs: {
+                mlApp: process.env.DD_LLMOBS_ML_APP || "superblocks-ai-code-gen",
+                agentlessEnabled: process.env.DD_LLMOBS_AGENTLESS_ENABLED === "1",
+            },
+        });
+    }
+}
+import { DD_INTERNAL_TAGS } from "./constants.js";
+import { llmobsOtelExporter } from "./otel-exporter.js";
+import { getCanonicalModel } from "./utils.js";
+/**
+ * Span tags that carry the CALLER's OpenTelemetry ids (parsed from the incoming
+ * W3C `traceparent`) onto the LLMObs generation trace.
+ *
+ * dd-trace's own `apm_trace_id` on LLMObs spans is a dd-native id that does not
+ * match the OTel APM journey: LLMObs runs as agentless dd-trace, the journey as
+ * OTel, so they are two separate id spaces and from an LLMObs span you cannot
+ * reach the connected APM trace. These tags record the real OTel journey ids so
+ * a generation can be correlated back to its APM trace by `superblocks.apm.trace_id`.
+ */
+export const APM_TRACE_ID_TAG = "superblocks.apm.trace_id";
+export const APM_SPAN_ID_TAG = "superblocks.apm.span_id";
+/** Parse a W3C `<version>-<traceId:32>-<spanId:16>-<flags>` into correlation tags. */
+export function apmCorrelationTags(traceHeaders) {
+    const traceparent = traceHeaders?.traceparent;
+    if (!traceparent) {
+        return undefined;
+    }
+    const [, traceId, spanId] = traceparent.split("-");
+    if (!traceId || !spanId || traceId.length !== 32 || spanId.length !== 16) {
+        return undefined;
+    }
+    return { [APM_TRACE_ID_TAG]: traceId, [APM_SPAN_ID_TAG]: spanId };
+}
+/** Stack implementation that allows random access removals for span bookkeeping. */
+class IndexedStack {
+    items = [];
+    /** Push a new item onto the stack. */
+    push(item) {
+        this.items.push(item);
+    }
+    /** Peek at the item on the top of the stack without removing it. */
+    top() {
+        return this.items[this.items.length - 1];
+    }
+    /** Remove a specific item from the stack if present. */
+    remove(item) {
+        const index = this.items.indexOf(item);
+        if (index !== -1) {
+            this.items.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /** The number of items currently tracked by the stack. */
+    length() {
+        return this.items.length;
+    }
+}
+class State extends IndexedStack {
+}
+/**
+ * Core tracer responsible for LLM observability within the AI service.
+ *
+ * Provides utilities for executing code within spans, managing span lifecycles,
+ * and decorating functions or classes with consistent instrumentation.
+ */
+export class LLMObsTracer {
+    globalState = new State();
+    localStorage = new AsyncLocalStorage();
+    globalTags = {};
+    defaultRootPolicy;
+    static _instance = new LLMObsTracer();
+    rootSpan;
+    constructor({ defaultRootPolicy = "allow", } = {}) {
+        this.defaultRootPolicy = defaultRootPolicy;
+        this.localStorage.enterWith(new State());
+    }
+    static get instance() {
+        return LLMObsTracer._instance;
+    }
+    /**
+     * Set the default root policy for spans created without an explicit policy.
+     * The default is 'allow'.
+     * @see LLMObsRootPolicy
+     */
+    setDefaultRootPolicy(policy) {
+        this.defaultRootPolicy = policy;
+    }
+    /**
+     * Execute a function within a traced span context and finish the span
+     * automatically once the function resolves.
+     */
+    trace(options, fn) {
+        return this._trace({ finish: "auto", ...options }, fn);
+    }
+    /**
+     * Wrap a function so each invocation runs inside an automatically managed span.
+     * When the function lacks a name, the span falls back to the provided kind.
+     */
+    wrap(options, fn) {
+        const name = options.name || fn.name || options.kind;
+        const trace = this.trace.bind(this);
+        return function (...args) {
+            return trace({ ...options, name }, (_span) => fn.apply(this, args));
+        };
+    }
+    startActiveSpan(options) {
+        const { activation, ...rest } = options;
+        return this._trace({ finish: "manual", activation, ...rest }, (span) => span);
+    }
+    /**
+     * Flush any buffered spans.
+     */
+    flush() {
+        try {
+            this.llmobs.flush();
+        }
+        catch {
+            /* swallow error */
+        }
+    }
+    /**
+     * Export the supplied span (or the currently active span) into the
+     * DataDog-specific wire format for manual submission.
+     */
+    exportSpan(span) {
+        if (span && isNoopSpan(span)) {
+            return {
+                traceId: "noop",
+                spanId: "noop",
+            };
+        }
+        if (!this.llmobs.enabled) {
+            return {
+                traceId: "noop",
+                spanId: "noop",
+            };
+        }
+        return this.llmobs.exportSpan(span || this.active());
+    }
+    annotate(spanOrAnnotations, maybeAnnotations) {
+        if (!this.llmobs.enabled) {
+            return;
+        }
+        const annotations = maybeAnnotations === undefined
+            ? spanOrAnnotations
+            : maybeAnnotations;
+        const targetSpan = maybeAnnotations === undefined
+            ? this.active()
+            : spanOrAnnotations;
+        const { tags, metadata, model, baseAnnotations } = LLMObsTracer.normalizeAnnotationPayload(targetSpan, annotations);
+        if (model && targetSpan) {
+            this.setModel(targetSpan, model.name, model.provider);
+        }
+        const payload = Object.keys(metadata).length
+            ? { tags, metadata, ...baseAnnotations }
+            : { tags, ...baseAnnotations };
+        try {
+            return this.llmobs.annotate(targetSpan, payload);
+        }
+        catch {
+            /* swallow error */
+        }
+    }
+    /** Submit feedback or evaluation metrics for a completed span. */
+    submitEvaluation(spanContext, option) {
+        return this.llmobs.submitEvaluation(spanContext, option);
+    }
+    /**
+     * Create a decorator factory that wraps functions inside traced spans using
+     * the provided options as defaults.
+     */
+    decorate(options) {
+        return (target) => {
+            return this.wrap(options, target);
+        };
+    }
+    /** Retrieve the currently active span, falling back to global state. */
+    active() {
+        return this.localState?.top() || this.globalState.top();
+    }
+    /**
+     * Merge globally-applied tags into those sent with every span that this tracer
+     * creates. Later tags override earlier ones when keys overlap.
+     */
+    setGlobalTags(tags) {
+        this.globalTags = { ...this.globalTags, ...tags };
+    }
+    /**
+     * Register the span with local/global state, override its finish behaviour,
+     * and apply global tags so nested spans maintain proper hierarchy.
+     */
+    register(span, finish, activation) {
+        this.annotate(span, { tags: this.globalTags });
+        const originalFinish = span.finish.bind(span);
+        if (finish === "manual") {
+            const manualSpan = span;
+            manualSpan.__isManualSpan = true;
+        }
+        span.finish = (finishTime) => {
+            this.localState?.remove(span);
+            this.globalState.remove(span);
+            try {
+                return originalFinish(finishTime);
+            }
+            catch {
+                /* swallow error */
+            }
+        };
+        const localState = this.localState;
+        if (localState) {
+            localState.push(span);
+        }
+        if (!localState || activation === "global") {
+            this.globalState.push(span);
+        }
+    }
+    /** Runs tracing for both auto-finishing and manually finished spans. */
+    _trace(options, fn) {
+        if (!this.llmobs.enabled) {
+            // Tracing is disabled; execute the function without span management.
+            getLogger().debug("llmobs tracing is disabled");
+            const noopSpan = LLMObsTracer.createNoopSpan();
+            return fn(noopSpan);
+        }
+        const { tags, finish, activation = "local", rootPolicy = this.defaultRootPolicy, traceHeaders, ...rest } = options;
+        const parentContext = this.active();
+        const hasTraceHeaders = Boolean(traceHeaders?.traceparent || traceHeaders?.tracestate);
+        if (!parentContext &&
+            !hasTraceHeaders &&
+            rootPolicy === "drop-if-no-parent") {
+            const noopSpan = LLMObsTracer.createNoopSpan();
+            if (finish === "auto") {
+                return this.localStorage.run(new State(), () => fn(noopSpan));
+            }
+            return fn(noopSpan);
+        }
+        const setup = (span, parent) => {
+            this.register(span, finish, activation);
+            // On the root generation span, also tag the caller's OTel journey ids so
+            // this LLMObs trace can be correlated back to its connected APM trace
+            // (dd-trace's apm_trace_id does not match the OTel journey; see above).
+            const apmTags = parent ? undefined : apmCorrelationTags(traceHeaders);
+            this.annotate(span, { tags: apmTags ? { ...tags, ...apmTags } : tags });
+            if (!parent || parent === span) {
+                return;
+            }
+            if (LLMObsTracer.isManualSpan(span) ||
+                LLMObsTracer.isManualSpan(parent)) {
+                LLMObsTracer.alignManualChildTrace(span, parent);
+            }
+        };
+        return this.activateDatadogTraceContext(traceHeaders, parentContext, () => this.activate(parentContext, () => {
+            // Capture OTEL context BEFORE llmobs.trace() activates the new
+            // dd-trace span. Inside the callback, dd-trace has already activated
+            // the new span and may propagate it into OTEL AsyncLocalStorage.
+            //
+            // Only root LLMObs spans need a captured entry: children resolve
+            // context via perFlushCtx / crossBatch in processBatch.
+            //
+            // For legacy Cloud Prem roots without incoming trace headers, strip
+            // any active OTEL span so standalone Clark sessions remain roots. When
+            // request trace headers are present, preserve the ambient context so
+            // the LLMObs-derived OTEL spans can join the request trace.
+            const capturedOtelCtx = LLMObsTracer.isCloudPrem() && !parentContext
+                ? hasTraceHeaders
+                    ? otelContextApi.active()
+                    : otelTrace.deleteSpan(otelContextApi.active())
+                : undefined;
+            if (finish === "auto") {
+                return this.llmobs.trace(rest, (span) => {
+                    return this.localStorage.run(new State(), () => {
+                        this.maybeCaptureRootOtelCtx(span, capturedOtelCtx);
+                        setup(span, parentContext);
+                        return fn(span);
+                    });
+                });
+            }
+            else {
+                return this.llmobs.trace(rest, (span, _done) => {
+                    this.maybeCaptureRootOtelCtx(span, capturedOtelCtx);
+                    setup(span, parentContext);
+                    return fn(span);
+                });
+            }
+        }));
+    }
+    static createNoopSpan() {
+        const context = () => ({
+            toTraceId: () => "",
+            toSpanId: () => "",
+            toTraceparent: () => "",
+        });
+        const span = {
+            finish: () => {
+                /* noop */
+            },
+            context,
+        };
+        span.__isNoopSpan = true;
+        return span;
+    }
+    /**
+     * Store the captured OTEL context in the registry if applicable.
+     * Shared between the auto-finish and manual-finish branches of _trace().
+     * Only called for root LLMObs spans (capturedOtelCtx is undefined for children).
+     * Noop spans are excluded — they have no real dd-trace span ID to key on.
+     */
+    maybeCaptureRootOtelCtx(span, capturedOtelCtx) {
+        if (capturedOtelCtx && !isNoopSpan(span)) {
+            otelContextRegistry.captureAtSpanStart(span.context().toSpanId(), capturedOtelCtx);
+        }
+    }
+    /**
+     * Activate a span as the current parent context for downstream traces.
+     *
+     * Root spans use an undefined span to clear stale ambient LLMObs context
+     * without discarding other values held in Datadog's storage.
+     */
+    activate(span, fn) {
+        if (!this.llmobs.enabled) {
+            return fn();
+        }
+        return llmobsStorage.run({ ...llmobsStorage.getStore(), span }, fn);
+    }
+    activateDatadogTraceContext(traceHeaders, parentContext, fn) {
+        if (parentContext ||
+            !(traceHeaders?.traceparent || traceHeaders?.tracestate)) {
+            return fn();
+        }
+        // Only the header extraction and span creation are guarded: fn must run
+        // outside the try, or a synchronous throw inside the traced callback
+        // (rethrown by dd-trace's scope().activate) would be caught here and run
+        // the callback a second time.
+        let bridgeSpan;
+        try {
+            const extracted = ddTrace.extract("http_headers", traceHeaders);
+            if (extracted) {
+                bridgeSpan = ddTrace.startSpan("llmobs.apm_bridge", {
+                    childOf: extracted,
+                });
+            }
+        }
+        catch {
+            bridgeSpan = undefined;
+        }
+        if (!bridgeSpan) {
+            return fn();
+        }
+        const activeBridgeSpan = bridgeSpan;
+        return ddTrace.scope().activate(activeBridgeSpan, () => {
+            try {
+                return fn();
+            }
+            finally {
+                activeBridgeSpan.finish();
+            }
+        });
+    }
+    get localState() {
+        return this.localStorage.getStore();
+    }
+    static _llmobs = null;
+    static _otelExporterInitialized = false;
+    static _isCloudPremCached = null;
+    get llmobs() {
+        if (!LLMObsTracer._llmobs?.enabled) {
+            // Ensure dd-trace is initialized with LLMObs config if needed
+            ensureLlmobsInitialized();
+            // Lazily access ddTrace.llmobs to avoid triggering dd-trace initialization
+            // before ddTrace.init() is called
+            LLMObsTracer._llmobs = ddTrace.llmobs;
+            // Sync global tags from dd-trace config if available.
+            this.setGlobalTags(ddTraceInternal._tracer?._config?.tags ?? {});
+        }
+        // Initialize OTEL exporter for CLOUD_PREM deployments when LLMObs becomes enabled.
+        // This patches LLMObsSpanWriter.flush to convert spans to OTEL format instead of
+        // sending them directly to Datadog LLMObs API.
+        if (LLMObsTracer._llmobs?.enabled &&
+            !LLMObsTracer._otelExporterInitialized &&
+            LLMObsTracer.isCloudPrem()) {
+            // Mark as initialized before async call to prevent duplicate init attempts
+            LLMObsTracer._otelExporterInitialized = true;
+            llmobsOtelExporter.init().catch((err) => {
+                LLMObsTracer._otelExporterInitialized = false;
+                getLogger().error("Failed to initialize OTEL exporter for LLMObs", getErrorMeta(err));
+            });
+        }
+        return LLMObsTracer._llmobs;
+    }
+    /**
+     * Check if current deployment is CLOUD_PREM.
+     * In CLOUD_PREM, LLMObs spans are converted to OTEL spans instead of
+     * being sent directly to Datadog LLMObs API.
+     * Result is cached since deployment type is constant for process lifetime.
+     */
+    static isCloudPrem() {
+        if (LLMObsTracer._isCloudPremCached !== null) {
+            return LLMObsTracer._isCloudPremCached;
+        }
+        // First, try to import from SDK (if available as a dependency)
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { isCloudPrem } = require("@superblocksteam/sdk");
+            LLMObsTracer._isCloudPremCached = isCloudPrem;
+            return isCloudPrem;
+        }
+        catch (error) {
+            if (error?.code !== "MODULE_NOT_FOUND") {
+                getLogger().debug("Error checking isCloudPrem:", { error });
+            }
+            // Fallback: check env var directly (for when SDK is not available)
+            const deploymentType = process.env.SUPERBLOCKS_DEPLOYMENT_TYPE;
+            const isCloudPrem = deploymentType === "cloud-prem";
+            LLMObsTracer._isCloudPremCached = isCloudPrem;
+            getLogger().debug(`isCloudPrem fallback to env var: SUPERBLOCKS_DEPLOYMENT_TYPE=${deploymentType}, isCloudPrem=${isCloudPrem}`);
+            return isCloudPrem;
+        }
+    }
+    setModel(span, modelName, modelProvider) {
+        const { provider, modelId } = getCanonicalModel({
+            provider: modelProvider,
+            modelId: modelName,
+        });
+        this.setTag(span, DD_INTERNAL_TAGS.MODEL_NAME, modelId);
+        this.setTag(span, DD_INTERNAL_TAGS.MODEL_PROVIDER, provider);
+    }
+    setTag(span, key, value) {
+        try {
+            this.llmobs._tagger?._setTag(span, key, value);
+        }
+        catch {
+            /* swallow error */
+        }
+    }
+    /**
+     * Realign a child span created within a manual parent so it retains the
+     * correct trace/parent IDs; mirrors dd-trace's internal behaviour.
+     */
+    static alignManualChildTrace(child, parent) {
+        const childContext = child.context();
+        const parentContext = parent.context();
+        childContext._parentId = parentContext._spanId;
+        const parentTrace = parentContext._trace;
+        const childTrace = childContext._trace;
+        if (!parentTrace || childTrace === parentTrace) {
+            return;
+        }
+        if (childTrace?.started) {
+            const index = childTrace.started.indexOf(child);
+            if (index !== -1) {
+                childTrace.started.splice(index, 1);
+            }
+        }
+        childContext._trace = parentTrace;
+        childContext._traceId = parentContext._traceId;
+        if (Array.isArray(parentTrace.started) &&
+            parentTrace.started.indexOf(child) === -1) {
+            parentTrace.started.push(child);
+        }
+    }
+    /** True when a span was created via {@link startActiveSpan}. */
+    static isManualSpan(span) {
+        return Boolean(span.__isManualSpan);
+    }
+    /** Normalize annotation payloads so tags and metadata are consistently shaped. */
+    static normalizeAnnotationPayload(span, raw) {
+        const { error, tags: rawTags = {}, metadata: rawMetadata = {}, model, ...baseAnnotations } = raw;
+        const tags = { ...rawTags };
+        const internalContext = span?.context();
+        // Merge any existing metadata from span context
+        const metadata = {
+            ...internalContext?._metadata,
+            ...rawMetadata,
+        };
+        if (internalContext) {
+            internalContext._metadata = metadata;
+        }
+        if (error !== undefined) {
+            tags.error = true;
+            if (error instanceof Error) {
+                Object.assign(tags, {
+                    "error.msg": error.message,
+                    "error.stack": error.stack,
+                    "error.type": error.name,
+                });
+            }
+            else {
+                metadata.error = safeJsonStringify(error);
+            }
+        }
+        return { tags, metadata, model, baseAnnotations };
+    }
+}
+function isNoopSpan(span) {
+    return Boolean(span.__isNoopSpan);
+}
+const tracer = LLMObsTracer.instance;
+export default tracer;
+//# sourceMappingURL=tracer.js.map