@frontmcp/observability 1.9.1 → 1.9.3

package/otel/otel.types.d.ts

@@ -133,7 +133,7 @@ export interface TracingOptions {
     oauthSpans?: boolean;
     /** Instrument elicitation request/result flows (default: true) */
     elicitationSpans?: boolean;
-    /** Emit startup telemetry report on first request (default: true) */
+    /** Emit a `frontmcp.startup` span once the server is ready (default: true) */
     startupReport?: boolean;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -51,8 +51,8 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
-    "@frontmcp/sdk": "1.9.1",
-    "@frontmcp/utils": "1.9.1",
+    "@frontmcp/sdk": "1.9.3",
+    "@frontmcp/utils": "1.9.3",
     "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
     "@opentelemetry/sdk-node": "^0.219.0",
     "@opentelemetry/sdk-trace-base": "^2.8.0",

package/plugin/observability.hooks.d.ts

@@ -32,6 +32,8 @@ export declare const ACTIVE_SPAN_KEY: unique symbol;
 export declare const ACTIVE_OTEL_CTX_KEY: unique symbol;
 /** Timestamp of the last recorded stage event */
 export declare const STAGE_TS_KEY: unique symbol;
+/** OTel context of the request's HTTP span, on the FrontMcpContext: the parent of the spans of the flows it runs */
+export declare const HTTP_SPAN_CTX_KEY: unique symbol;
 /**
  * Generate a privacy-safe session tracing ID.
  * 16-char truncated SHA-256 — sufficient for trace correlation,
@@ -43,6 +45,17 @@ export interface FlowContextLike {
     get?(key: symbol): unknown;
     state?: Record<symbol | string, any>;
 }
+/** Why a flow failed, as the client sees it in production. */
+export interface FlowFailure {
+    /** The error itself: what `this.fail()` was given, not the control-flow signal that carried it */
+    error: Error;
+    type: string;
+    message: string;
+    code: string;
+    errorId: string;
+}
+/** The failure behind a flow's `state.flowError`, mapped as the SDK maps it for the client (same error ID). */
+export declare function flowFailureOf(flowError: unknown): FlowFailure;
 export declare function onHttpWillTrace(options: TracingOptions, flowCtx: any): void;
 export declare function onHttpWillAcquireQuota(flowCtx: any): void;
 export declare function onHttpDidAcquireQuota(flowCtx: any): void;
@@ -91,4 +104,19 @@ export declare function onAuthStage(stageName: string, flowCtx: any): void;
 export declare function onAuthDidFinalize(flowCtx: any): void;
 export declare function wrapContextFetch(options: TracingOptions, flowCtx: any): void;
 export declare function onAgentDidExecuteEnrich(flowCtx: any): void;
+/** Wraps each hook a plugin, app or entry injected into a flow of the request: `run` runs the hook. */
+export type HookObserver = (hook: {
+    flowName: string;
+    stage: string;
+    target: unknown;
+    flowContext: unknown;
+}, run: () => Promise<void>) => Promise<void>;
+/** Installs `observer` for the request the flow `flowCtx` serves, unless one watches it already. */
+export declare function installHookObserver(flowCtx: FlowContextLike, observer: HookObserver): void;
+/** Runs one hook inside a `hook <stage>` span, a child of its flow's span. `fail` and `abort` end it as an error; other control-flow signals end it OK. */
+export declare function runInHookSpan(flowCtx: any, hook: {
+    flowName: string;
+    stage: string;
+    owner?: string;
+}, run: () => Promise<void>): Promise<void>;
 export declare function reportStartup(data: StartupTelemetryData): void;

package/plugin/observability.plugin.d.ts

@@ -25,6 +25,15 @@ export default class ObservabilityPlugin extends DynamicPlugin<ObservabilityPlug
     private tracingOpts;
     constructor(options?: ObservabilityPluginOptionsInput);
     private get tracingEnabled();
+    private get requestLogsEnabled();
+    /** Whether tracing is on and its `kind` option isn't off. */
+    private traces;
+    /** Wraps each other hook the request runs: names it on the request's log, and gives it a span with `hookSpans`. */
+    private readonly observeHook;
+    /** Watches the hooks of the request `ctx` serves, from the first flow of it that this plugin sees. */
+    private watchHooks;
+    /** Names the entry a request serves on its request log, and records the entry flow's failure. */
+    private annotateRequestLog;
     _httpWillTrace(ctx: unknown): void;
     _httpWillQuota(ctx: unknown): void;
     _httpDidSemaphore(ctx: unknown): void;
@@ -145,8 +154,7 @@ export default class ObservabilityPlugin extends DynamicPlugin<ObservabilityPlug
     _toolDidCreateCtxFetch(ctx: unknown): void;
     _agentDidExecuteMeta(ctx: unknown): void;
     /**
-     * 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: StartupTelemetryData): void;
     static dynamicProviders: (input: ObservabilityPluginOptionsInput) => ProviderType[];

package/process-stats/process-stats.collector.d.ts

@@ -53,7 +53,7 @@ export declare class ProcessStatsCollector {
     private readonly getActiveHandles?;
     private readonly getActiveRequests?;
     private readonly readFdCount;
-    private cpuStart;
+    private cpuStart?;
     constructor(init?: ProcessStatsCollectorOptions);
     collect(): GaugeSnapshotEntry[];
     /**

package/request-log/request-log.collector.d.ts

@@ -73,6 +73,10 @@ export declare class RequestLogCollector {
      * Set request status.
      */
     setStatus(status: RequestLog['status'], statusCode?: number): void;
+    /**
+     * Set the HTTP status the request was answered with; one of 400 or more marks it failed.
+     */
+    setStatusCode(statusCode: number): void;
     /**
      * Set error details.
      */

package/request-log/request-log.hooks.d.ts

@@ -0,0 +1,35 @@
+import { RequestLogCollector } from './request-log.collector';
+import type { RequestLogCollectorOptions } from './request-log.types';
+interface RequestLogFlowContext {
+    get?(token: unknown): unknown;
+    rawInput?: {
+        request?: {
+            method?: string;
+            path?: string;
+            body?: unknown;
+            headers?: Record<string, unknown>;
+        };
+        response?: {
+            statusCode?: unknown;
+        };
+    };
+    state?: Record<string | symbol, unknown>;
+}
+/** The open request log of the request `flowCtx` serves; entry flows annotate it. */
+export declare function currentRequestLog(flowCtx: RequestLogFlowContext): RequestLogCollector | undefined;
+/** Opens the request's log, kept on the request context so the entry flows and log entries reach it. */
+export declare function startRequestLog(flowCtx: RequestLogFlowContext, options: RequestLogCollectorOptions): void;
+/** Records why an entry flow failed (its `state.flowError`) on the request's log, as the client sees it. */
+export declare function recordRequestLogFailure(flowCtx: RequestLogFlowContext): void;
+/**
+ * Records how the HTTP flow authenticated the request (its `state.verifyResult`): `auth_type` is the scheme of
+ * the `Authorization` header (`bearer`), or `anonymous` for a caller without one or with an anonymous subject.
+ */
+export declare function recordRequestLogAuth(flowCtx: RequestLogFlowContext): void;
+/**
+ * Closes the request's log with its HTTP status, which fires `requestLogs.onRequestComplete`: the status the
+ * flow responded with (`state.statusCode`), else the one a transport wrote to the response itself. A status
+ * of 400 or more marks the request failed.
+ */
+export declare function completeRequestLog(flowCtx: RequestLogFlowContext): Promise<void>;
+export {};

package/request-log/request-log.types.d.ts

@@ -75,7 +75,7 @@ export interface RequestLog {
 export interface RequestLogCollectorOptions {
     /** Maximum entries to collect per request (default: 500) */
     maxEntries?: number;
-    /** Include input/output summaries (default: true) */
+    /** Accepted, but not read yet: request logs carry no input or output summaries. */
     includeSummaries?: boolean;
     /** Callback when request log is complete */
     onRequestComplete?: (log: RequestLog) => void | Promise<void>;

package/telemetry/telemetry.context-extension.d.ts

@@ -1,12 +1,12 @@
 /**
  * Module augmentation for TypeScript — adds `this.telemetry` to every
  * execution context: ExecutionContextBase (ToolContext, ResourceContext,
- * AgentContext, JobContext, SkillContext, ...) and PromptContext.
+ * AgentContext, JobContext, SkillContext, PromptContext, ...).
  *
  * This file provides type information only. The runtime getter is
  * installed by the SDK's context extension mechanism when the
- * ObservabilityPlugin registers its `contextExtensions`, on the same two
- * prototypes: ExecutionContextBase and PromptContext.
+ * ObservabilityPlugin registers its `contextExtensions`, on
+ * ExecutionContextBase.prototype, which PromptContext inherits.
  */
 import type { TelemetryAccessor } from './telemetry.accessor';
 declare module '@frontmcp/sdk' {