neatlogs 1.1.19 → 1.1.21

package/dist/cli.mjs

@@ -58,6 +58,110 @@ function enableLogging() {
   _disabled = false;
 }
 
+// src/span-kinds/constants.ts
+var VECTOR_DB_SYSTEMS = /* @__PURE__ */ new Set([
+  "chroma",
+  "chromadb",
+  "pinecone",
+  "qdrant",
+  "milvus",
+  "marqo",
+  "weaviate",
+  "lancedb",
+  "pgvector",
+  "elasticsearch"
+]);
+var RETRIEVAL_OPS = [
+  "query",
+  "search",
+  "get",
+  "fetch",
+  "find",
+  "retrieve",
+  "scroll",
+  "peek",
+  "discover",
+  "recommend",
+  "aggregate",
+  "hybrid_search",
+  "select"
+];
+var VECTOR_DB_NAMES = [
+  "chroma",
+  "pinecone",
+  "weaviate",
+  "qdrant",
+  "milvus",
+  "lancedb",
+  "marqo"
+];
+
+// src/span-kinds/mapping.ts
+var VALID_SPAN_KINDS = /* @__PURE__ */ new Set([
+  "WORKFLOW",
+  "AGENT",
+  "CHAIN",
+  "TOOL",
+  "RETRIEVER",
+  "EMBEDDING",
+  "MCP_TOOL",
+  "GUARDRAIL",
+  "EVALUATOR"
+]);
+var ALL_SPAN_KINDS = /* @__PURE__ */ new Set([
+  ...VALID_SPAN_KINDS,
+  "LLM",
+  "RERANKER",
+  "VECTOR_STORE"
+]);
+function resolveExplicitSpanKind(attributes) {
+  for (const key of [
+    "neatlogs.span.kind",
+    "openinference.span.kind",
+    "traceloop.span.kind"
+  ]) {
+    const value = String(attributes[key] ?? "").trim();
+    if (value) return value;
+  }
+  return "";
+}
+function inferSpanKindFromName(spanName) {
+  const nameLower = spanName.toLowerCase();
+  if (["openai", "anthropic", "cohere", "bedrock", "chat", "completion", "llm", "gemini", "google_genai"].some(
+    (kw) => nameLower.includes(kw)
+  )) {
+    return "LLM";
+  }
+  if (nameLower.includes("embed")) {
+    return "EMBEDDING";
+  }
+  if (VECTOR_DB_NAMES.some((db) => nameLower.includes(db))) {
+    if (RETRIEVAL_OPS.some((kw) => nameLower.includes(kw))) {
+      return "RETRIEVER";
+    }
+    return "VECTOR_STORE";
+  }
+  if (["retriev", "search", "query"].some((kw) => nameLower.includes(kw))) {
+    return "RETRIEVER";
+  }
+  if (nameLower.includes("rerank")) {
+    return "RERANKER";
+  }
+  if (nameLower.includes("agent")) {
+    return "AGENT";
+  }
+  if (["tool", "function"].some((kw) => nameLower.includes(kw))) {
+    return "TOOL";
+  }
+  if (["guardrail", "validate", "moderate", "safety"].some((kw) => nameLower.includes(kw))) {
+    return "GUARDRAIL";
+  }
+  if (["evaluat", "score", "metric"].some((kw) => nameLower.includes(kw))) {
+    return "EVALUATOR";
+  }
+  return "CHAIN";
+}
+
 // src/config/attribute-mapping.json
 var attribute_mapping_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
@@ -1235,27 +1339,11 @@ var AttributeMapper = class {
   /** Extract and normalize span kind from multiple possible sources. */
   mapSpanKind(attributes) {
     const spanKindConfig = this.mappings.span_kind ?? {};
-    const sources = spanKindConfig.sources ?? [];
     const valuesMap = spanKindConfig.values ?? {};
-    const priority = spanKindConfig.priority ?? "openinference";
-    let spanKindValue;
-    if (priority === "openinference") {
-      if ("openinference.span.kind" in attributes) {
-        spanKindValue = attributes["openinference.span.kind"];
-      }
-    } else {
-      for (const source of sources) {
-        if (source in attributes) {
-          spanKindValue = attributes[source];
-          break;
-        }
-      }
-    }
-    if (!spanKindValue && "neatlogs.span.kind" in attributes) {
-      spanKindValue = attributes["neatlogs.span.kind"];
-    }
-    if (spanKindValue && spanKindValue in valuesMap) {
-      return valuesMap[spanKindValue];
+    const spanKindValue = resolveExplicitSpanKind(attributes);
+    if (spanKindValue) {
+      const mapped = valuesMap[spanKindValue] ?? valuesMap[spanKindValue.toUpperCase()];
+      if (mapped) return mapped;
     }
     if (spanKindValue && Object.values(valuesMap).includes(spanKindValue)) {
       return spanKindValue;
@@ -1829,7 +1917,7 @@ function clearDoctorCapture() {
 
 // src/core/context.ts
 import {
-  trace as otelTrace2,
+  trace as otelTrace3,
   createContextKey as createContextKey2,
   ROOT_CONTEXT as ROOT_CONTEXT3,
   SpanStatusCode as SpanStatusCode3
@@ -2177,11 +2265,11 @@ function getNeatlogsRootSpan() {
 function getNeatlogsParentContext(baseContext) {
   return baseContext ?? getNeatlogsActiveContext();
 }
-function withNeatlogsSpan(span2, fn, baseContext) {
+function withNeatlogsSpan(span2, fn, baseContext, rootSpan) {
   const base = baseContext ?? getNeatlogsActiveContext();
   let ctx = otelTrace.setSpan(base, span2);
   if (base.getValue(NEATLOGS_ROOT_SPAN_KEY) === void 0) {
-    ctx = ctx.setValue(NEATLOGS_ROOT_SPAN_KEY, span2);
+    ctx = ctx.setValue(NEATLOGS_ROOT_SPAN_KEY, rootSpan ?? span2);
   }
   return privateContextStorage.run(ctx, fn);
 }
@@ -3913,6 +4001,84 @@ function discardPendingMediaOwner(owner) {
   pendingMediaOwners.delete(owner ?? defaultPendingMediaOwner);
 }
 
+// src/core/auto-root.ts
+import {
+  trace as otelTrace2
+} from "@opentelemetry/api";
+var boundAutoRoots = /* @__PURE__ */ new WeakMap();
+var ROOT_KINDS = /* @__PURE__ */ new Set(["workflow", "chain", "agent", "mcp_tool", "llm"]);
+function autoRootEnabled() {
+  const val = (process.env.NEATLOGS_AUTO_ROOT ?? "").trim().toLowerCase();
+  return !["false", "0", "no", "off"].includes(val);
+}
+function resolveRootWorkflowName() {
+  const clientName = getActiveClient()?.workflowName;
+  if (typeof clientName === "string" && clientName.trim()) return clientName;
+  try {
+    const name = getSessionConfig()?.workflowName;
+    if (typeof name === "string" && name.trim()) return name;
+  } catch {
+  }
+  return "workflow";
+}
+function stampRootIdentity(root) {
+  applySessionAttributes(root, void 0, true);
+  applyEndUserAttributes(root, void 0, void 0, true);
+}
+function bindSpanToAutoRoot(child, root) {
+  if (!root) return child;
+  let ended = false;
+  const proxy = new Proxy(child, {
+    get(target, prop, _receiver) {
+      if (prop === "end") {
+        return (...args) => {
+          if (ended) return;
+          ended = true;
+          try {
+            target.end(...args);
+          } finally {
+            try {
+              root.end();
+            } catch {
+            }
+          }
+        };
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+  boundAutoRoots.set(proxy, root);
+  aliasMediaCaptureSpan(proxy, child);
+  return proxy;
+}
+function maybeOpenAutoRoot(tracer, kind, baseCtx) {
+  const k = String(kind ?? "").toLowerCase();
+  const existing = getActiveNeatlogsSpan();
+  if (!autoRootEnabled() || ROOT_KINDS.has(k) || existing !== void 0 && existing.isRecording()) {
+    return { root: void 0, ctx: baseCtx };
+  }
+  const root = tracer.startSpan(
+    resolveRootWorkflowName(),
+    { attributes: { "neatlogs.span.kind": "workflow", "neatlogs.auto_root": true } },
+    baseCtx
+  );
+  stampRootIdentity(root);
+  return { root, ctx: otelTrace2.setSpan(baseCtx, root) };
+}
+
+// src/errors.ts
+var NeatlogsConfigurationError = class extends TypeError {
+  code;
+  option;
+  constructor(code, option, message) {
+    super(message);
+    this.name = "NeatlogsConfigurationError";
+    this.code = code;
+    this.option = option;
+  }
+};
+
 // src/decorators/base.ts
 import {
   ROOT_CONTEXT as ROOT_CONTEXT2,
@@ -3990,7 +4156,28 @@ function decorateSpan(opts, fn) {
     const tracer = getNeatlogsTracer(TRACER_NAME);
     const isRoot = isRootSpan();
     const parentContext = isRoot ? ROOT_CONTEXT2 : getNeatlogsParentContext();
-    const span2 = tracer.startSpan(spanName, {}, parentContext);
+    const autoRoot = maybeOpenAutoRoot(
+      tracer,
+      String(opts.kind ?? ""),
+      parentContext
+    );
+    if (autoRoot.root) {
+      applySessionAttributes(autoRoot.root, opts.sessionId, true, {
+        parentSessionId: opts.parentSessionId,
+        sessionFeatureName: opts.sessionFeatureName,
+        sessionEntryPoint: opts.sessionEntryPoint
+      });
+      applyEndUserAttributes(
+        autoRoot.root,
+        opts.endUserId,
+        opts.endUserMetadata,
+        true
+      );
+    }
+    const span2 = bindSpanToAutoRoot(
+      tracer.startSpan(spanName, {}, autoRoot.ctx),
+      autoRoot.root
+    );
     return withNeatlogsSpan(span2, () => {
       let finished = false;
       let streamInterrupted = false;
@@ -4359,7 +4546,8 @@ function decorateSpan(opts, fn) {
       });
       try {
         setCommonSpanAttrs(span2, opts);
-        applySessionAttributes(span2, opts.sessionId, isRoot, {
+        const spanIsRoot = isRoot && !autoRoot.root;
+        applySessionAttributes(span2, opts.sessionId, spanIsRoot, {
           parentSessionId: opts.parentSessionId,
           sessionFeatureName: opts.sessionFeatureName,
           sessionEntryPoint: opts.sessionEntryPoint
@@ -4368,7 +4556,7 @@ function decorateSpan(opts, fn) {
           span2,
           opts.endUserId,
           opts.endUserMetadata,
-          isRoot
+          spanIsRoot
         );
         if (captureInput && args.length > 0) {
           try {
@@ -4408,7 +4596,7 @@ function decorateSpan(opts, fn) {
         finishError(error);
         throw error;
       }
-    });
+    }, autoRoot.ctx, autoRoot.root);
   };
   Object.defineProperty(wrapped, "name", {
     value: spanName,
@@ -4437,6 +4625,9 @@ var _sessionConfig = {};
 function _setSessionConfig(config) {
   _sessionConfig = config;
 }
+function getSessionConfig() {
+  return { ..._sessionConfig };
+}
 var PROMPT_VARIABLES_KEY = createContextKey2("neatlogs.prompt_variables");
 var PROMPT_TEMPLATE_KEY = createContextKey2("neatlogs.prompt_template");
 var PROMPT_VERSION_KEY = createContextKey2("neatlogs.prompt_version");
@@ -4460,6 +4651,20 @@ var KNOWN_OPTION_KEYS = /* @__PURE__ */ new Set([
   "endUserId",
   "endUserMetadata"
 ]);
+function assertNoHttpSpanKind(kind, attributes) {
+  const candidates = [
+    kind,
+    attributes?.["neatlogs.span.kind"],
+    attributes?.["openinference.span.kind"]
+  ];
+  if (candidates.some((value) => String(value ?? "").trim().toUpperCase() === "HTTP")) {
+    throw new NeatlogsConfigurationError(
+      "UNSUPPORTED_SPAN_KIND",
+      "kind",
+      "HTTP spans are not supported. Trace the semantic LLM, TOOL, RETRIEVER, or other AI operation instead."
+    );
+  }
+}
 function _setSpanAttributes(span2, kind, attributes) {
   if (kind?.toUpperCase() === "LLM") {
     span2.setAttribute("neatlogs.internal", true);
@@ -4530,6 +4735,7 @@ async function trace(options, fn) {
     attributes: explicitAttributes,
     ...extraOptions
   } = options;
+  assertNoHttpSpanKind(kind, explicitAttributes);
   const sessionId = sessionIdOption ?? currentSessionId();
   const currentSpan = getActiveNeatlogsSpan();
   const rootSpan = getNeatlogsRootSpan();
@@ -4574,7 +4780,7 @@ async function trace(options, fn) {
   }
   let ctx = getNeatlogsActiveContext();
   if (shouldFallbackToRoot) {
-    ctx = otelTrace2.setSpan(ctx, rootSpan);
+    ctx = otelTrace3.setSpan(ctx, rootSpan);
   }
   const variablesJson = promptVariables ? JSON.stringify(promptVariables) : void 0;
   const userVariablesJson = userPromptVariables ? JSON.stringify(userPromptVariables) : void 0;
@@ -4608,12 +4814,13 @@ async function trace(options, fn) {
   const tracer = getNeatlogsTracer("neatlogs.trace");
   const spanCallback = async (span3) => {
     _setSpanAttributes(span3, kind, extraAttributes);
-    applySessionAttributes(span3, sessionId, isRootTrace, {
+    const spanIsRoot = isRootTrace && !autoRoot.root;
+    applySessionAttributes(span3, sessionId, spanIsRoot, {
       parentSessionId,
       sessionFeatureName,
       sessionEntryPoint
     });
-    applyEndUserAttributes(span3, endUserId, endUserMetadata, isRootTrace);
+    applyEndUserAttributes(span3, endUserId, endUserMetadata, spanIsRoot);
     if (input !== void 0 && input !== null) {
       const capturedInput = captureMedia(
         span3,
@@ -4665,106 +4872,34 @@ async function trace(options, fn) {
   };
   const parentContext = shouldCreateRootTrace ? ROOT_CONTEXT3 : getNeatlogsParentContext(ctx);
   const startAttributes = kind ? { "openinference.span.kind": kind } : void 0;
-  const span2 = tracer.startSpan(name, startAttributes ? { attributes: startAttributes } : {}, parentContext);
+  const autoRoot = isRootTrace ? maybeOpenAutoRoot(tracer, String(kind ?? "CHAIN"), parentContext) : { root: void 0, ctx: parentContext };
+  if (autoRoot.root) {
+    applySessionAttributes(autoRoot.root, sessionId, true, {
+      parentSessionId,
+      sessionFeatureName,
+      sessionEntryPoint
+    });
+    applyEndUserAttributes(autoRoot.root, endUserId, endUserMetadata, true);
+  }
+  const span2 = bindSpanToAutoRoot(
+    tracer.startSpan(
+      name,
+      startAttributes ? { attributes: startAttributes } : {},
+      autoRoot.ctx
+    ),
+    autoRoot.root
+  );
   if (shouldCreateRootTrace) {
     logger6.debug(`[trace] Creating NEW root trace '${name}' (sessionId=${sessionId})`);
   } else {
     logger6.debug(`[trace] Creating child span '${name}'`);
   }
-  return withNeatlogsSpan(span2, () => spanCallback(span2), ctx);
-}
-
-// src/span-kinds/constants.ts
-var VECTOR_DB_SYSTEMS = /* @__PURE__ */ new Set([
-  "chroma",
-  "chromadb",
-  "pinecone",
-  "qdrant",
-  "milvus",
-  "marqo",
-  "weaviate",
-  "lancedb",
-  "pgvector",
-  "elasticsearch"
-]);
-var RETRIEVAL_OPS = [
-  "query",
-  "search",
-  "get",
-  "fetch",
-  "find",
-  "retrieve",
-  "scroll",
-  "peek",
-  "discover",
-  "recommend",
-  "aggregate",
-  "hybrid_search",
-  "select"
-];
-var VECTOR_DB_NAMES = [
-  "chroma",
-  "pinecone",
-  "weaviate",
-  "qdrant",
-  "milvus",
-  "lancedb",
-  "marqo"
-];
-
-// src/span-kinds/mapping.ts
-var VALID_SPAN_KINDS = /* @__PURE__ */ new Set([
-  "WORKFLOW",
-  "AGENT",
-  "CHAIN",
-  "TOOL",
-  "RETRIEVER",
-  "EMBEDDING",
-  "MCP_TOOL",
-  "GUARDRAIL"
-]);
-var ALL_SPAN_KINDS = /* @__PURE__ */ new Set([
-  ...VALID_SPAN_KINDS,
-  "LLM",
-  "RERANKER",
-  "EVALUATOR",
-  "VECTOR_STORE"
-]);
-function inferSpanKindFromName(spanName) {
-  const nameLower = spanName.toLowerCase();
-  if (["openai", "anthropic", "cohere", "bedrock", "chat", "completion", "llm", "gemini", "google_genai"].some(
-    (kw) => nameLower.includes(kw)
-  )) {
-    return "LLM";
-  }
-  if (nameLower.includes("embed")) {
-    return "EMBEDDING";
-  }
-  if (VECTOR_DB_NAMES.some((db) => nameLower.includes(db))) {
-    if (RETRIEVAL_OPS.some((kw) => nameLower.includes(kw))) {
-      return "RETRIEVER";
-    }
-    return "VECTOR_STORE";
-  }
-  if (["retriev", "search", "query"].some((kw) => nameLower.includes(kw))) {
-    return "RETRIEVER";
-  }
-  if (nameLower.includes("rerank")) {
-    return "RERANKER";
-  }
-  if (nameLower.includes("agent")) {
-    return "AGENT";
-  }
-  if (["tool", "function"].some((kw) => nameLower.includes(kw))) {
-    return "TOOL";
-  }
-  if (["guardrail", "validate", "moderate", "safety"].some((kw) => nameLower.includes(kw))) {
-    return "GUARDRAIL";
-  }
-  if (["evaluat", "score", "metric"].some((kw) => nameLower.includes(kw))) {
-    return "EVALUATOR";
-  }
-  return "CHAIN";
+  return withNeatlogsSpan(
+    span2,
+    () => spanCallback(span2),
+    autoRoot.ctx,
+    autoRoot.root
+  );
 }
 
 // src/decorators/orchestration.ts
@@ -5284,6 +5419,7 @@ var neatlogs_telemetry_schema_default = {
         "VECTOR_STORE",
         "MEMORY",
         "GUARDRAIL",
+        "EVALUATOR",
         "LOG",
         "HTTP",
         "UNKNOWN"
@@ -6712,6 +6848,7 @@ var neatlogs_telemetry_schema_default = {
             "AGENT",
             "CHAIN",
             "TASK",
+            "EVALUATOR",
             "HTTP",
             "UNKNOWN"
           ]
@@ -6875,6 +7012,7 @@ var neatlogs_telemetry_schema_default = {
           "neatlogs.vector_store.*",
           "neatlogs.memory.*",
           "neatlogs.guardrail.*",
+          "neatlogs.evaluator.*",
           "neatlogs.mcp.*",
           "neatlogs.code.*"
         ],
@@ -6958,7 +7096,7 @@ var TELEMETRY_CONFLICT_PRECEDENCE = Object.freeze(
 );
 
 // src/version.ts
-var __version__ = "1.1.19";
+var __version__ = "1.1.21";
 
 // src/init.ts
 import * as path2 from "path";
@@ -6980,16 +7118,16 @@ import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
 import * as fs from "fs";
 import * as path from "path";
 import { performance } from "perf_hooks";
-import { ROOT_CONTEXT as ROOT_CONTEXT4, trace as otelTrace3, TraceFlags, SpanStatusCode as SpanStatusCode4 } from "@opentelemetry/api";
+import { ROOT_CONTEXT as ROOT_CONTEXT4, trace as otelTrace4, TraceFlags, SpanStatusCode as SpanStatusCode4 } from "@opentelemetry/api";
 
 // src/core/instrumentation-scope-parser.ts
 var SCOPE_PATTERNS = {
   // Neatlogs custom instrumentations
   "@neatlogs/instrumentation-google-genai": { provider: "google", framework: "google_genai" },
   "@neatlogs/instrumentation-mastra": { framework: "mastra" },
-  "@neatlogs/instrumentation-ai-sdk": { framework: "ai_sdk" },
+  "@neatlogs/instrumentation-ai-sdk": { framework: "vercel_ai_sdk" },
   // Vercel AI SDK native scope (the `ai` package emits this directly)
-  ai: { framework: "ai_sdk" },
+  ai: { framework: "vercel_ai_sdk" },
   // OpenInference instrumentations (npm @arizeai scope names)
   "@arizeai/openinference-instrumentation-openai": { provider: "openai", framework: "openai" },
   "@arizeai/openinference-instrumentation-anthropic": { provider: "anthropic", framework: "anthropic" },
@@ -7078,7 +7216,7 @@ function parseInstrumentationScope(scopeName) {
   } else if (scopeLower.includes("dspy")) {
     result.framework = "dspy";
   } else if (scopeLower.includes("vercel-ai") || scopeLower.includes("ai-sdk")) {
-    result.framework = "ai_sdk";
+    result.framework = "vercel_ai_sdk";
   }
   if (scopeLower.includes("openai")) {
     result.provider = "openai";
@@ -8967,6 +9105,46 @@ function addVerificationMarkerResourceAttribute(attributes) {
   if (marker) attributes[VERIFICATION_MARKER_KEY] = marker;
 }
 
+// src/core/http-span.ts
+import { SpanKind } from "@opentelemetry/api";
+var HTTP_SCOPE_PREFIXES = [
+  "@opentelemetry/instrumentation-http",
+  "@opentelemetry/instrumentation-fetch",
+  "@opentelemetry/instrumentation-undici"
+];
+var HTTP_ATTRIBUTE_KEYS = [
+  "http.method",
+  "http.request.method",
+  "http.url",
+  "http.route",
+  "url.full"
+];
+var SEMANTIC_AI_KINDS = /* @__PURE__ */ new Set([
+  "WORKFLOW",
+  "AGENT",
+  "CHAIN",
+  "TOOL",
+  "RETRIEVER",
+  "EMBEDDING",
+  "GUARDRAIL",
+  "LLM",
+  "RERANKER",
+  "VECTOR_STORE",
+  "TASK",
+  "EVALUATOR",
+  "LOG",
+  "MEMORY",
+  "MCP_TOOL"
+]);
+function isHttpSpan(span2, attributes = span2.attributes ?? {}) {
+  const resolvedKind = resolveExplicitSpanKind(attributes).toUpperCase();
+  if (resolvedKind === "HTTP") return true;
+  if (SEMANTIC_AI_KINDS.has(resolvedKind)) return false;
+  const scopeName = span2.instrumentationLibrary.name ?? "";
+  if (HTTP_SCOPE_PREFIXES.some((prefix) => scopeName.startsWith(prefix))) return true;
+  return span2.kind === SpanKind.CLIENT && HTTP_ATTRIBUTE_KEYS.some((key) => key in attributes);
+}
+
 // src/core/span-processor.ts
 var logger11 = getLogger();
 function resolveLogFilePath(configuredPath) {
@@ -9238,6 +9416,7 @@ var NeatlogsSpanProcessor = class {
   onEnd(span2) {
     this._activeSpans.delete(span2.spanContext().spanId);
     if (this._closed) return;
+    if (isHttpSpan(span2)) return;
     if (span2.name === "neatlogs.trace.complete") {
       const markerData = spanToDict(span2, { includeScope: true });
       markerData.resource = { attributes: markerData.resource };
@@ -9397,6 +9576,7 @@ var NeatlogsSpanProcessor = class {
       const maskResult = scheduleMask(span2, spanData, this.mask ?? null);
       const pending = maskResult.then((maskedSpanData) => {
         if (maskedSpanData === null) return;
+        if (isHttpSpan(span2, maskedSpanData.attributes ?? {})) return;
         if (this._processedLogStream && !this._processedLogStream.destroyed) {
           try {
             this._processedLogStream.write(JSON.stringify(maskedSpanData) + "\n");
@@ -9495,8 +9675,8 @@ var NeatlogsSpanProcessor = class {
         isRemote: false,
         traceFlags: TraceFlags.SAMPLED
       };
-      const wrappedSpan = otelTrace3.wrapSpanContext(spanCtx);
-      const ctx = otelTrace3.setSpan(ROOT_CONTEXT4, wrappedSpan);
+      const wrappedSpan = otelTrace4.wrapSpanContext(spanCtx);
+      const ctx = otelTrace4.setSpan(ROOT_CONTEXT4, wrappedSpan);
       const marker = markerTracer.startSpan("neatlogs.trace.complete", void 0, ctx);
       marker.setAttribute("neatlogs.trace.complete", true);
       marker.setAttribute("neatlogs.internal", true);
@@ -9665,7 +9845,8 @@ var CompletionMarkerSpanProcessor = class {
   onStart(_span, _parentContext) {
   }
   onEnd(span2) {
-    if (this.closed || span2.name === "neatlogs.trace.complete" || span2.parentSpanId) return;
+    if (this.closed || span2.name === "neatlogs.trace.complete" || span2.parentSpanId || isHttpSpan(span2))
+      return;
     if (!this.source.ownsSpan(span2)) return;
     const task = this.source.whenMaskComplete(span2).then((eligible) => {
       if (!eligible || this.closed) return;
@@ -9805,6 +9986,10 @@ var FilteringExporter = class {
   _onPrepared;
   export(spans, resultCallback) {
     void mapWithConcurrency(spans, MEDIA_RESOLUTION_CONCURRENCY, async (span2) => {
+      if (isHttpSpan(span2)) {
+        discardPendingMedia(span2);
+        return { span: null, mediaReady: true };
+      }
       if (span2.instrumentationLibrary.name === "next.js") {
         discardPendingMedia(span2);
         this.diagnostics?.recordFrameworkSpanDrop();
@@ -9825,6 +10010,11 @@ var FilteringExporter = class {
         ...masked.attributes && typeof masked.attributes === "object" ? masked.attributes : {}
       };
       const maskedData = { ...masked, attributes };
+      const maskedSpan = maskedReadableSpan(span2, maskedData);
+      if (isHttpSpan(maskedSpan)) {
+        discardPendingMedia(span2);
+        return { span: null, mediaReady: true };
+      }
       captureMediaInSnapshot(
         span2,
         maskedData,
@@ -11132,18 +11322,6 @@ function closeSharedClient() {
 function _resetMastraCache() {
 }
 
-// src/errors.ts
-var NeatlogsConfigurationError = class extends TypeError {
-  code;
-  option;
-  constructor(code, option, message) {
-    super(message);
-    this.name = "NeatlogsConfigurationError";
-    this.code = code;
-    this.option = option;
-  }
-};
-
 // src/core/deadline.ts
 async function runByDeadline(operation, deadlineMs) {
   const remaining = Math.max(0, deadlineMs - Date.now());
@@ -11244,6 +11422,24 @@ var INIT_OPTION_KEYS = /* @__PURE__ */ new Set([
   "piiSpanTypes",
   "uploadAuthority"
 ]);
+function resolveInitEndpoint(endpoint) {
+  const explicit = (endpoint ?? "").trim();
+  if (explicit) return explicit;
+  const fromEnv = (process.env.NEATLOGS_ENDPOINT ?? "").trim();
+  return fromEnv || DEFAULT_INGEST_ENDPOINT;
+}
+function resolveIngestBaseUrl(endpoint) {
+  const parsed = new URL(endpoint.trim());
+  const path3 = parsed.pathname.replace(/\/+$/, "");
+  if (path3 !== "" && path3 !== "/v1/traces") {
+    throw new NeatlogsConfigurationError(
+      "INVALID_ENDPOINT",
+      "endpoint",
+      "endpoint must be a base URL or an OTLP traces URL ending in /v1/traces."
+    );
+  }
+  return parsed.origin;
+}
 function validateInitOptions(options) {
   const raw = options;
   if (Object.prototype.hasOwnProperty.call(raw, "instrumentations")) {
@@ -11327,8 +11523,13 @@ function stableValue(value, ancestors = /* @__PURE__ */ new WeakSet(), location
     ancestors.delete(value);
   }
 }
+function resolveApiKey(apiKey) {
+  const explicit = (apiKey ?? "").trim();
+  if (explicit) return explicit;
+  return (process.env.NEATLOGS_API_KEY ?? "").trim();
+}
 function initIdentity(options) {
-  const apiKey = (options.apiKey ?? process.env.NEATLOGS_API_KEY ?? "").trim();
+  const apiKey = resolveApiKey(options.apiKey);
   const apiKeyDigest = createHash4("sha256").update(apiKey).digest("hex");
   const serialized = stableValue({
     apiKeyDigest,
@@ -11348,7 +11549,7 @@ function initIdentity(options) {
     captureLogs: options.captureLogs ?? false,
     pii: options.pii ?? null,
     version: options.version ?? null,
-    endpoint: options.endpoint ?? DEFAULT_INGEST_ENDPOINT,
+    endpoint: resolveInitEndpoint(options.endpoint),
     batchSize: options.batchSize ?? 100,
     flushInterval: options.flushInterval ?? 5,
     piiEnabled: options.piiEnabled ?? null,
@@ -11428,12 +11629,7 @@ async function _performInit(options) {
     );
   }
   _deliveryDiagnostics = new DeliveryDiagnostics();
-  let resolvedKey;
-  if (options.apiKey && options.apiKey.trim()) {
-    resolvedKey = options.apiKey.trim();
-  } else {
-    resolvedKey = (process.env.NEATLOGS_API_KEY ?? "").trim();
-  }
+  let resolvedKey = resolveApiKey(options.apiKey);
   let disableExportResolved = !!options.disableExport || ["true", "1", "yes"].includes(
     (process.env.NEATLOGS_DISABLE_EXPORT ?? "").toLowerCase()
   );
@@ -11454,8 +11650,8 @@ async function _performInit(options) {
   }
   _debugMode2 = options.debug ?? false;
   const resolvedWorkflowName = _resolveWorkflowName(options.workflowName);
-  const endpoint = options.endpoint ?? DEFAULT_INGEST_ENDPOINT;
-  const baseUrl = new URL(endpoint).origin;
+  const endpoint = resolveInitEndpoint(options.endpoint);
+  const baseUrl = resolveIngestBaseUrl(endpoint);
   const uploadAuthority = disableExportResolved ? new DisabledUploadAuthority("export_disabled") : resolveUploadAuthority(
     options.uploadAuthority,
     process.env.NEATLOGS_UPLOADS_ENABLED,
@@ -12175,6 +12371,36 @@ var INGESTION_STAGES = /* @__PURE__ */ new Set([
 ]);
 var INGESTION_STATES = /* @__PURE__ */ new Set(["processing", "failed", "succeeded"]);
 var SAFE_FAILURE_CODE = /^[A-Z0-9_]{1,64}$/;
+var PROBE_FAILURE = {
+  AUTH_FAILED: {
+    remediationCode: "CHECK_INGEST_CREDENTIAL",
+    message: "The project key was rejected by the existing trace API"
+  },
+  BACKEND_PROBE_UNAVAILABLE: {
+    remediationCode: "CHECK_TRACE_ENDPOINT",
+    message: "The existing trace ingestion or read path is unavailable"
+  },
+  TRACE_READBACK_TIMEOUT: {
+    remediationCode: "WAIT_FOR_TRACE",
+    message: "Timed out waiting for the exact Doctor trace"
+  },
+  INGESTION_PIPELINE_FAILED: {
+    remediationCode: "CONTACT_SUPPORT",
+    message: "Trace ingestion reported a terminal pipeline failure"
+  },
+  BACKEND_HTTP_ERROR: {
+    remediationCode: "CHECK_TRACE_ENDPOINT",
+    message: "The existing trace read path returned an unexpected HTTP status"
+  },
+  BACKEND_CONNECTION_FAILED: {
+    remediationCode: "CHECK_TRACE_ENDPOINT",
+    message: "Could not connect to the existing trace read path"
+  },
+  TRACE_READBACK_INVALID: {
+    remediationCode: "CONTACT_SUPPORT",
+    message: "Trace read-back returned an invalid response"
+  }
+};
 var ProbeReadError = class extends Error {
   constructor(reasonCode, message, details) {
     super(message);
@@ -12294,7 +12520,7 @@ function validateLocalFixture(traceId) {
     check("controlled_fixture_bounds", stats.droppedSpans === 0, "CONTROLLED_BOUNDS_VALID", "CONTROLLED_CAPTURE_TRUNCATED", "REDUCE_DIAGNOSTIC_CAPTURE", "Doctor stayed inside the bounded capture budget")
   ];
 }
-async function withTimeout(operation, timeoutMs, onTimeout) {
+async function withTimeout(operation, timeoutMs, onTimeout, timeoutReason = "BACKEND_PROBE_UNAVAILABLE") {
   let timer;
   try {
     return await Promise.race([
@@ -12302,7 +12528,7 @@ async function withTimeout(operation, timeoutMs, onTimeout) {
       new Promise((_resolve, reject) => {
         timer = setTimeout(() => {
           onTimeout?.();
-          reject(new ProbeReadError("BACKEND_PROBE_UNAVAILABLE", "Doctor operation timed out"));
+          reject(new ProbeReadError(timeoutReason, "Doctor operation timed out"));
         }, Math.max(1, timeoutMs));
       })
     ]);
@@ -12490,12 +12716,13 @@ function failedProbeResult(local, reasonCode, details) {
   };
 }
 function failedProbeTransportCheck(reasonCode, details) {
+  const failure2 = PROBE_FAILURE[reasonCode];
   return {
     name: "probe_transport",
     status: "fail",
     reason_code: reasonCode,
-    remediation_code: reasonCode === "AUTH_FAILED" ? "CHECK_INGEST_CREDENTIAL" : "CHECK_TRACE_ENDPOINT",
-    message: reasonCode === "AUTH_FAILED" ? "The project key was rejected by the existing trace API" : "The existing trace ingestion or read path is unavailable",
+    remediation_code: failure2.remediationCode,
+    message: failure2.message,
     ...details ? { details } : {}
   };
 }
@@ -12573,16 +12800,23 @@ function human(result) {
   if (result.note) lines.push(result.note);
   return lines.join("\n");
 }
+function readbackTimeoutReason(remainingMs, requestTimeoutMs) {
+  return remainingMs <= requestTimeoutMs ? "TRACE_READBACK_TIMEOUT" : "BACKEND_CONNECTION_FAILED";
+}
+function responseBodyFailureReason(status, remainingMs, requestTimeoutMs) {
+  return status === 409 || status >= 200 && status < 300 && status !== 202 ? "TRACE_READBACK_INVALID" : readbackTimeoutReason(remainingMs, requestTimeoutMs);
+}
 async function boundedFetch(io, input, initOptions, deadline) {
   const remaining = deadline - Date.now();
   if (remaining <= 0) {
-    throw new ProbeReadError("BACKEND_PROBE_UNAVAILABLE", "Doctor probe deadline expired");
+    throw new ProbeReadError("TRACE_READBACK_TIMEOUT", "Doctor probe deadline expired");
   }
   const controller = new AbortController();
   return withTimeout(
     () => io.fetch(input, { ...initOptions, signal: controller.signal }),
     Math.min(io.requestTimeoutMs, remaining),
-    () => controller.abort()
+    () => controller.abort(),
+    readbackTimeoutReason(remaining, io.requestTimeoutMs)
   );
 }
 async function discardResponseBody(response, reader) {
@@ -12604,7 +12838,7 @@ async function boundedJson2(response, io, deadline) {
   const remaining = deadline - Date.now();
   if (remaining <= 0) {
     await discardResponseBody(response);
-    throw new ProbeReadError("BACKEND_PROBE_UNAVAILABLE", "Doctor probe deadline expired");
+    throw new ProbeReadError("TRACE_READBACK_TIMEOUT", "Doctor probe deadline expired");
   }
   const contentLength = Number(response.headers.get("content-length"));
   if (Number.isFinite(contentLength) && contentLength > MAX_READBACK_BYTES) {
@@ -12639,9 +12873,17 @@ async function boundedJson2(response, io, deadline) {
     }
   }, Math.min(io.requestTimeoutMs, remaining), () => {
     void discardResponseBody(response, reader);
-  }).catch(async () => {
+  }, responseBodyFailureReason(
+    response.status,
+    remaining,
+    io.requestTimeoutMs
+  )).catch(async (error) => {
     await discardResponseBody(response, reader);
-    return null;
+    if (error instanceof ProbeReadError) throw error;
+    throw new ProbeReadError(
+      "BACKEND_CONNECTION_FAILED",
+      "Trace read-back response could not be read"
+    );
   });
 }
 function usage() {
@@ -12746,10 +12988,11 @@ async function runDoctorCli(argv, overrides = {}) {
             "x-neatlogs-doctor": DOCTOR_MARKER_VERSION
           }
         }, deadline);
-      } catch {
+      } catch (error) {
+        if (error instanceof ProbeReadError) throw error;
         throw new ProbeReadError(
-          "BACKEND_PROBE_UNAVAILABLE",
-          "The existing trace read path is unavailable",
+          "BACKEND_CONNECTION_FAILED",
+          "Could not connect to the existing trace read path",
           lastDiagnostics
         );
       }
@@ -12757,7 +13000,7 @@ async function runDoctorCli(argv, overrides = {}) {
         const value = await boundedJson2(response, io, deadline);
         if (!value || typeof value !== "object") {
           throw new ProbeReadError(
-            "BACKEND_PROBE_UNAVAILABLE",
+            "TRACE_READBACK_INVALID",
             "Trace read-back returned an invalid response"
           );
         }
@@ -12770,12 +13013,23 @@ async function runDoctorCli(argv, overrides = {}) {
         throw new ProbeReadError("AUTH_FAILED", "Trace read-back rejected the project key");
       }
       if ([202, 404, 409].includes(response.status)) {
-        const value = await boundedJson2(response, io, deadline).catch(() => null);
+        const value = await boundedJson2(response, io, deadline);
         const currentDiagnostics = ingestionDiagnosticDetails(value);
         if (currentDiagnostics) lastDiagnostics = currentDiagnostics;
         if (response.status === 409) {
+          const terminalValue = objectValue(value);
+          const isDlq = terminalValue.finalizationStatus === "dlq";
+          const hasDiagnostics = Object.hasOwn(terminalValue, "ingestionDiagnostics");
+          const validDlq = typeof terminalValue.error === "string" && (terminalValue.message === void 0 || typeof terminalValue.message === "string") && (!hasDiagnostics || currentDiagnostics !== void 0);
+          const validReceipt = currentDiagnostics?.ingestion_state === "failed";
+          if (isDlq ? !validDlq : !validReceipt) {
+            throw new ProbeReadError(
+              "TRACE_READBACK_INVALID",
+              "Trace read-back returned an invalid terminal receipt"
+            );
+          }
           throw new ProbeReadError(
-            "BACKEND_PROBE_UNAVAILABLE",
+            "INGESTION_PIPELINE_FAILED",
             "Trace ingestion reported a terminal failure",
             currentDiagnostics
           );
@@ -12783,7 +13037,7 @@ async function runDoctorCli(argv, overrides = {}) {
       } else {
         await discardResponseBody(response);
         throw new ProbeReadError(
-          "BACKEND_PROBE_UNAVAILABLE",
+          "BACKEND_HTTP_ERROR",
           `Trace read-back failed with HTTP ${response.status}`,
           response.status >= 500 ? lastDiagnostics : void 0
         );
@@ -12793,7 +13047,7 @@ async function runDoctorCli(argv, overrides = {}) {
     }
     if (!persisted) {
       throw new ProbeReadError(
-        "BACKEND_PROBE_UNAVAILABLE",
+        "TRACE_READBACK_TIMEOUT",
         "Timed out waiting for the exact Doctor trace",
         lastDiagnostics
       );
@@ -12802,7 +13056,7 @@ async function runDoctorCli(argv, overrides = {}) {
     io.stdout(json ? JSON.stringify(result, null, 2) : human(result));
     return result.status === "pass" ? 0 : 3;
   } catch (error) {
-    const reason = error instanceof ProbeReadError && error.reasonCode === "AUTH_FAILED" ? "AUTH_FAILED" : "BACKEND_PROBE_UNAVAILABLE";
+    const reason = error instanceof ProbeReadError ? error.reasonCode : "BACKEND_PROBE_UNAVAILABLE";
     const result = local ? failedProbeResult(
       local,
       reason,