neatlogs 1.1.19 → 1.1.21

package/dist/cli.cjs

@@ -24,7 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/doctor-cli.ts
-var import_api9 = require("@opentelemetry/api");
+var import_api11 = require("@opentelemetry/api");
 
 // src/core/doctor-capture.ts
 var import_api = require("@opentelemetry/api");
@@ -81,6 +81,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#",
@@ -1258,27 +1362,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;
@@ -1851,7 +1939,7 @@ function clearDoctorCapture() {
 }
 
 // src/core/context.ts
-var import_api4 = require("@opentelemetry/api");
+var import_api5 = require("@opentelemetry/api");
 
 // src/prompt/template.ts
 var import_node_async_hooks = require("async_hooks");
@@ -2190,11 +2278,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 = import_api2.trace.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);
 }
@@ -3926,8 +4014,84 @@ function discardPendingMediaOwner(owner) {
   pendingMediaOwners.delete(owner ?? defaultPendingMediaOwner);
 }
 
-// src/decorators/base.ts
+// src/core/auto-root.ts
 var import_api3 = require("@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: import_api3.trace.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
+var import_api4 = require("@opentelemetry/api");
 var logger5 = getLogger();
 var TRACER_NAME = "neatlogs";
 var STREAM_CAPTURE_TRUNCATED = "[TRUNCATED_STREAM_OUTPUT]";
@@ -3999,8 +4163,29 @@ function decorateSpan(opts, fn) {
   const wrapped = (...args) => {
     const tracer = getNeatlogsTracer(TRACER_NAME);
     const isRoot = isRootSpan();
-    const parentContext = isRoot ? import_api3.ROOT_CONTEXT : getNeatlogsParentContext();
-    const span2 = tracer.startSpan(spanName, {}, parentContext);
+    const parentContext = isRoot ? import_api4.ROOT_CONTEXT : getNeatlogsParentContext();
+    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;
@@ -4040,7 +4225,7 @@ function decorateSpan(opts, fn) {
         if (finished) return;
         finished = true;
         captureResult(result);
-        span2.setStatus({ code: import_api3.SpanStatusCode.OK });
+        span2.setStatus({ code: import_api4.SpanStatusCode.OK });
         span2.end();
       };
       const setStreamCounts = () => {
@@ -4079,12 +4264,12 @@ function decorateSpan(opts, fn) {
             setStreamCounts();
             captureResult(streamCaptureValue());
           }
-          span2.setStatus({ code: import_api3.SpanStatusCode.UNSET });
+          span2.setStatus({ code: import_api4.SpanStatusCode.UNSET });
           span2.end();
           return;
         }
         span2.setStatus({
-          code: import_api3.SpanStatusCode.ERROR,
+          code: import_api4.SpanStatusCode.ERROR,
           message: error?.message ?? String(error)
         });
         span2.recordException(
@@ -4149,7 +4334,7 @@ function decorateSpan(opts, fn) {
         finished = true;
         span2.setAttribute("neatlogs.stream.cancelled", true);
         captureResult(streamCaptureValue());
-        span2.setStatus({ code: import_api3.SpanStatusCode.UNSET });
+        span2.setStatus({ code: import_api4.SpanStatusCode.UNSET });
         span2.end();
       };
       const wrapAsyncIterator = (iterator) => {
@@ -4369,7 +4554,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
@@ -4378,7 +4564,7 @@ function decorateSpan(opts, fn) {
           span2,
           opts.endUserId,
           opts.endUserMetadata,
-          isRoot
+          spanIsRoot
         );
         if (captureInput && args.length > 0) {
           try {
@@ -4418,7 +4604,7 @@ function decorateSpan(opts, fn) {
         finishError(error);
         throw error;
       }
-    });
+    }, autoRoot.ctx, autoRoot.root);
   };
   Object.defineProperty(wrapped, "name", {
     value: spanName,
@@ -4447,11 +4633,14 @@ var _sessionConfig = {};
 function _setSessionConfig(config) {
   _sessionConfig = config;
 }
-var PROMPT_VARIABLES_KEY = (0, import_api4.createContextKey)("neatlogs.prompt_variables");
-var PROMPT_TEMPLATE_KEY = (0, import_api4.createContextKey)("neatlogs.prompt_template");
-var PROMPT_VERSION_KEY = (0, import_api4.createContextKey)("neatlogs.prompt_version");
-var USER_PROMPT_TEMPLATE_KEY = (0, import_api4.createContextKey)("neatlogs.user_prompt_template");
-var USER_PROMPT_VARIABLES_KEY = (0, import_api4.createContextKey)("neatlogs.user_prompt_variables");
+function getSessionConfig() {
+  return { ..._sessionConfig };
+}
+var PROMPT_VARIABLES_KEY = (0, import_api5.createContextKey)("neatlogs.prompt_variables");
+var PROMPT_TEMPLATE_KEY = (0, import_api5.createContextKey)("neatlogs.prompt_template");
+var PROMPT_VERSION_KEY = (0, import_api5.createContextKey)("neatlogs.prompt_version");
+var USER_PROMPT_TEMPLATE_KEY = (0, import_api5.createContextKey)("neatlogs.user_prompt_template");
+var USER_PROMPT_VARIABLES_KEY = (0, import_api5.createContextKey)("neatlogs.user_prompt_variables");
 var KNOWN_OPTION_KEYS = /* @__PURE__ */ new Set([
   "name",
   "kind",
@@ -4470,6 +4659,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);
@@ -4540,6 +4743,7 @@ async function trace(options, fn) {
     attributes: explicitAttributes,
     ...extraOptions
   } = options;
+  assertNoHttpSpanKind(kind, explicitAttributes);
   const sessionId = sessionIdOption ?? currentSessionId();
   const currentSpan = getActiveNeatlogsSpan();
   const rootSpan = getNeatlogsRootSpan();
@@ -4584,7 +4788,7 @@ async function trace(options, fn) {
   }
   let ctx = getNeatlogsActiveContext();
   if (shouldFallbackToRoot) {
-    ctx = import_api4.trace.setSpan(ctx, rootSpan);
+    ctx = import_api5.trace.setSpan(ctx, rootSpan);
   }
   const variablesJson = promptVariables ? JSON.stringify(promptVariables) : void 0;
   const userVariablesJson = userPromptVariables ? JSON.stringify(userPromptVariables) : void 0;
@@ -4618,12 +4822,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,
@@ -4656,7 +4861,7 @@ async function trace(options, fn) {
       return result;
     } catch (error) {
       span3.setStatus({
-        code: import_api4.SpanStatusCode.ERROR,
+        code: import_api5.SpanStatusCode.ERROR,
         message: error instanceof Error ? error.message : String(error)
       });
       span3.recordException(
@@ -4673,108 +4878,36 @@ async function trace(options, fn) {
       span3.end();
     }
   };
-  const parentContext = shouldCreateRootTrace ? import_api4.ROOT_CONTEXT : getNeatlogsParentContext(ctx);
+  const parentContext = shouldCreateRootTrace ? import_api5.ROOT_CONTEXT : 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
@@ -5294,6 +5427,7 @@ var neatlogs_telemetry_schema_default = {
         "VECTOR_STORE",
         "MEMORY",
         "GUARDRAIL",
+        "EVALUATOR",
         "LOG",
         "HTTP",
         "UNKNOWN"
@@ -6722,6 +6856,7 @@ var neatlogs_telemetry_schema_default = {
             "AGENT",
             "CHAIN",
             "TASK",
+            "EVALUATOR",
             "HTTP",
             "UNKNOWN"
           ]
@@ -6885,6 +7020,7 @@ var neatlogs_telemetry_schema_default = {
           "neatlogs.vector_store.*",
           "neatlogs.memory.*",
           "neatlogs.guardrail.*",
+          "neatlogs.evaluator.*",
           "neatlogs.mcp.*",
           "neatlogs.code.*"
         ],
@@ -6968,7 +7104,7 @@ var TELEMETRY_CONFLICT_PRECEDENCE = Object.freeze(
 );
 
 // src/version.ts
-var __version__ = "1.1.19";
+var __version__ = "1.1.21";
 
 // src/init.ts
 var path2 = __toESM(require("path"));
@@ -6987,16 +7123,16 @@ var import_exporter_logs_otlp_proto = require("@opentelemetry/exporter-logs-otlp
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 var import_node_perf_hooks = require("perf_hooks");
-var import_api5 = require("@opentelemetry/api");
+var import_api7 = require("@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" },
@@ -7085,7 +7221,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";
@@ -8974,6 +9110,46 @@ function addVerificationMarkerResourceAttribute(attributes) {
   if (marker) attributes[VERIFICATION_MARKER_KEY] = marker;
 }
 
+// src/core/http-span.ts
+var import_api6 = require("@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 === import_api6.SpanKind.CLIENT && HTTP_ATTRIBUTE_KEYS.some((key) => key in attributes);
+}
+
 // src/core/span-processor.ts
 var logger11 = getLogger();
 function resolveLogFilePath(configuredPath) {
@@ -9245,6 +9421,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 };
@@ -9361,7 +9538,7 @@ var NeatlogsSpanProcessor = class {
         attributes: unifiedAttrs,
         resource: { attributes: resourceAttrs },
         status: {
-          code: import_api5.SpanStatusCode[span2.status.code] ?? String(span2.status.code),
+          code: import_api7.SpanStatusCode[span2.status.code] ?? String(span2.status.code),
           description: span2.status.message ?? null
         },
         links: span2.links.map((link) => ({
@@ -9404,6 +9581,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");
@@ -9483,9 +9661,9 @@ var NeatlogsSpanProcessor = class {
   _markInterrupted(span2, cleanReason) {
     span2.setAttribute("neatlogs.trace.interrupted", true);
     span2.setAttribute("neatlogs.trace.termination.reason", cleanReason);
-    if (span2.status.code === import_api5.SpanStatusCode.UNSET) {
+    if (span2.status.code === import_api7.SpanStatusCode.UNSET) {
       span2.setStatus({
-        code: import_api5.SpanStatusCode.ERROR,
+        code: import_api7.SpanStatusCode.ERROR,
         message: `Interrupted during ${cleanReason}`
       });
     }
@@ -9500,10 +9678,10 @@ var NeatlogsSpanProcessor = class {
         traceId: rootSpan.spanContext().traceId,
         spanId: rootSpan.spanContext().spanId,
         isRemote: false,
-        traceFlags: import_api5.TraceFlags.SAMPLED
+        traceFlags: import_api7.TraceFlags.SAMPLED
       };
-      const wrappedSpan = import_api5.trace.wrapSpanContext(spanCtx);
-      const ctx = import_api5.trace.setSpan(import_api5.ROOT_CONTEXT, wrappedSpan);
+      const wrappedSpan = import_api7.trace.wrapSpanContext(spanCtx);
+      const ctx = import_api7.trace.setSpan(import_api7.ROOT_CONTEXT, wrappedSpan);
       const marker = markerTracer.startSpan("neatlogs.trace.complete", void 0, ctx);
       marker.setAttribute("neatlogs.trace.complete", true);
       marker.setAttribute("neatlogs.internal", true);
@@ -9672,7 +9850,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;
@@ -9709,7 +9888,7 @@ var CompletionMarkerSpanProcessor = class {
 };
 
 // src/core/filtering-exporter.ts
-var import_api6 = require("@opentelemetry/api");
+var import_api8 = require("@opentelemetry/api");
 var import_core = require("@opentelemetry/core");
 var import_resources = require("@opentelemetry/resources");
 var MEDIA_RESOLUTION_CONCURRENCY = 4;
@@ -9748,7 +9927,7 @@ function toAttributes(value) {
 function statusCode(value, fallback) {
   if (typeof value === "number") return value;
   if (typeof value === "string") {
-    const resolved = import_api6.SpanStatusCode[value];
+    const resolved = import_api8.SpanStatusCode[value];
     if (typeof resolved === "number") return resolved;
   }
   return fallback;
@@ -9812,6 +9991,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();
@@ -9832,6 +10015,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,
@@ -10299,7 +10487,7 @@ var DeliveryDiagnostics = class {
 };
 
 // src/core/observable-batch-processors.ts
-var import_api7 = require("@opentelemetry/api");
+var import_api9 = require("@opentelemetry/api");
 var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
 var import_sdk_logs = require("@opentelemetry/sdk-logs");
 var ObservableBatchSpanProcessor = class extends import_sdk_trace_base.BatchSpanProcessor {
@@ -10310,7 +10498,7 @@ var ObservableBatchSpanProcessor = class extends import_sdk_trace_base.BatchSpan
   diagnostics;
   onEnd(span2) {
     const state = this;
-    if ((span2.spanContext().traceFlags & import_api7.TraceFlags.SAMPLED) !== 0 && state._finishedSpans.length >= state._maxQueueSize) {
+    if ((span2.spanContext().traceFlags & import_api9.TraceFlags.SAMPLED) !== 0 && state._finishedSpans.length >= state._maxQueueSize) {
       discardPendingMedia(span2);
       this.diagnostics.recordQueueDrop("span");
     }
@@ -10344,7 +10532,7 @@ function _setOtelLogger(otelLogger, debug) {
 }
 
 // src/prompt/client.ts
-var import_api8 = require("@opentelemetry/api");
+var import_api10 = require("@opentelemetry/api");
 var import_core4 = require("@opentelemetry/core");
 var PromptClientError = class extends Error {
   constructor(message) {
@@ -11057,8 +11245,8 @@ var PromptClient = class _PromptClient {
     let contextResult;
     try {
       try {
-        const suppressedContext = (0, import_core4.suppressTracing)(import_api8.context.active());
-        contextResult = import_api8.context.with(suppressedContext, startTransport);
+        const suppressedContext = (0, import_core4.suppressTracing)(import_api10.context.active());
+        contextResult = import_api10.context.with(suppressedContext, startTransport);
       } catch {
       }
       if (contextResult && contextResult !== transportPromise) {
@@ -11135,18 +11323,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());
@@ -11247,6 +11423,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")) {
@@ -11330,8 +11524,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 = (0, import_node_crypto4.createHash)("sha256").update(apiKey).digest("hex");
   const serialized = stableValue({
     apiKeyDigest,
@@ -11351,7 +11550,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,
@@ -11431,12 +11630,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()
   );
@@ -11457,8 +11651,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,
@@ -12178,6 +12372,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);
@@ -12297,7 +12521,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([
@@ -12305,7 +12529,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));
       })
     ]);
@@ -12360,7 +12584,7 @@ async function localResult(env, options = {}) {
             markDoctorSpan("LLM");
             const output = { text: "generated diagnostic output" };
             llm.setAttribute("output.value", JSON.stringify(output));
-            llm.setStatus({ code: import_api9.SpanStatusCode.OK });
+            llm.setStatus({ code: import_api11.SpanStatusCode.OK });
             llm.end();
             return output;
           }
@@ -12379,7 +12603,7 @@ async function localResult(env, options = {}) {
       const output = await diagnosticTool({ value: 1 });
       const result2 = { result: output };
       setTraceOutput(result2);
-      root.setStatus({ code: import_api9.SpanStatusCode.OK });
+      root.setStatus({ code: import_api11.SpanStatusCode.OK });
       return result2;
     });
     let flushed = false;
@@ -12493,12 +12717,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 } : {}
   };
 }
@@ -12576,16 +12801,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) {
@@ -12607,7 +12839,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) {
@@ -12642,9 +12874,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() {
@@ -12749,10 +12989,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
         );
       }
@@ -12760,7 +13001,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"
           );
         }
@@ -12773,12 +13014,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
           );
@@ -12786,7 +13038,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
         );
@@ -12796,7 +13048,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
       );
@@ -12805,7 +13057,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,