Inspect traces

See which tools ran, how long they took and where a request failed. Flow can send runtime events to your own system or export traces to Flow Observe.

Trace a conversation

Use an EventSink to send events to your logs or observability system. Events include messages, turns, model calls, tool calls and schedules.

Event sink

import type { EventSink } from "@flow-engineer/flow";

const log: EventSink = (event) => {
  console.log(event.type, event.conversationId, event.at);
};
// Pass events: [log] when creating the agent.

An event sink must not throw. jsonlSink(path) is available for writing events to a local file. To export OTLP/JSON traces, set the following on the agent’s host:

Trace configuration

FLOW_FRAMEWORK_TRACES_KEY=your_trace_key
FLOW_FRAMEWORK_TRACES_URL=https://flow.engineer/observe

Metadata is exported by default. Set FLOW_FRAMEWORK_TRACES_CONTENT=1 to include message content. Scenario-test traces carry a test run marker so the dashboard can distinguish them from production. Check it worked: send a message that calls a tool, then find the turn and its tool span in your trace backend. Raw event sinks may contain message and tool content regardless of the trace content flag; apply your own access and retention controls.

Tool-call traces

MCP, plugin and CLI calls emit tool.start and tool.end events with their surface, client name and version, session, person, duration, outcome and error. mcpServer uses the same FLOW_FRAMEWORK_TRACES_* environment settings. Explicit traces options override them; traces: false stops trace export without disabling event sinks.

What an MCP or CLI trace contains

Each call is a root trace without a conversation. Arguments and results are included only with FLOW_FRAMEWORK_TRACES_CONTENT=1. await handle.flushTraces() flushes the bounded background queue.CLI calls send the command and an idempotency key in _meta; the caller can reuse its key on a retry. defineCli sends its version (default "1"). CLI arguments and trace credentials are not placed in _meta.Legacy client initialization metadata is retained for at most 24 hours and 4,096 sessions. Bearer tokens are never cached.

Test a failure

Reproduce a conversation with a scenario test.

Run your own infrastructure

Configure persistence and restart behavior.

Get started

Build

Ship to

Agent Features

Run in production

Inspect traces

Trace a conversation

Tool-call traces

Test a failure

Run your own infrastructure

​Trace a conversation

​Tool-call traces

Test a failure

Run your own infrastructure

Trace a conversation

Tool-call traces