@frontmcp/observability 1.9.2 → 1.9.4

package/esm/index.mjs

@@ -704,6 +704,13 @@ var RequestLogCollector = class {
     this.status = status;
     this.statusCode = statusCode;
   }
+  /**
+   * Set the HTTP status the request was answered with; one of 400 or more marks it failed.
+   */
+  setStatusCode(statusCode) {
+    this.statusCode = statusCode;
+    if (statusCode >= 400) this.status = "error";
+  }
   /**
    * Set error details.
    */
@@ -772,12 +779,17 @@ var RequestLogCollector = class {
   }
 };
 
+// libs/observability/src/request-log/request-log.hooks.ts
+import { isAnonymousSubject } from "@frontmcp/sdk";
+
 // libs/observability/src/plugin/observability.hooks.ts
 import {
   context as otelContext3,
-  SpanKind as SpanKind11,
+  SpanKind as SpanKind12,
+  SpanStatusCode as SpanStatusCode2,
   trace as trace3
 } from "@opentelemetry/api";
+import { FlowControl, InternalMcpError, toMcpError } from "@frontmcp/sdk";
 import { sha256Hex } from "@frontmcp/utils";
 
 // libs/observability/src/otel/otel.types.ts
@@ -977,8 +989,35 @@ function setFetchResponseStatus(span, statusCode) {
   span.setAttribute(HttpAttributes.STATUS_CODE, statusCode);
 }
 
-// libs/observability/src/otel/spans/http-server.span.ts
+// libs/observability/src/otel/spans/hook.span.ts
 import { SpanKind as SpanKind4 } from "@opentelemetry/api";
+function recordHookEvent(parentSpan, stage, owner) {
+  const attributes = {};
+  if (owner) {
+    attributes[FrontMcpAttributes.HOOK_OWNER] = owner;
+  }
+  parentSpan.addEvent(`hook.${stage}`, attributes);
+}
+function startHookSpan(tracer, options) {
+  const attributes = {
+    [FrontMcpAttributes.HOOK_STAGE]: options.stage
+  };
+  if (options.owner) {
+    attributes[FrontMcpAttributes.HOOK_OWNER] = options.owner;
+  }
+  if (options.flowName) {
+    attributes[FrontMcpAttributes.FLOW_NAME] = options.flowName;
+  }
+  return startSpan(tracer, {
+    name: `hook ${options.stage}`,
+    kind: SpanKind4.INTERNAL,
+    attributes,
+    parentContext: options.parentContext
+  });
+}
+
+// libs/observability/src/otel/spans/http-server.span.ts
+import { SpanKind as SpanKind5 } from "@opentelemetry/api";
 function startHttpServerSpan(tracer, options) {
   const attributes = {
     [HttpAttributes.METHOD]: options.method.toUpperCase(),
@@ -1001,7 +1040,7 @@ function startHttpServerSpan(tracer, options) {
   }
   return startSpan(tracer, {
     name: `${options.method.toUpperCase()} ${options.path}`,
-    kind: SpanKind4.SERVER,
+    kind: SpanKind5.SERVER,
     attributes,
     parentContext: options.parentContext
   });
@@ -1011,11 +1050,11 @@ function setHttpResponseStatus(span, statusCode) {
 }
 
 // libs/observability/src/otel/spans/prompt.span.ts
-import { SpanKind as SpanKind5 } from "@opentelemetry/api";
+import { SpanKind as SpanKind6 } from "@opentelemetry/api";
 function startPromptSpan(tracer, options) {
   return startSpan(tracer, {
     name: `prompt ${options.name}`,
-    kind: SpanKind5.INTERNAL,
+    kind: SpanKind6.INTERNAL,
     attributes: {
       [FrontMcpAttributes.PROMPT_NAME]: options.name,
       [McpAttributes.COMPONENT_TYPE]: "prompt",
@@ -1026,7 +1065,7 @@ function startPromptSpan(tracer, options) {
 }
 
 // libs/observability/src/otel/spans/resource.span.ts
-import { SpanKind as SpanKind6 } from "@opentelemetry/api";
+import { SpanKind as SpanKind7 } from "@opentelemetry/api";
 function startResourceSpan(tracer, options) {
   const attributes = {
     [FrontMcpAttributes.RESOURCE_URI]: options.uri,
@@ -1039,14 +1078,14 @@ function startResourceSpan(tracer, options) {
   }
   return startSpan(tracer, {
     name: `resource ${options.uri}`,
-    kind: SpanKind6.INTERNAL,
+    kind: SpanKind7.INTERNAL,
     attributes,
     parentContext: options.parentContext
   });
 }
 
 // libs/observability/src/otel/spans/rpc.span.ts
-import { SpanKind as SpanKind7 } from "@opentelemetry/api";
+import { SpanKind as SpanKind8 } from "@opentelemetry/api";
 function startRpcSpan(tracer, options) {
   const attributes = {
     [RpcAttributes.SYSTEM]: "mcp",
@@ -1070,14 +1109,14 @@ function startRpcSpan(tracer, options) {
   }
   return startSpan(tracer, {
     name: options.method,
-    kind: SpanKind7.SERVER,
+    kind: SpanKind8.SERVER,
     attributes,
     parentContext: options.parentContext
   });
 }
 
 // libs/observability/src/otel/spans/startup.span.ts
-import { SpanKind as SpanKind8 } from "@opentelemetry/api";
+import { SpanKind as SpanKind9 } from "@opentelemetry/api";
 function emitStartupReport(tracer, data) {
   const attributes = {
     [FrontMcpAttributes.STARTUP_TOOLS_COUNT]: data.toolsCount,
@@ -1091,14 +1130,14 @@ function emitStartupReport(tracer, data) {
   }
   const { span } = startSpan(tracer, {
     name: "frontmcp.startup",
-    kind: SpanKind8.INTERNAL,
+    kind: SpanKind9.INTERNAL,
     attributes
   });
   endSpanOk(span);
 }
 
 // libs/observability/src/otel/spans/tool.span.ts
-import { SpanKind as SpanKind9 } from "@opentelemetry/api";
+import { SpanKind as SpanKind10 } from "@opentelemetry/api";
 function startToolSpan(tracer, options) {
   const attributes = {
     [FrontMcpAttributes.TOOL_NAME]: options.name,
@@ -1116,14 +1155,14 @@ function startToolSpan(tracer, options) {
   }
   return startSpan(tracer, {
     name: `tool ${options.name}`,
-    kind: SpanKind9.INTERNAL,
+    kind: SpanKind10.INTERNAL,
     attributes,
     parentContext: options.parentContext
   });
 }
 
 // libs/observability/src/otel/spans/transport.span.ts
-import { SpanKind as SpanKind10 } from "@opentelemetry/api";
+import { SpanKind as SpanKind11 } from "@opentelemetry/api";
 function startTransportSpan(tracer, options) {
   const attributes = {
     [FrontMcpAttributes.TRANSPORT_TYPE]: options.type
@@ -1136,7 +1175,7 @@ function startTransportSpan(tracer, options) {
   }
   return startSpan(tracer, {
     name: `transport ${options.type}`,
-    kind: SpanKind10.INTERNAL,
+    kind: SpanKind11.INTERNAL,
     attributes,
     parentContext: options.parentContext
   });
@@ -1181,6 +1220,8 @@ var EXEC_SPAN_KEY = /* @__PURE__ */ Symbol.for("frontmcp:otel:exec-span");
 var ACTIVE_SPAN_KEY = /* @__PURE__ */ Symbol.for("frontmcp:otel:active-span");
 var ACTIVE_OTEL_CTX_KEY = /* @__PURE__ */ Symbol.for("frontmcp:otel:active-otel-ctx");
 var STAGE_TS_KEY = /* @__PURE__ */ Symbol.for("frontmcp:otel:stage-ts");
+var STAGE_EVENTS_KEY = /* @__PURE__ */ Symbol.for("frontmcp:otel:stage-events");
+var HTTP_SPAN_CTX_KEY = /* @__PURE__ */ Symbol.for("frontmcp:otel:http-span-ctx");
 function sessionTracingId(sessionId) {
   return sha256Hex(sessionId).slice(0, 16);
 }
@@ -1215,7 +1256,44 @@ function clearActiveSpan(flowCtx) {
   } catch {
   }
 }
+function beginFlowSpan(flowCtx, options, span, spanCtx) {
+  flowCtx.state[SPAN_KEY] = span;
+  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
+  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  flowCtx.state[STAGE_EVENTS_KEY] = options.flowStageEvents !== false;
+}
+function parentContextOf(ctx) {
+  return ctx.get?.(HTTP_SPAN_CTX_KEY) ?? createOTelContextFromTrace(ctx.traceContext);
+}
+function flowFailureOf(flowError) {
+  const failed = flowError?.originalError;
+  const error = flowError instanceof FlowControl ? failed instanceof Error ? failed : new InternalMcpError(`Flow ended with: ${flowError.type}`) : flowError instanceof Error ? flowError : new Error(String(flowError));
+  const reported = toMcpError(error);
+  return {
+    error,
+    type: reported.name,
+    message: reported.getPublicMessage(),
+    code: reported.code,
+    errorId: reported.errorId
+  };
+}
+function endFailedSpan(span, flowError) {
+  const failure = flowFailureOf(flowError);
+  span.setStatus({ code: SpanStatusCode2.ERROR, message: failure.message });
+  span.recordException({
+    name: failure.type,
+    message: failure.message,
+    code: failure.code,
+    stack: failure.error.stack
+  });
+  span.end();
+}
+function traceparentOf(span) {
+  const { traceId, spanId, traceFlags } = span.spanContext();
+  return `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, "0")}`;
+}
 function recordStageEvent(span, stageName, state) {
+  if (state[STAGE_EVENTS_KEY] === false) return;
   const now = Date.now();
   const prev = state[STAGE_TS_KEY];
   const attributes = {};
@@ -1241,9 +1319,8 @@ function onHttpWillTrace(options, flowCtx) {
   });
   span.setAttribute(McpAttributes.SESSION_ID, sessionHash);
   span.setAttribute(FrontMcpAttributes.SESSION_ID_HASH, sessionHash);
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  ctx.set?.(HTTP_SPAN_CTX_KEY, spanCtx);
+  beginFlowSpan(flowCtx, options, span, spanCtx);
   recordStageEvent(span, "traceRequest", flowCtx.state);
 }
 function onHttpWillAcquireQuota(flowCtx) {
@@ -1287,7 +1364,7 @@ function onToolWillParse(options, flowCtx) {
   const ctx = extractContext(flowCtx);
   if (!ctx) return;
   const tracer = getTracer();
-  const parentOTelCtx = createOTelContextFromTrace(ctx.traceContext);
+  const parentOTelCtx = parentContextOf(ctx);
   const sessionHash = sessionTracingId(ctx.sessionId);
   const { span, context: spanCtx } = startRpcSpan(tracer, {
     method: "tools/call",
@@ -1295,9 +1372,7 @@ function onToolWillParse(options, flowCtx) {
     sessionIdHash: sessionHash,
     parentContext: parentOTelCtx
   });
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  beginFlowSpan(flowCtx, options, span, spanCtx);
   recordStageEvent(span, "parseInput", flowCtx.state);
 }
 function onToolWillFindTool(flowCtx) {
@@ -1367,8 +1442,8 @@ function onToolDidFinalize(flowCtx) {
   const toolSpan = flowCtx.state?.[EXEC_SPAN_KEY];
   const error = flowCtx.state?.flowError;
   if (error) {
-    if (toolSpan) endSpanError(toolSpan, error instanceof Error ? error : String(error));
-    if (rpcSpan) endSpanError(rpcSpan, error instanceof Error ? error : String(error));
+    if (toolSpan) endFailedSpan(toolSpan, error);
+    if (rpcSpan) endFailedSpan(rpcSpan, error);
   } else if (rpcSpan) {
     recordStageEvent(rpcSpan, "finalize", flowCtx.state);
     endSpanOk(rpcSpan);
@@ -1379,7 +1454,7 @@ function onResourceWillParse(options, flowCtx) {
   const ctx = extractContext(flowCtx);
   if (!ctx) return;
   const tracer = getTracer();
-  const parentOTelCtx = createOTelContextFromTrace(ctx.traceContext);
+  const parentOTelCtx = parentContextOf(ctx);
   const sessionHash = sessionTracingId(ctx.sessionId);
   const { span, context: spanCtx } = startRpcSpan(tracer, {
     method: "resources/read",
@@ -1387,9 +1462,7 @@ function onResourceWillParse(options, flowCtx) {
     sessionIdHash: sessionHash,
     parentContext: parentOTelCtx
   });
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  beginFlowSpan(flowCtx, options, span, spanCtx);
   recordStageEvent(span, "parseInput", flowCtx.state);
 }
 function onResourceWillFind(flowCtx) {
@@ -1420,8 +1493,8 @@ function onResourceDidFinalize(flowCtx) {
   const resSpan = flowCtx.state?.[EXEC_SPAN_KEY];
   const error = flowCtx.state?.flowError;
   if (error) {
-    if (resSpan) endSpanError(resSpan, error instanceof Error ? error : String(error));
-    if (rpcSpan) endSpanError(rpcSpan, error instanceof Error ? error : String(error));
+    if (resSpan) endFailedSpan(resSpan, error);
+    if (rpcSpan) endFailedSpan(rpcSpan, error);
   } else if (rpcSpan) {
     recordStageEvent(rpcSpan, "finalize", flowCtx.state);
     endSpanOk(rpcSpan);
@@ -1432,7 +1505,7 @@ function onPromptWillParse(options, flowCtx) {
   const ctx = extractContext(flowCtx);
   if (!ctx) return;
   const tracer = getTracer();
-  const parentOTelCtx = createOTelContextFromTrace(ctx.traceContext);
+  const parentOTelCtx = parentContextOf(ctx);
   const sessionHash = sessionTracingId(ctx.sessionId);
   const { span, context: spanCtx } = startRpcSpan(tracer, {
     method: "prompts/get",
@@ -1440,9 +1513,7 @@ function onPromptWillParse(options, flowCtx) {
     sessionIdHash: sessionHash,
     parentContext: parentOTelCtx
   });
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  beginFlowSpan(flowCtx, options, span, spanCtx);
   recordStageEvent(span, "parseInput", flowCtx.state);
 }
 function onPromptWillFind(flowCtx) {
@@ -1476,8 +1547,8 @@ function onPromptDidFinalize(flowCtx) {
   const promptSpan = flowCtx.state?.[EXEC_SPAN_KEY];
   const error = flowCtx.state?.flowError;
   if (error) {
-    if (promptSpan) endSpanError(promptSpan, error instanceof Error ? error : String(error));
-    if (rpcSpan) endSpanError(rpcSpan, error instanceof Error ? error : String(error));
+    if (promptSpan) endFailedSpan(promptSpan, error);
+    if (rpcSpan) endFailedSpan(rpcSpan, error);
   } else if (rpcSpan) {
     recordStageEvent(rpcSpan, "finalize", flowCtx.state);
     endSpanOk(rpcSpan);
@@ -1488,7 +1559,7 @@ function onAgentWillParse(options, flowCtx) {
   const ctx = extractContext(flowCtx);
   if (!ctx) return;
   const tracer = getTracer();
-  const parentOTelCtx = createOTelContextFromTrace(ctx.traceContext);
+  const parentOTelCtx = parentContextOf(ctx);
   const sessionHash = sessionTracingId(ctx.sessionId);
   const { span, context: spanCtx } = startRpcSpan(tracer, {
     method: "agents/call",
@@ -1496,9 +1567,7 @@ function onAgentWillParse(options, flowCtx) {
     sessionIdHash: sessionHash,
     parentContext: parentOTelCtx
   });
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  beginFlowSpan(flowCtx, options, span, spanCtx);
   recordStageEvent(span, "parseInput", flowCtx.state);
 }
 function onAgentWillFind(flowCtx) {
@@ -1512,7 +1581,7 @@ function onAgentWillExecute(options, flowCtx) {
   const agentName = flowCtx.state?.input?.name ?? "unknown";
   const { span: agentSpan } = startSpan(tracer, {
     name: `agent ${agentName}`,
-    kind: SpanKind11.INTERNAL,
+    kind: SpanKind12.INTERNAL,
     attributes: {
       [FrontMcpAttributes.FLOW_NAME]: "agents:call-agent",
       [McpAttributes.COMPONENT_TYPE]: "agent",
@@ -1539,8 +1608,8 @@ function onAgentDidFinalize(flowCtx) {
   const agentSpan = flowCtx.state?.[EXEC_SPAN_KEY];
   const error = flowCtx.state?.flowError;
   if (error) {
-    if (agentSpan) endSpanError(agentSpan, error instanceof Error ? error : String(error));
-    if (rpcSpan) endSpanError(rpcSpan, error instanceof Error ? error : String(error));
+    if (agentSpan) endFailedSpan(agentSpan, error);
+    if (rpcSpan) endFailedSpan(rpcSpan, error);
   } else if (rpcSpan) {
     recordStageEvent(rpcSpan, "finalize", flowCtx.state);
     endSpanOk(rpcSpan);
@@ -1551,11 +1620,11 @@ function onGenericFlowWillStart(flowName, options, flowCtx) {
   const ctx = extractContext(flowCtx);
   if (!ctx) return;
   const tracer = getTracer();
-  const parentOTelCtx = createOTelContextFromTrace(ctx.traceContext);
+  const parentOTelCtx = parentContextOf(ctx);
   const sessionHash = sessionTracingId(ctx.sessionId);
   const { span, context: spanCtx } = startSpan(tracer, {
     name: flowName,
-    kind: SpanKind11.INTERNAL,
+    kind: SpanKind12.INTERNAL,
     attributes: {
       [FrontMcpAttributes.FLOW_NAME]: flowName,
       [McpAttributes.SESSION_ID]: sessionHash,
@@ -1565,9 +1634,7 @@ function onGenericFlowWillStart(flowName, options, flowCtx) {
     },
     parentContext: parentOTelCtx
   });
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  beginFlowSpan(flowCtx, options, span, spanCtx);
 }
 function onGenericFlowStage(stageName, flowCtx) {
   const span = flowCtx.state?.[SPAN_KEY];
@@ -1578,7 +1645,7 @@ function onGenericFlowDidFinalize(flowCtx) {
   if (!span) return;
   const error = flowCtx.state?.flowError;
   if (error) {
-    endSpanError(span, error instanceof Error ? error : String(error));
+    endFailedSpan(span, error);
   } else {
     endSpanOk(span);
   }
@@ -1588,16 +1655,14 @@ function onTransportWillStart(transportType, options, flowCtx) {
   const ctx = extractContext(flowCtx);
   if (!ctx) return;
   const tracer = getTracer();
-  const parentOTelCtx = createOTelContextFromTrace(ctx.traceContext);
+  const parentOTelCtx = parentContextOf(ctx);
   const sessionHash = sessionTracingId(ctx.sessionId);
   const { span, context: spanCtx } = startTransportSpan(tracer, {
     type: transportType,
     sessionIdHash: sessionHash,
     parentContext: parentOTelCtx
   });
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  beginFlowSpan(flowCtx, options, span, spanCtx);
   recordStageEvent(span, "parseInput", flowCtx.state);
 }
 function onTransportDidRoute(flowCtx) {
@@ -1617,7 +1682,7 @@ function onTransportDidFinalize(flowCtx) {
   recordStageEvent(span, "cleanup", flowCtx.state);
   const error = flowCtx.state?.flowError;
   if (error) {
-    endSpanError(span, error instanceof Error ? error : String(error));
+    endFailedSpan(span, error);
   } else {
     endSpanOk(span);
   }
@@ -1627,14 +1692,12 @@ function onAuthWillStart(flowName, options, flowCtx) {
   const ctx = extractContext(flowCtx);
   if (!ctx) return;
   const tracer = getTracer();
-  const parentOTelCtx = createOTelContextFromTrace(ctx.traceContext);
+  const parentOTelCtx = parentContextOf(ctx);
   const { span, context: spanCtx } = startAuthSpan(tracer, {
     flowName,
     parentContext: parentOTelCtx
   });
-  flowCtx.state[SPAN_KEY] = span;
-  flowCtx.state[SPAN_CTX_KEY] = spanCtx;
-  flowCtx.state[STAGE_TS_KEY] = Date.now();
+  beginFlowSpan(flowCtx, options, span, spanCtx);
   recordStageEvent(span, "parseInput", flowCtx.state);
 }
 function onAuthDidDetermineMode(flowCtx) {
@@ -1654,30 +1717,35 @@ function onAuthDidFinalize(flowCtx) {
   const error = flowCtx.state?.flowError;
   if (error) {
     setAuthResult(span, "unauthorized");
-    endSpanError(span, error instanceof Error ? error : String(error));
+    endFailedSpan(span, error);
   } else {
     setAuthResult(span, "authorized");
     endSpanOk(span);
   }
 }
 function wrapContextFetch(options, flowCtx) {
-  if (options.fetchSpans === false) return;
   const toolCtx = flowCtx.state?.toolContext ?? flowCtx.state?.toolCallContext;
   if (!toolCtx || typeof toolCtx.fetch !== "function") return;
   const originalFetch = toolCtx.fetch.bind(toolCtx);
   const parentOTelCtx = flowCtx.state?.[SPAN_CTX_KEY];
   toolCtx.fetch = async (input, init) => {
-    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
-    const method = init?.method ?? "GET";
-    const tracer = getTracer();
-    const { span } = startFetchSpan(tracer, { method, url, parentContext: parentOTelCtx });
+    const fetchSpan = options.fetchSpans === false ? void 0 : startFetchSpan(getTracer(), {
+      method: init?.method ?? (input instanceof Request ? input.method : "GET"),
+      url: typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url,
+      parentContext: parentOTelCtx
+    }).span;
+    const callingSpan = fetchSpan ?? flowCtx.state?.[EXEC_SPAN_KEY] ?? flowCtx.state?.[SPAN_KEY];
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
+    if (callingSpan && !headers.has("traceparent")) headers.set("traceparent", traceparentOf(callingSpan));
     try {
-      const response = await originalFetch(input, init);
-      setFetchResponseStatus(span, response.status);
-      endSpanOk(span);
+      const response = await originalFetch(input, { ...init, headers });
+      if (fetchSpan) {
+        setFetchResponseStatus(fetchSpan, response.status);
+        endSpanOk(fetchSpan);
+      }
       return response;
     } catch (err) {
-      endSpanError(span, err instanceof Error ? err : String(err));
+      if (fetchSpan) endSpanError(fetchSpan, err instanceof Error ? err : String(err));
       throw err;
     }
   };
@@ -1695,6 +1763,26 @@ function onAgentDidExecuteEnrich(flowCtx) {
     }
   }
 }
+var HOOK_OBSERVER_KEY = /* @__PURE__ */ Symbol.for("frontmcp:hook-observer");
+function installHookObserver(flowCtx, observer) {
+  const ctx = extractContext(flowCtx);
+  if (ctx && !ctx.get?.(HOOK_OBSERVER_KEY)) ctx.set?.(HOOK_OBSERVER_KEY, observer);
+}
+async function runInHookSpan(flowCtx, hook, run) {
+  const ctx = extractContext(flowCtx);
+  const { span } = startHookSpan(getTracer(), {
+    ...hook,
+    parentContext: flowCtx.state?.[SPAN_CTX_KEY] ?? (ctx && parentContextOf(ctx))
+  });
+  try {
+    await run();
+    endSpanOk(span);
+  } catch (error) {
+    if (error instanceof FlowControl && error.type !== "fail" && error.type !== "abort") endSpanOk(span);
+    else endFailedSpan(span, error);
+    throw error;
+  }
+}
 function reportStartup(data) {
   const tracer = getTracer();
   emitStartupReport(tracer, data);
@@ -1734,27 +1822,34 @@ function startRequestLog(flowCtx, options) {
   if (typeof rpcMethod === "string") collector.setRpcMethod(rpcMethod);
 }
 function recordRequestLogFailure(flowCtx) {
-  const failure = flowCtx.state?.["flowError"];
-  if (!failure) return;
-  const error = failure instanceof Error ? failure : new Error(String(failure));
-  currentRequestLog(flowCtx)?.setError({
-    type: error.name,
-    message: error.message,
-    code: error.code
-  });
+  const flowError = flowCtx.state?.["flowError"];
+  if (!flowError) return;
+  const { type, message, code, errorId } = flowFailureOf(flowError);
+  currentRequestLog(flowCtx)?.setError({ type, message, code, error_id: errorId });
+}
+function recordRequestLogAuth(flowCtx) {
+  const verifyResult = flowCtx.state?.["verifyResult"];
+  const authorization = flowCtx.rawInput?.request?.headers?.["authorization"];
+  const scheme = typeof authorization === "string" ? authorization.trim().split(/\s+/)[0].toLowerCase() : "";
+  const sub = verifyResult?.authorization?.user?.sub;
+  const anonymous = typeof sub !== "string" || isAnonymousSubject(sub);
+  currentRequestLog(flowCtx)?.setAuthInfo(
+    anonymous || !scheme ? "anonymous" : scheme,
+    verifyResult?.kind === "authorized" && !anonymous
+  );
 }
 async function completeRequestLog(flowCtx) {
   const collector = currentRequestLog(flowCtx);
   if (!collector || collector.isFinalized()) return;
   const statusCode = flowCtx.state?.["statusCode"] ?? flowCtx.rawInput?.response?.statusCode;
-  if (typeof statusCode === "number" && statusCode >= 400) collector.setStatus("error", statusCode);
+  if (typeof statusCode === "number") collector.setStatusCode(statusCode);
   await collector.finalize();
 }
 
 // libs/observability/src/telemetry/telemetry.accessor.ts
 import {
-  SpanKind as SpanKind12,
-  SpanStatusCode as SpanStatusCode2,
+  SpanKind as SpanKind13,
+  SpanStatusCode as SpanStatusCode3,
   trace as trace4
 } from "@opentelemetry/api";
 
@@ -1873,14 +1968,14 @@ var TelemetrySpan = class {
   /** Record an error on this span */
   recordError(error) {
     this.span.recordException(error);
-    this.span.setStatus({ code: SpanStatusCode2.ERROR, message: error.message });
+    this.span.setStatus({ code: SpanStatusCode3.ERROR, message: error.message });
     this.hasError = true;
     return this;
   }
   /** End the span (preserves ERROR status if already set) */
   end() {
     if (!this.hasError) {
-      this.span.setStatus({ code: SpanStatusCode2.OK });
+      this.span.setStatus({ code: SpanStatusCode3.OK });
     }
     this.span.end();
   }
@@ -1888,7 +1983,7 @@ var TelemetrySpan = class {
   endWithError(error) {
     const msg = typeof error === "string" ? error : error.message;
     if (error instanceof Error) this.span.recordException(error);
-    this.span.setStatus({ code: SpanStatusCode2.ERROR, message: msg });
+    this.span.setStatus({ code: SpanStatusCode3.ERROR, message: msg });
     this.span.end();
   }
   /** Get the underlying OTel span (escape hatch) */
@@ -1935,7 +2030,7 @@ var TelemetryAccessor = class {
     const span = this.tracer.startSpan(
       name,
       {
-        kind: SpanKind12.INTERNAL,
+        kind: SpanKind13.INTERNAL,
         attributes: { ...this.baseAttributes, ...attributes }
       },
       this.getActiveContext()
@@ -1984,11 +2079,11 @@ var TelemetryAccessor = class {
     } else {
       const span = this.tracer.startSpan(
         name,
-        { kind: SpanKind12.INTERNAL, attributes: this.baseAttributes },
+        { kind: SpanKind13.INTERNAL, attributes: this.baseAttributes },
         this.fallbackContext
       );
       if (attributes) span.addEvent(name, attributes);
-      span.setStatus({ code: SpanStatusCode2.OK });
+      span.setStatus({ code: SpanStatusCode3.OK });
       span.end();
     }
   }
@@ -2036,7 +2131,7 @@ var TelemetryAccessor = class {
 };
 
 // libs/observability/src/telemetry/telemetry.factory.ts
-import { SpanStatusCode as SpanStatusCode3, trace as trace5 } from "@opentelemetry/api";
+import { SpanStatusCode as SpanStatusCode4, trace as trace5 } from "@opentelemetry/api";
 var TelemetryFactory = class {
   constructor(tracerName = "@frontmcp/observability") {
     this.tracer = trace5.getTracer(tracerName);
@@ -2127,6 +2222,14 @@ var DEFAULT_TRACING = {
 var ObservabilityPlugin = class extends DynamicPlugin {
   constructor(options = {}) {
     super();
+    /** Wraps each other hook the request runs: names it on the request's log, and gives it a span with `hookSpans`. */
+    this.observeHook = async ({ flowName, stage, target, flowContext }, run) => {
+      if (target === this) return run();
+      if (this.requestLogsEnabled) currentRequestLog(flowContext)?.addHook(`${flowName}:${stage}`);
+      if (!this.traces("hookSpans")) return run();
+      const owner = target?.constructor?.name;
+      return runInHookSpan(flowContext, { flowName, stage, owner }, run);
+    };
     this.options = resolveOptions(options);
     this.tracingOpts = this.options.tracing !== false ? this.options.tracing : DEFAULT_TRACING;
   }
@@ -2136,6 +2239,15 @@ var ObservabilityPlugin = class extends DynamicPlugin {
   get requestLogsEnabled() {
     return this.options.requestLogs !== false;
   }
+  /** Whether tracing is on and its `kind` option isn't off. */
+  traces(kind) {
+    return this.tracingEnabled && this.tracingOpts[kind] !== false;
+  }
+  /** Watches the hooks of the request `ctx` serves, from the first flow of it that this plugin sees. */
+  watchHooks(ctx) {
+    if (this.requestLogsEnabled || this.traces("hookSpans"))
+      installHookObserver(ctx, this.observeHook);
+  }
   /** Names the entry a request serves on its request log, and records the entry flow's failure. */
   annotateRequestLog(ctx, set) {
     if (!this.requestLogsEnabled) return;
@@ -2146,6 +2258,7 @@ var ObservabilityPlugin = class extends DynamicPlugin {
   _httpWillTrace(ctx) {
     if (this.tracingEnabled) onHttpWillTrace(this.tracingOpts, ctx);
     if (this.options.requestLogs !== false) startRequestLog(ctx, this.options.requestLogs);
+    this.watchHooks(ctx);
   }
   _httpWillQuota(ctx) {
     if (this.tracingEnabled) onHttpWillAcquireQuota(ctx);
@@ -2158,6 +2271,7 @@ var ObservabilityPlugin = class extends DynamicPlugin {
   }
   _httpDidAuth(ctx) {
     if (this.tracingEnabled) onHttpDidCheckAuth(ctx);
+    if (this.requestLogsEnabled) recordRequestLogAuth(ctx);
   }
   _httpWillRoute(ctx) {
     if (this.tracingEnabled) onHttpWillRoute(ctx);
@@ -2170,6 +2284,7 @@ var ObservabilityPlugin = class extends DynamicPlugin {
     if (this.requestLogsEnabled) void completeRequestLog(ctx);
   }
   _toolWillParse(ctx) {
+    this.watchHooks(ctx);
     if (this.tracingEnabled) onToolWillParse(this.tracingOpts, ctx);
   }
   _toolWillFind(ctx) {
@@ -2208,6 +2323,7 @@ var ObservabilityPlugin = class extends DynamicPlugin {
     if (this.requestLogsEnabled) recordRequestLogFailure(ctx);
   }
   _resourceWillParse(ctx) {
+    this.watchHooks(ctx);
     if (this.tracingEnabled) onResourceWillParse(this.tracingOpts, ctx);
   }
   _resourceWillFind(ctx) {
@@ -2231,6 +2347,7 @@ var ObservabilityPlugin = class extends DynamicPlugin {
     if (this.requestLogsEnabled) recordRequestLogFailure(ctx);
   }
   _promptWillParse(ctx) {
+    this.watchHooks(ctx);
     if (this.tracingEnabled) onPromptWillParse(this.tracingOpts, ctx);
   }
   _promptWillFind(ctx) {
@@ -2254,6 +2371,7 @@ var ObservabilityPlugin = class extends DynamicPlugin {
     if (this.requestLogsEnabled) recordRequestLogFailure(ctx);
   }
   _agentWillParse(ctx) {
+    this.watchHooks(ctx);
     if (this.tracingEnabled) onAgentWillParse(this.tracingOpts, ctx);
   }
   _agentWillFind(ctx) {
@@ -2407,46 +2525,46 @@ var ObservabilityPlugin = class extends DynamicPlugin {
     if (this.tracingEnabled) onAuthDidFinalize(ctx);
   }
   _oauthTokenWill(ctx) {
-    if (this.tracingEnabled) onGenericFlowWillStart("oauth/token", this.tracingOpts, ctx);
+    if (this.traces("oauthSpans")) onGenericFlowWillStart("oauth/token", this.tracingOpts, ctx);
   }
   _oauthTokenDone(ctx) {
-    if (this.tracingEnabled) onGenericFlowDidFinalize(ctx);
+    if (this.traces("oauthSpans")) onGenericFlowDidFinalize(ctx);
   }
   _oauthAuthzWill(ctx) {
-    if (this.tracingEnabled) onGenericFlowWillStart("oauth/authorize", this.tracingOpts, ctx);
+    if (this.traces("oauthSpans")) onGenericFlowWillStart("oauth/authorize", this.tracingOpts, ctx);
   }
   _oauthAuthzDone(ctx) {
-    if (this.tracingEnabled) onGenericFlowDidFinalize(ctx);
+    if (this.traces("oauthSpans")) onGenericFlowDidFinalize(ctx);
   }
   _oauthCallbackWill(ctx) {
-    if (this.tracingEnabled) onGenericFlowWillStart("oauth/callback", this.tracingOpts, ctx);
+    if (this.traces("oauthSpans")) onGenericFlowWillStart("oauth/callback", this.tracingOpts, ctx);
   }
   _oauthCallbackDone(ctx) {
-    if (this.tracingEnabled) onGenericFlowDidFinalize(ctx);
+    if (this.traces("oauthSpans")) onGenericFlowDidFinalize(ctx);
   }
   _oauthProviderWill(ctx) {
-    if (this.tracingEnabled) onGenericFlowWillStart("oauth/provider-callback", this.tracingOpts, ctx);
+    if (this.traces("oauthSpans")) onGenericFlowWillStart("oauth/provider-callback", this.tracingOpts, ctx);
   }
   _oauthProviderDone(ctx) {
-    if (this.tracingEnabled) onGenericFlowDidFinalize(ctx);
+    if (this.traces("oauthSpans")) onGenericFlowDidFinalize(ctx);
   }
   _oauthRegisterWill(ctx) {
-    if (this.tracingEnabled) onGenericFlowWillStart("oauth/register", this.tracingOpts, ctx);
+    if (this.traces("oauthSpans")) onGenericFlowWillStart("oauth/register", this.tracingOpts, ctx);
   }
   _oauthRegisterDone(ctx) {
-    if (this.tracingEnabled) onGenericFlowDidFinalize(ctx);
+    if (this.traces("oauthSpans")) onGenericFlowDidFinalize(ctx);
   }
   _elicitReqWill(ctx) {
-    if (this.tracingEnabled) onGenericFlowWillStart("elicitation/request", this.tracingOpts, ctx);
+    if (this.traces("elicitationSpans")) onGenericFlowWillStart("elicitation/request", this.tracingOpts, ctx);
   }
   _elicitReqDone(ctx) {
-    if (this.tracingEnabled) onGenericFlowDidFinalize(ctx);
+    if (this.traces("elicitationSpans")) onGenericFlowDidFinalize(ctx);
   }
   _elicitResWill(ctx) {
-    if (this.tracingEnabled) onGenericFlowWillStart("elicitation/result", this.tracingOpts, ctx);
+    if (this.traces("elicitationSpans")) onGenericFlowWillStart("elicitation/result", this.tracingOpts, ctx);
   }
   _elicitResDone(ctx) {
-    if (this.tracingEnabled) onGenericFlowDidFinalize(ctx);
+    if (this.traces("elicitationSpans")) onGenericFlowDidFinalize(ctx);
   }
   _subscribeWill(ctx) {
     if (this.tracingEnabled) onGenericFlowWillStart("resources/subscribe", this.tracingOpts, ctx);
@@ -2512,12 +2630,10 @@ var ObservabilityPlugin = class extends DynamicPlugin {
   // Startup Report (public method)
   // ═══════════════════════════════════════════════════════════════════════════
   /**
-   * Emit startup telemetry report.
-   * Call after scope.initialize() completes with component counts.
+   * Emit the `frontmcp.startup` span (`tracing.startupReport`). The scope calls it once it is ready.
    */
   reportStartupTelemetry(data) {
-    if (this.options.tracing === false) return;
-    reportStartup(data);
+    if (this.traces("startupReport")) reportStartup(data);
   }
 };
 ObservabilityPlugin.defaultOptions = {
@@ -3084,35 +3200,8 @@ function setupOTel(options) {
   }
 }
 
-// libs/observability/src/otel/spans/hook.span.ts
-import { SpanKind as SpanKind13 } from "@opentelemetry/api";
-function recordHookEvent(parentSpan, stage, owner) {
-  const attributes = {};
-  if (owner) {
-    attributes[FrontMcpAttributes.HOOK_OWNER] = owner;
-  }
-  parentSpan.addEvent(`hook.${stage}`, attributes);
-}
-function startHookSpan(tracer, options) {
-  const attributes = {
-    [FrontMcpAttributes.HOOK_STAGE]: options.stage
-  };
-  if (options.owner) {
-    attributes[FrontMcpAttributes.HOOK_OWNER] = options.owner;
-  }
-  if (options.flowName) {
-    attributes[FrontMcpAttributes.FLOW_NAME] = options.flowName;
-  }
-  return startSpan(tracer, {
-    name: `hook ${options.stage}`,
-    kind: SpanKind13.INTERNAL,
-    attributes,
-    parentContext: options.parentContext
-  });
-}
-
 // libs/observability/src/otel/spans/pretty-span-exporter.ts
-import { SpanKind as SpanKind14, SpanStatusCode as SpanStatusCode4 } from "@opentelemetry/api";
+import { SpanKind as SpanKind14, SpanStatusCode as SpanStatusCode5 } from "@opentelemetry/api";
 var RESET = "\x1B[0m";
 var DIM = "\x1B[2m";
 var BOLD = "\x1B[1m";
@@ -3164,7 +3253,7 @@ var PrettySpanExporter = class {
     const traceShort = span.spanContext().traceId.slice(0, 8);
     const durationMs = (span.duration[0] * 1e3 + span.duration[1] / 1e6).toFixed(1);
     const kind = KIND_LABELS[span.kind] ?? "UNKNOWN";
-    const statusOk = span.status.code !== SpanStatusCode4.ERROR;
+    const statusOk = span.status.code !== SpanStatusCode5.ERROR;
     const attrs = Object.entries(span.attributes).filter(([k]) => SHOW_ATTRS.has(k)).map(([k, v]) => {
       const short = k.replace("frontmcp.", "").replace("mcp.", "");
       return `${short}=${v}`;
@@ -3353,7 +3442,7 @@ var ProcessStatsCollector = class {
       });
     }
     const mem = probeSafely(() => this.memoryUsage());
-    if (mem) {
+    if (mem && mem.rss > 0) {
       entries.push({
         name: "frontmcp_process_resident_memory_bytes",
         value: mem.rss,
@@ -3376,7 +3465,7 @@ var ProcessStatsCollector = class {
       });
     }
     const uptime = probeSafely(() => this.uptime());
-    if (uptime !== void 0) {
+    if (uptime !== void 0 && uptime > 0) {
       entries.push({
         name: "frontmcp_process_uptime_seconds",
         value: uptime,