@frontmcp/observability 1.11.2 → 1.12.0-rc.1

package/logging/sink.factory.d.ts

@@ -9,7 +9,7 @@ export declare function createSink(config: SinkConfig): LogSink;
 /**
  * Create an array of LogSink instances from an array of SinkConfig.
  *
- * If no configs are provided, defaults to StdoutSink in Node.js
- * or ConsoleSink in browser environments.
+ * Without configs it returns no sinks; `@FrontMcp({ observability: { logging } })` passes a stdout sink
+ * (a console sink in a browser) when `logging` names none.
  */
 export declare function createSinks(configs?: SinkConfig[]): LogSink[];

package/otel/context-propagator.d.ts

@@ -5,7 +5,7 @@
  * This propagator uses the existing FrontMCP trace context parser
  * to extract and inject W3C traceparent headers.
  */
-import { type Context, type TextMapGetter, type TextMapSetter, type TextMapPropagator } from '@opentelemetry/api';
+import { type Context, type TextMapGetter, type TextMapPropagator, type TextMapSetter } from '@opentelemetry/api';
 /**
  * FrontMcpPropagator — OTel TextMapPropagator that reads/writes
  * the W3C traceparent header using the same format as the SDK.

package/otel/otel.types.d.ts

@@ -61,7 +61,7 @@ export declare const FrontMcpAttributes: {
     readonly SESSION_CREATED: "frontmcp.session.created";
     /** Auth mode: "public" | "transparent" | "orchestrated" */
     readonly AUTH_MODE: "frontmcp.auth.mode";
-    /** Auth result: "authorized" | "unauthorized" | "anonymous" */
+    /** Auth result: "authorized" | "anonymous" | "unauthorized" | "forbidden" | "error" */
     readonly AUTH_RESULT: "frontmcp.auth.result";
     /** OAuth grant type: "authorization_code" | "refresh_token" | "anonymous" */
     readonly OAUTH_GRANT_TYPE: "frontmcp.oauth.grant_type";
@@ -127,7 +127,7 @@ export interface TracingOptions {
     flowStageEvents?: boolean;
     /** Instrument transport flows — SSE, streamable-http, stateless-http (default: true) */
     transportSpans?: boolean;
-    /** Instrument auth verify/session verify flows (default: true) */
+    /** An `auth session:verify` span for each HTTP request's authentication, with `frontmcp.auth.result` (default: true) */
     authSpans?: boolean;
     /** Instrument OAuth flows — token, authorize, callback, register (default: true) */
     oauthSpans?: boolean;

package/otel/spans/auth.span.d.ts

@@ -1,7 +1,7 @@
 /**
  * Auth Span — authentication and session verification instrumentation.
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface AuthSpanOptions {
     /** Auth flow name (e.g., "auth:verify", "session:verify") */
     flowName: string;

package/otel/spans/fetch.span.d.ts

@@ -4,7 +4,7 @@
  * Wraps fetch() calls made via FrontMcpContext.fetch() to create
  * client HTTP spans following OTel HTTP semantic conventions.
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface FetchSpanOptions {
     /** HTTP method */
     method: string;

package/otel/spans/hook.span.d.ts

@@ -5,7 +5,7 @@
  * to keep trace depth manageable. When hookSpans is enabled, each hook
  * gets its own child span.
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface HookSpanOptions {
     /** Hook stage name (e.g., "willExecute") */
     stage: string;

package/otel/spans/http-server.span.d.ts

@@ -3,7 +3,7 @@
  *
  * @see https://opentelemetry.io/docs/specs/semconv/http/http-spans/
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface HttpServerSpanOptions {
     method: string;
     path: string;

package/otel/spans/pretty-span-exporter.d.ts

@@ -8,8 +8,8 @@
  *   ↳ SPAN tools/call [36008509] 8ms rpc.system=mcp mcp.session.id=5bfdd288
  *   ↳ SPAN tool get_weather [36008509] 5ms mcp.component.type=tool enduser.id=client-42
  */
-import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { ExportResult } from '@opentelemetry/core';
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
 export declare class PrettySpanExporter implements SpanExporter {
     private useAnsi;
     constructor();

package/otel/spans/prompt.span.d.ts

@@ -1,7 +1,7 @@
 /**
  * Prompt Span — FrontMCP prompt invocation instrumentation.
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface PromptSpanOptions {
     /** Prompt name */
     name: string;

package/otel/spans/resource.span.d.ts

@@ -1,7 +1,7 @@
 /**
  * Resource Read Span — FrontMCP resource read instrumentation.
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface ResourceSpanOptions {
     /** Resource URI */
     uri: string;

package/otel/spans/rpc.span.d.ts

@@ -7,7 +7,7 @@
  *
  * @see https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface RpcSpanOptions {
     /** MCP method (e.g., "tools/call", "resources/read") */
     method: string;

package/otel/spans/span.utils.d.ts

@@ -1,7 +1,7 @@
 /**
  * Span utility helpers for creating and managing OTel spans.
  */
-import { type Tracer, type Span, type Context, SpanKind } from '@opentelemetry/api';
+import { SpanKind, type Context, type Span, type Tracer } from '@opentelemetry/api';
 /**
  * Options for starting a span.
  */

package/otel/spans/tool.span.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool Execution Span — FrontMCP tool invocation instrumentation.
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface ToolSpanOptions {
     /** Tool name */
     name: string;

package/otel/spans/transport.span.d.ts

@@ -4,7 +4,7 @@
  * Created for each transport-level flow that handles session creation,
  * protocol routing, and message dispatch.
  */
-import { type Tracer, type Span, type Context } from '@opentelemetry/api';
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
 export interface TransportSpanOptions {
     /** Transport type: "legacy-sse" | "streamable-http" | "stateless-http" */
     type: string;

package/otel/trace-context-bridge.d.ts

@@ -6,7 +6,7 @@
  * This bridge allows OTel spans to be created as children of
  * the existing trace, preserving the trace ID across the boundary.
  */
-import { type SpanContext, type Context as OTelContext } from '@opentelemetry/api';
+import { type Context as OTelContext, type SpanContext } from '@opentelemetry/api';
 /**
  * Minimal TraceContext interface — matches the SDK's TraceContext type
  * without importing it directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "1.11.2",
+  "version": "1.12.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.11.2",
-    "@frontmcp/utils": "1.11.2",
+    "@frontmcp/sdk": "1.12.0-rc.1",
+    "@frontmcp/utils": "1.12.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/observability.hooks.d.ts

@@ -99,10 +99,10 @@ export declare function onTransportWillStart(transportType: string, options: Tra
 export declare function onTransportDidRoute(flowCtx: any): void;
 export declare function onTransportStage(stageName: string, flowCtx: any): void;
 export declare function onTransportDidFinalize(flowCtx: any): void;
-export declare function onAuthWillStart(flowName: string, options: TracingOptions, flowCtx: any): void;
-export declare function onAuthDidDetermineMode(flowCtx: any): void;
-export declare function onAuthStage(stageName: string, flowCtx: any): void;
-export declare function onAuthDidFinalize(flowCtx: any): void;
+/** Opens the `auth session:verify` span of the request's authentication, inside its HTTP span. */
+export declare function onHttpWillAuthenticate(options: TracingOptions, flowCtx: any): void;
+/** Ends the authentication span, whatever the stage's outcome, with `frontmcp.auth.result`. */
+export declare function onHttpDidAuthenticate(flowCtx: any): void;
 export declare function wrapContextFetch(options: TracingOptions, flowCtx: any): void;
 export declare function onAgentDidExecuteEnrich(flowCtx: any): void;
 export type { HookObserver };

package/plugin/observability.plugin.d.ts

@@ -12,7 +12,7 @@ import type { ObservabilityPluginOptions, ObservabilityPluginOptionsInput } from
  * - Prompt invocations (parseInput → find → execute → validate → finalize)
  * - Agent calls (parseInput → find → auth → validate → execute → finalize)
  * - Skills (search, load)
- * - List operations (tools, resources, prompts, resource templates)
+ * - List operations (tools, resources, prompts, resource templates, events)
  * - Completions
  * - Session lifecycle (creation, auth verification)
  *
@@ -39,6 +39,7 @@ export default class ObservabilityPlugin extends DynamicPlugin<ObservabilityPlug
     _httpDidSemaphore(ctx: unknown): void;
     _httpWillAuth(ctx: unknown): void;
     _httpDidAuth(ctx: unknown): void;
+    _httpFinallyAuth(ctx: unknown): void;
     _httpWillRoute(ctx: unknown): void;
     _httpDidRoute(ctx: unknown): void;
     _httpFinallyFinalize(ctx: unknown): void;
@@ -88,6 +89,52 @@ export default class ObservabilityPlugin extends DynamicPlugin<ObservabilityPlug
     _listPromptsWill(ctx: unknown): void;
     _listPromptsDidFilter(ctx: unknown): void;
     _listPromptsDone(ctx: unknown): void;
+    /** Start the events/list span. */
+    _listEventsWill(ctx: unknown): void;
+    /** Record the filterByAuthorities stage on the events/list span. */
+    _listEventsDidFilter(ctx: unknown): void;
+    /** End the events/list span, however the listing ended. */
+    _listEventsDone(ctx: unknown): void;
+    /** Start the events/subscribe span. */
+    _eventSubscribeWill(ctx: unknown): void;
+    /** Record the verifyCallback stage on the events/subscribe span. */
+    _eventSubscribeDidVerify(ctx: unknown): void;
+    /** End the events/subscribe span, however the subscribe ended. */
+    _eventSubscribeDone(ctx: unknown): void;
+    /** Start the events/unsubscribe span. */
+    _eventUnsubscribeWill(ctx: unknown): void;
+    /** End the events/unsubscribe span, however the unsubscribe ended. */
+    _eventUnsubscribeDone(ctx: unknown): void;
+    /** Start the events/publish span. */
+    _eventPublishWill(ctx: unknown): void;
+    /** Record the match stage on the events/publish span. */
+    _eventPublishDidMatch(ctx: unknown): void;
+    /** End the events/publish span once its result is built. */
+    _eventPublishDone(ctx: unknown): void;
+    /** Starts the span of a request to the HTTP publish endpoint. */
+    _eventPublishHttpWill(ctx: unknown): void;
+    /** Marks on the span that the endpoint knows its caller. */
+    _eventPublishHttpDidAuthenticate(ctx: unknown): void;
+    /** Ends the span, however the request ended. */
+    _eventPublishHttpDone(ctx: unknown): void;
+    /** Start the events/deliver span. */
+    _eventDeliverWill(ctx: unknown): void;
+    /** Record the send stage on the events/deliver span. */
+    _eventDeliverDidSend(ctx: unknown): void;
+    /** End the events/deliver span once its result is built. */
+    _eventDeliverDone(ctx: unknown): void;
+    /** Start the events/poll span. */
+    _eventPollWill(ctx: unknown): void;
+    /** Record the readEvents stage on the events/poll span. */
+    _eventPollDidRead(ctx: unknown): void;
+    /** End the events/poll span, however the poll ended. */
+    _eventPollDone(ctx: unknown): void;
+    /** Start the events/stream span. */
+    _eventStreamWill(ctx: unknown): void;
+    /** Record the openStream stage on the events/stream span. */
+    _eventStreamDidOpen(ctx: unknown): void;
+    /** End the events/stream span, however the stream ended. */
+    _eventStreamDone(ctx: unknown): void;
     _skillSearchWill(ctx: unknown): void;
     _skillSearchDone(ctx: unknown): void;
     _skillLoadWill(ctx: unknown): void;
@@ -112,13 +159,6 @@ export default class ObservabilityPlugin extends DynamicPlugin<ObservabilityPlug
     _slhttpWillParse(ctx: unknown): void;
     _slhttpDidHandle(ctx: unknown): void;
     _slhttpFinallyCleanup(ctx: unknown): void;
-    _authVerifyWill(ctx: unknown): void;
-    _authVerifyDidMode(ctx: unknown): void;
-    _authVerifyDidToken(ctx: unknown): void;
-    _authVerifyDidBuild(ctx: unknown): void;
-    _sessionVerifyWill(ctx: unknown): void;
-    _sessionVerifyDidJwt(ctx: unknown): void;
-    _sessionVerifyDidBuild(ctx: unknown): void;
     _oauthTokenWill(ctx: unknown): void;
     _oauthTokenDone(ctx: unknown): void;
     _oauthAuthzWill(ctx: unknown): void;

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

@@ -21,7 +21,7 @@ export interface ObservabilityPluginOptions {
  * Logging options within the plugin.
  */
 export interface ObservabilityLoggingOptions {
-    /** Sink configurations (default: StdoutSink in Node.js, ConsoleSink in browser) */
+    /** Sink configurations; through `@FrontMcp({ observability })`, a stdout sink (console in a browser) when omitted */
     sinks?: SinkConfig[];
     /** Field names to redact from log attributes */
     redactFields?: string[];

package/request-log/index.d.ts

@@ -1,3 +1,3 @@
-export type { RequestLog, RequestLogEntry, RequestLogCollectorOptions } from './request-log.types';
+export type { RequestLog, RequestLogEntry, RequestLogCollectorOptions, RequestLogSummary } from './request-log.types';
 export { RequestLogCollector } from './request-log.collector';
 export { REQUEST_LOG_COLLECTOR } from './request-log.tokens';

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

@@ -10,6 +10,7 @@ export declare class RequestLogCollector {
     private readonly entries;
     private readonly hooksTriggered;
     private readonly maxEntries;
+    private readonly includeSummaries;
     private readonly onComplete?;
     private readonly requestId;
     private readonly traceId;
@@ -27,6 +28,8 @@ export declare class RequestLogCollector {
     private status;
     private statusCode?;
     private error?;
+    private inputSummary?;
+    private outputSummary?;
     private finalized;
     private finalizedLog?;
     constructor(context: {
@@ -65,6 +68,14 @@ export declare class RequestLogCollector {
      * Set the prompt name being invoked.
      */
     setPromptName(name: string): void;
+    /**
+     * Summarize the call's arguments, with `includeSummaries`.
+     */
+    setInput(args: unknown): void;
+    /**
+     * Summarize the call's result, with `includeSummaries`.
+     */
+    setOutput(result: unknown): void;
     /**
      * Set authentication info.
      */

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

@@ -21,6 +21,8 @@ export declare function currentRequestLog(flowCtx: RequestLogFlowContext): Reque
 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;
+/** Summarizes an entry flow's answer (its `state.output`) on the request's log, with `includeSummaries`. */
+export declare function recordRequestLogOutput(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.

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

@@ -0,0 +1,5 @@
+import type { RequestLogSummary } from './request-log.types';
+/** The argument names and size of a call's arguments. */
+export declare function summarizeInput(args: unknown): RequestLogSummary;
+/** The size, content types, `structuredContent` keys and error flag of a call's result. */
+export declare function summarizeOutput(result: unknown): RequestLogSummary;

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

@@ -68,6 +68,23 @@ export interface RequestLog {
     hooks_triggered: string[];
     /** All structured log entries for this request */
     entries: RequestLogEntry[];
+    /** The arguments of a `tools/call` or `prompts/get`, without their values */
+    input_summary?: RequestLogSummary;
+    /** The result of a `tools/call`, `resources/read` or `prompts/get`, without its content */
+    output_summary?: RequestLogSummary;
+}
+/**
+ * The shape and size of a call's arguments or result, never its values.
+ */
+export interface RequestLogSummary {
+    /** Size of the value as JSON, in bytes */
+    bytes?: number;
+    /** The argument names of an input; the `structuredContent` keys of a tool's result */
+    keys?: string[];
+    /** The content types of a result: `text`, `image`, … for a tool or prompt, each content's `mimeType` for a resource */
+    content_types?: string[];
+    /** Whether a tool's result is an error result */
+    is_error?: boolean;
 }
 /**
  * Options for RequestLogCollector.
@@ -75,7 +92,10 @@ export interface RequestLog {
 export interface RequestLogCollectorOptions {
     /** Maximum entries to collect per request (default: 500) */
     maxEntries?: number;
-    /** Accepted, but not read yet: request logs carry no input or output summaries. */
+    /**
+     * Add `input_summary` and `output_summary` to the log of a `tools/call`, `resources/read` or `prompts/get`: the
+     * argument names, result keys, content types and sizes, never the values (default: false).
+     */
     includeSummaries?: boolean;
     /** Callback when request log is complete */
     onRequestComplete?: (log: RequestLog) => void | Promise<void>;