Skip to content

instrument() and InstrumentationMiddleware

from fastmcp_feedback.instrumentation import InstrumentationMiddleware, instrument
instrument(app, sinks=None, **kwargs) -> InstrumentationMiddleware

Creates an InstrumentationMiddleware(sinks, **kwargs), adds it to app with app.add_middleware, and returns it.

FastMCP runs the first middleware added as the outermost. Call instrument() before adding other middleware to include their time and record calls they reject; call it last to time only the tool.

InstrumentationMiddleware(
sinks=None, *, mode=None, redactor=None, meta_only_tools=(),
identity_resolver=None, late_identity_keys=(), enricher=None, server_version=None,
hook_timeout=0.25, max_queue=1000, batch_size=100, sink_timeout=10.0,
max_error_chars=500, recent_calls=2000, correlation_timeout=1.0,
result_classifier=DEFAULT_RESULT_CLASSIFIER, exclude_tools=(),
sample_rates=None, random=random.random, recent_events=2000,
capture_llm_text=False, max_llm_text_chars=None, max_payload_bytes=65536,
)
ParameterDefaultDescription
sinks[JsonLinesSink()]Where records go. See Sinks.
modeFEEDBACK_INSTRUMENTATION_MODE, then "meta""off", "meta" or "full". Anything else raises ValueError.
redactorRedactor()Secret redaction for arguments, results, error text, hook output, event attributes and embedded text. See Redaction.
meta_only_tools()Tools never recorded above meta, even in full mode.
identity_resolverNone(context) -> dict, may be async. Keys user_sub, caller_kind, client_id become columns; other keys go to identity. Runs before the tool; events recorded during the call get the same three values. Runs again after the tool, for kept calls, when that first answer was empty (no keys, only None values, or a failed run) or lacks a key in late_identity_keys; a missing column alone does not trigger it. The row takes the second answer’s values where the first had none. See Tools that create the caller’s identity.
late_identity_keys()Identity keys that may only exist once the tool has run (a client id a registration creates). A first answer without one of them gets the second run. Empty by default, so a resolver that answers anything runs once unless you list keys here.
enricherNone(tool, args, result, context) -> dict, may be async. Output goes to extra, except server_version, which fills that column.
server_versionNoneDefault for the server_version column of calls and events.
hook_timeout0.25Seconds an async hook may take before it is skipped for that call. The identity resolver’s first run is before the tool, so this also bounds how long it can delay the tool; its second run overlaps the enricher.
max_queue1000Records waiting for the sinks before new ones are dropped and counted.
batch_size100Records handed to each sink per write.
sink_timeout10.0Seconds one sink write may take.
max_error_chars500Longest error message stored, after redaction.
recent_calls2000Call records kept in memory for feedback linking, including ones still queued.
correlation_timeout1.0Seconds the database lookup in capture_recent_calls may take.
result_classifierDEFAULT_RESULT_CLASSIFIER(tool, result) -> str | None. None turns soft-error detection off. See Classifier.
exclude_tools()Tools never recorded and never linked. The calls themselves are untouched.
sample_ratesNoneTool name to the fraction of its ok calls recorded, in (0, 1]. Other values raise ValueError. Failures are always recorded.
randomrandom.random() -> float in [0, 1) deciding sampling; a call is kept when it returns less than the rate. For tests.
recent_events2000Events kept in memory for events_for.
capture_llm_textFalseStore prompt and completion passed to record_llm_call.
max_llm_text_chars8 * max_error_charsLongest prompt or completion stored.
max_payload_bytes65536Largest arguments and result stored in full mode, and largest event attrs, in bytes of JSON. Larger values are stored as {"_truncated": true, "size": ..., "preview": ...}, after redaction; in attrs only the largest values are replaced. None for no limit; other values must be a positive int. See Payload size limit.
MethodReturnsDescription
record_event(kind, *, key=None, attrs=None, user_sub=None, call_id=None, caller_kind=None, client_id=None)boolRecord an event. Inside a tool call, call_id, session and the three identity fields default to the call’s. Synchronous, safe from any thread, never raises or blocks. False when not recorded: mode off, kind empty or over 128 characters, key over 255 characters, attrs not a mapping, a full queue, no event loop, or after aclose().
record_llm_call(*, model, provider=None, duration_ms=None, input_tokens=None, output_tokens=None, ok=None, error=None, key=None, attrs=None, prompt=None, completion=None)boolRecord an llm.call event. See Record LLM calls.
MethodReturnsDescription
events_for(key, *, kinds=None, limit=1000)list[dict]A key’s events, oldest first, the newest limit of them. Reads the DatabaseSink plus events still queued; without one, memory only. occurred_at is a UTC datetime.
capture_recent_calls(ctx=None, n=20, *, user_sub=None, window=timedelta(minutes=15))list[CallLink]Up to n calls that led up to now, chronological: same session first, then same user_sub within window. ctx is looked up when omitted; user_sub is asked of the identity resolver when omitted. Never raises; [] on failure.
link_feedback(feedback_ref, links)boolStore links for a feedback id of any format, replacing earlier ones. Needs a DatabaseSink. False instead of raising.
feedback_context(feedback_ref)list[dict]Linked calls in order, with call columns filled from the database or from memory for calls not yet written. Keys: call_id, position, rule, tool, started_at, duration_ms, ok, outcome, error_type, error_message, session_id, user_sub, caller_kind, server_version, extra. [] without a DatabaseSink.
similar(text, *, source_types=None, k=10, min_score=None)list[dict]Embedded texts most like text, best first. Needs an EmbeddingSink. Never raises.
similar_feedback(feedback_ref, *, k=10, source_types=None, min_score=None)list[dict]Texts most like an embedded feedback item, excluding the item. [] until it is embedded. Never raises.

Each similar result has source_type, source_id, text, score (1 minus cosine distance, in [0, 1]) and created_at.

MethodDescription
flush()Wait until queued records have been handed to the sinks, including ones queued while it waits. Does not wait for an EmbeddingSink’s own queue; use mw.embedding_sink.flush() for that.
aclose()Flush, stop the background task, and close every sink that has aclose. Call on server shutdown. Idempotent: a second call does nothing. Afterwards the middleware is closed for good: tool calls still run, but their records and any record_event, from the loop or a thread, are dropped and counted in dispatcher.dropped and dispatcher.drop_reasons["dispatcher closed"] (one warning), never written, and not kept in memory for linking or events_for. A record a thread handed over just before is delivered if it lands during the flush, else dropped the same way. Since 2026.10.05.
NameDescription
database_sinkThe first DatabaseSink among the sinks, or None.
embedding_sinkThe first EmbeddingSink among the sinks, or None.
redactorThe Redactor in use.
modeThe resolved mode.
dispatcherThe RecordDispatcher. dispatcher.dropped counts records dropped (full queue, no event loop); dispatcher.sink_errors counts failed sink writes.
NameValue
MODES("off", "meta", "full")
MODE_ENV_VAR"FEEDBACK_INSTRUMENTATION_MODE"
DEFAULT_TABLE_PREFIX"ffb_"
DEFAULT_EMBEDDING_DIM1024
EMBEDDING_SOURCES("feedback", "call_error", "event", "llm")
DEFAULT_EVENT_TEXT_KEYS("error_excerpt", "error", "message", "reason")