Skip to content

Records

Sinks receive batches that mix two dataclasses, ToolCallRecord and EventRecord. Tell them apart with isinstance or record.record_type ("tool_call" or "event"). Both have to_row() (column values) and to_dict() (JSON-friendly, timestamp as ISO 8601).

from fastmcp_feedback.instrumentation import EventRecord, ToolCallRecord

One tool call, built after the tool returns or raises.

FieldTypeDescription
idstrRandom UUID, chosen before the tool runs so events recorded inside it can carry it. Primary key of ffb_tool_calls.
toolstrTool name as called.
started_atdatetimeUTC, when the middleware saw the call.
duration_msfloatWall time through the middleware chain below this one, including the tool.
okbooloutcome == "ok".
outcomestr"ok", "soft_error" (a result the classifier flagged) or "error" (the tool raised).
modestr"meta" or "full"; "meta" for tools in meta_only_tools.
error_typestr | NoneException class name (the original cause, not FastMCP’s ToolError wrapper), or "SoftError".
error_messagestr | NoneRedacted, cut to max_error_chars. For soft errors, the classifier’s string, such as status=failed: disk full.
session_idstr | NoneThe session key: HTTP mcp-session-id, a per-process key on stdio, else FastMCP’s ctx.session_id.
request_idstr | NoneThe MCP request id.
client_idstr | NoneFrom the identity resolver, else FastMCP’s ctx.client_id.
user_substr | NoneFrom the identity resolver: its run before the tool, with gaps filled from a second run after it when the first answer was empty or lacked a late_identity_keys key.
caller_kindstr | NoneFrom the identity resolver, as user_sub.
identitydictOther identity resolver keys, redacted, merged the same way.
server_versionstr | NoneFrom the enricher, else the middleware’s server_version.
args_sizeint | NoneBytes of the JSON-encoded arguments, before redaction.
result_sizeint | NoneBytes of the JSON-encoded result payload, before redaction. None when the tool raised.
argsAnyRedacted arguments in full mode, else None. Over max_payload_bytes, a truncation marker.
resultAnyRedacted result payload in full mode, else None. The payload is the structured content when present, otherwise the content items. Over max_payload_bytes, a truncation marker.
extradictEnricher output, redacted.
sample_ratefloat | NoneThe tool’s rate on sampled-in ok rows; None for everything recorded unconditionally.

One event from record_event or record_llm_call.

FieldTypeDescription
idstrRandom UUID. Primary key of ffb_events.
kindstrDotted name, at most 128 characters.
occurred_atdatetimeUTC, when record_event was called.
keystr | NoneJoin key, at most 255 characters.
call_idstr | NoneThe running call’s id when recorded inside a tool call, or the call_id passed in.
session_idstr | NoneThe running call’s session key, inside a call.
user_substr | NoneAs passed to record_event; otherwise, inside a tool call, the call’s user_sub from the identity resolver.
caller_kindstr | NoneAs passed; otherwise, inside a call, the call’s caller_kind.
client_idstr | NoneAs passed; otherwise, inside a call, the call’s client_id (the resolver’s, else FastMCP’s ctx.client_id).
server_versionstr | NoneThe middleware’s server_version.
attrsdictRedacted and made JSON-safe: NaN and infinities become strings, datetimes ISO strings, unknown types str(value). Over max_payload_bytes, the largest values become truncation markers until it fits.

A stored value larger than the middleware’s max_payload_bytes (64 KiB by default) is replaced by:

{"_truncated": true, "size": 812345, "preview": "{\"frames\": [[0.1, 0.2], ..."}
KeyMeaning
_truncatedAlways true. Test for it with is_truncated(value) from fastmcp_feedback.instrumentation.payload.
sizeThe value’s JSON size in bytes, as args_size and result_size measure it.
previewThe start of its JSON text, after redaction: 1000 characters, or a quarter of max_payload_bytes when that is smaller.

The keys and their meaning are stable. For call payloads the whole args or result becomes the marker; for event attrs only the largest values do, so the other keys stay in place. In SQL: json_extract(attrs, '$.error._truncated') on SQLite, attrs->'error'->>'_truncated' on Postgres. Since 2026.10.04.

KindRecorded bykeyattrs
feedback.submittedsubmit_feedback with instrumentation=feedback idtype, title, description, submitter
llm.callrecord_llm_callas passedmodel, ok, and provider, duration_ms, input_tokens, output_tokens, error, error_type, prompt, completion when present

Returned by capture_recent_calls, one per linked call.

FieldTypeDescription
call_idstrThe call’s id.
rulestr"session" or "user_window": why it matched.
toolstrTool name.
started_atdatetimeUTC.
okboolThe call’s ok.
positionintOrder within the link set, from 0, oldest first.

JsonLinesSink writes {"record": record_type, **record.to_dict()} per record. A call line:

{"record": "tool_call", "tool": "render", "started_at": "2026-10-02T03:44:16.471791+00:00",
"duration_ms": 0.51, "ok": false, "mode": "full", "outcome": "soft_error",
"id": "25568541-cf28-472c-9537-3151d7d21be7", "error_type": "SoftError",
"error_message": "status=failed: out of memory", "session_id": "fd6283b1-7dd9-411c-b3fb-838a9c38330a",
"request_id": "4", "client_id": null, "user_sub": "dev", "caller_kind": null,
"identity": {"team": "render"}, "server_version": null, "args_size": 16, "result_size": 46,
"args": {"scene": "big"}, "result": {"status": "failed", "error": "out of memory"},
"extra": {}, "sample_rate": null}