@frontmcp/observability 1.10.16 → 1.11.0-rc.1

package/logging/structured-log-transport.d.ts

@@ -1,6 +1,6 @@
-import { LogTransportInterface, LogRecord } from '@frontmcp/sdk';
+import { LogTransportInterface, type LogRecord } from '@frontmcp/sdk';
 import type { LogSink } from './log-sink.interface';
-import type { StructuredLogEntry, StructuredLogTransportOptions } from './structured-log.types';
+import { type StructuredLogEntry, type StructuredLogTransportOptions } from './structured-log.types';
 /**
  * Context accessor function type.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "1.10.16",
+  "version": "1.11.0-rc.1",
   "description": "OpenTelemetry tracing, structured JSON logging, request logs and Prometheus-format metrics for FrontMCP servers",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -53,8 +53,8 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
-    "@frontmcp/sdk": "1.10.16",
-    "@frontmcp/utils": "1.10.16",
+    "@frontmcp/sdk": "1.11.0-rc.1",
+    "@frontmcp/utils": "1.11.0-rc.1",
     "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
     "@opentelemetry/sdk-node": "^0.219.0",
     "@opentelemetry/sdk-trace-base": "^2.8.0",

package/plugin/index.d.ts

@@ -1,3 +1,5 @@
 export { default as ObservabilityPlugin } from './observability.plugin';
 export type { ObservabilityPluginOptions, ObservabilityPluginOptionsInput, ObservabilityLoggingOptions, } from './observability.plugin.types';
+export { ObservabilityConfigurationError } from './observability.errors';
+export type { DevEventsOptions, StallDetectionOptions } from './observability.options';
 export { sessionTracingId, SPAN_KEY, SPAN_CTX_KEY, EXEC_SPAN_KEY, ACTIVE_SPAN_KEY, ACTIVE_OTEL_CTX_KEY, reportStartup, } from './observability.hooks';

package/plugin/observability.errors.d.ts

@@ -0,0 +1,6 @@
+import { InternalMcpError } from '@frontmcp/sdk';
+/** Raised when `ObservabilityPlugin.init()` or `@FrontMcp({ observability })` is given options it cannot honour. */
+export declare class ObservabilityConfigurationError extends InternalMcpError {
+    readonly name = "ObservabilityConfigurationError";
+    constructor(message: string);
+}

package/plugin/observability.hooks.d.ts

@@ -18,6 +18,7 @@
  * - Every flow stage recorded as a timed span event
  * - Error status propagated to parent spans
  */
+import { type HookObserver } from '@frontmcp/sdk';
 import { type TracingOptions } from '../otel/otel.types';
 import { type StartupTelemetryData } from '../otel/spans/startup.span';
 /** Root span for the current flow (HTTP server span or RPC span) */
@@ -104,14 +105,8 @@ 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 type { HookObserver };
+/** Adds `observer` to the hook observers of the request the flow `flowCtx` serves, unless this plugin added one. */
 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: {

package/plugin/observability.options.d.ts

@@ -0,0 +1,34 @@
+import type { DevEventSink } from '../dev-events/dev-event-stream';
+/** Event-loop stall detection: a warning, a metric and a dev event for each stall, naming the calls in flight. */
+export interface StallDetectionOptions {
+    /** The shortest loop delay reported as a stall, in milliseconds (200 by default, from 20 to 60000). */
+    thresholdMs?: number;
+}
+/** The `frontmcp dev` event stream: call timings, failures and stalls. Only on in development. */
+export interface DevEventsOptions {
+    /** A JSON Lines file to append the events to; `frontmcp dev` names one (`--events-file`) when this is unset. */
+    file?: string;
+    /** More places to send the events to. */
+    sinks?: DevEventSink[];
+    /** How many events wait for the sinks at most before new ones are dropped (1000 by default). */
+    maxQueue?: number;
+}
+export interface ResolvedStallOptions {
+    thresholdMs: number;
+}
+export interface ResolvedDevEventsOptions {
+    file?: string;
+    /** Whether to send the events to the dev parent over IPC (`frontmcp dev --stdio --serve`). */
+    ipc: boolean;
+    sinks: DevEventSink[];
+    maxQueue: number;
+}
+/** Set by `frontmcp dev` on the server it starts: the events file, or `1` to send the events over IPC. */
+export declare const DEV_EVENTS_FILE_ENV = "FRONTMCP_DEV_EVENTS_FILE";
+export declare const DEV_EVENTS_IPC_ENV = "FRONTMCP_DEV_EVENTS_IPC";
+export declare function resolveStallOptions(input: boolean | StallDetectionOptions | undefined): ResolvedStallOptions | false;
+/**
+ * The dev event stream's options, or `false` when it is off: outside development (no `frontmcp dev` and
+ * `NODE_ENV` not `development`), when turned off, or with nowhere to write.
+ */
+export declare function resolveDevEventsOptions(input: boolean | DevEventsOptions | undefined, env?: NodeJS.ProcessEnv): ResolvedDevEventsOptions | false;

package/plugin/observability.plugin.types.d.ts

@@ -1,6 +1,7 @@
-import type { TracingOptions } from '../otel/otel.types';
 import type { SinkConfig } from '../logging/log-sink.interface';
+import type { TracingOptions } from '../otel/otel.types';
 import type { RequestLogCollectorOptions } from '../request-log/request-log.types';
+import type { DevEventsOptions, ResolvedDevEventsOptions, ResolvedStallOptions, StallDetectionOptions } from './observability.options';
 /**
  * Full resolved options for ObservabilityPlugin.
  */
@@ -11,6 +12,10 @@ export interface ObservabilityPluginOptions {
     logging: ObservabilityLoggingOptions | false;
     /** Request log collection configuration */
     requestLogs: RequestLogCollectorOptions | false;
+    /** Event-loop stall detection */
+    stalls: ResolvedStallOptions | false;
+    /** The `frontmcp dev` event stream; off outside development */
+    devEvents: ResolvedDevEventsOptions | false;
 }
 /**
  * Logging options within the plugin.
@@ -35,4 +40,8 @@ export interface ObservabilityPluginOptionsInput {
     logging?: boolean | ObservabilityLoggingOptions;
     /** Enable/configure request log collection */
     requestLogs?: boolean | RequestLogCollectorOptions;
+    /** Report event-loop stalls with the calls in flight: a warning, a metric and a dev event (default: off) */
+    stalls?: boolean | StallDetectionOptions;
+    /** Write call timings, failures and stalls to the `frontmcp dev` event stream (default: on, in development only) */
+    devEvents?: boolean | DevEventsOptions;
 }

package/stalls/call-monitor.d.ts

@@ -0,0 +1,39 @@
+import { DevEventStream } from '../dev-events/dev-event-stream';
+import type { ResolvedDevEventsOptions, ResolvedStallOptions } from '../plugin/observability.options';
+import { StallDetector } from './stall-detector';
+interface MonitorLogger {
+    warn(message: string): void;
+}
+/**
+ * A server's dev event stream, and its share of the process's stall detector. Its hooks keep each entry's execute stage
+ * in the calls in flight (an `Around` hook, so a failed call ends too) and report each call when its flow ends (a
+ * `Finally` hook).
+ */
+export declare class CallMonitor {
+    private readonly logger;
+    /** One stall detector per threshold in the process, shared by the monitor of every server, so a stall is reported once. */
+    private static readonly sharedDetectors;
+    readonly stalls?: StallDetector;
+    readonly devEvents?: DevEventStream;
+    private readonly sharedStalls?;
+    private readonly stallCounter?;
+    private readonly callStarts;
+    constructor(stallOptions: ResolvedStallOptions | false, devEventsOptions: ResolvedDevEventsOptions | false, logger: MonitorLogger);
+    private static sharedDetectorFor;
+    onReady(): void;
+    onShutdown(): Promise<void>;
+    markToolCallStart(ctx: unknown): void;
+    trackToolExecution(ctx: unknown, next: () => Promise<void>): Promise<void>;
+    reportToolCall(ctx: unknown): void;
+    markResourceReadStart(ctx: unknown): void;
+    trackResourceExecution(ctx: unknown, next: () => Promise<void>): Promise<void>;
+    reportResourceRead(ctx: unknown): void;
+    markPromptGetStart(ctx: unknown): void;
+    trackPromptExecution(ctx: unknown, next: () => Promise<void>): Promise<void>;
+    reportPromptGet(ctx: unknown): void;
+    private markStart;
+    private track;
+    private reportStall;
+    private report;
+}
+export {};

package/stalls/in-flight-calls.d.ts

@@ -0,0 +1,29 @@
+/** The requests whose entries a stall can be blamed on. */
+export type CallMethod = 'tools/call' | 'resources/read' | 'prompts/get';
+export interface CallIdentity {
+    method: CallMethod;
+    /** The entry's full name, its app's id first (`reports:export_rows`). */
+    entry: string;
+    /** The first 12 hex characters of the session's tracing id, never the session id itself. */
+    session?: string;
+}
+export interface CallRecord extends CallIdentity {
+    startedAt: number;
+    endedAt?: number;
+}
+/** The calls running now, and the ones that ended recently enough to have run during a stall still being measured. */
+export declare class InFlightCalls {
+    private readonly now;
+    private readonly records;
+    constructor(now: () => number);
+    /**
+     * Runs `body` as a call in flight. The call ends when `body` settles, whatever its outcome, or, when
+     * `stillRunning()` then returns a promise (an execution a timeout left running), when that promise settles.
+     */
+    track(call: CallIdentity, body: () => Promise<void>, stillRunning?: () => unknown): Promise<void>;
+    running(): CallRecord[];
+    /** The calls that ran at some point between `from` and `to`. */
+    during(from: number, to: number): CallRecord[];
+    /** Forgets the calls that ended before `time`. */
+    prune(time: number): void;
+}

package/stalls/index.d.ts

@@ -0,0 +1,6 @@
+export { CallMonitor } from './call-monitor';
+export { InFlightCalls } from './in-flight-calls';
+export type { CallIdentity, CallMethod, CallRecord } from './in-flight-calls';
+export { StallDetector } from './stall-detector';
+export type { GcPause, StallDetectorOptions, StallReport, StalledCall } from './stall-detector';
+export { countStall, describeStall, STALL_SECONDS_COUNTER } from './stall-report';

package/stalls/stall-detector.d.ts

@@ -0,0 +1,52 @@
+import { InFlightCalls, type CallIdentity } from './in-flight-calls';
+/** A garbage-collection pause, on the `performance.now()` clock. */
+export interface GcPause {
+    startTime: number;
+    duration: number;
+}
+export interface StalledCall extends CallIdentity {
+    /** How long the call had been running when the stall ended. */
+    runningMs: number;
+}
+export interface StallReport {
+    stallMs: number;
+    /** How much of the stall garbage collection took. */
+    gcMs: number;
+    /** `gc` when the stall less its GC time is under the threshold; else `calls`, or `unknown` with no call in flight. */
+    cause: 'calls' | 'gc' | 'unknown';
+    /** The calls in flight during the stall. */
+    calls: StalledCall[];
+}
+export interface StallDetectorOptions {
+    thresholdMs: number;
+    onStall: (report: StallReport) => void;
+    now?: () => number;
+    /** Feeds GC pauses to `record`, and returns how to stop; none where the runtime has no `perf_hooks`, so no sampling. */
+    observeGc?: (record: (pause: GcPause) => void) => (() => void) | undefined;
+}
+/**
+ * Samples the event loop every 10 ms and reports each gap of `thresholdMs` or more between two samples as a stall,
+ * with the calls in flight during it. A stall is reported on the sample after the one that measured it, once its
+ * GC pauses have been delivered.
+ */
+export declare class StallDetector {
+    readonly calls: InFlightCalls;
+    readonly onStall: (report: StallReport) => void;
+    private readonly thresholdMs;
+    private readonly now;
+    private readonly observeGc;
+    private stopObservingGc?;
+    private timer?;
+    private pending;
+    private gcPauses;
+    private previousSampleAt;
+    constructor(options: StallDetectorOptions);
+    /** Whether it samples: started, on a runtime with `perf_hooks`, and not stopped. */
+    get running(): boolean;
+    start(): void;
+    /** Stops sampling, and reports the stall measured last if there is one. */
+    stop(): void;
+    sample(): void;
+    private reportPending;
+    private reportOf;
+}

package/stalls/stall-report.d.ts

@@ -0,0 +1,9 @@
+import type { TelemetryCounter } from '../telemetry/telemetry.counters';
+import type { StallReport } from './stall-detector';
+/** Seconds the event loop was stalled, labelled `cause` (a call's method, `gc` or `unknown`) and `entry`. */
+export declare const STALL_SECONDS_COUNTER = "frontmcp_event_loop_stall_seconds_total";
+export declare const STALL_SECONDS_DESCRIPTION = "Seconds the event loop was stalled, by the method and entry of each call in flight, or gc, or unknown";
+/** One log line: how long the loop stalled, how much of it was GC, and the calls in flight; never their inputs. */
+export declare function describeStall(report: StallReport): string;
+/** Adds GC time under `gc`, and the rest of a stall to each entry in flight once, or to `unknown`. */
+export declare function countStall(report: StallReport, counter: TelemetryCounter): void;

package/logging/redaction.d.ts

@@ -1,17 +0,0 @@
-/**
- * Field redaction utilities for structured log entries.
- *
- * Traverses objects and replaces values of sensitive fields with '[REDACTED]'.
- */
-/**
- * Redact sensitive fields from an object.
- *
- * Performs a shallow clone with redacted values — does not mutate the input.
- * Field matching is case-insensitive.
- *
- * @param obj - Object to redact fields from
- * @param fields - Field names to redact (case-insensitive)
- * @param maxDepth - Maximum recursion depth (default: 5)
- * @returns New object with sensitive fields replaced by '[REDACTED]'
- */
-export declare function redactFields(obj: Record<string, unknown>, fields: string[], maxDepth?: number): Record<string, unknown>;