Skip to main content

​
Command overview

beacon endpoint traces reads the Beacon runtime JSONL log as traces: one per session or OpenTelemetry trace, with its events in order. Use it when you want a trace-oriented view of endpoint activity without starting the dashboard. Run the top-level command on an interactive terminal to open the full-screen local trace browser:
Browse local traces
Use the arrow keys or j/k to move, enter to open a trace, / to search, and 1–4 to filter an open trace by event type. Page Up and Page Down scroll long event details. The browser reads only local Beacon state and does not contact the network. When stdout or stdin is redirected, beacon traces falls back to a bounded tab-separated trace list instead of emitting terminal control sequences. The beacon endpoint traces commands below remain the stable JSON and scripting interface.
Command syntax
The commands read local files only and do not contact the network. Plain-text list, search, and show metadata rows collapse line breaks, tabs, and other whitespace to single spaces so each result stays on one row. JSON output retains the original text, and show keeps multiline text and commands in its indented event details.

​
Local history

The runtime log rotates after about 60 MB, which is a day or two of activity on a busy machine. Without a local history, trace commands can only see what is still in the log. The local history is a SQLite file, ~/.beacon/endpoint/history.db, that keeps sessions after the log rotates them away. Every trace command catches it up with the log before answering, so it needs no background service. It also makes search faster, since it keeps a full-text index of the same text the commands search. It is off until you turn it on:
  • The first beacon endpoint traces or beacon traces command on an interactive terminal asks once whether to create it. “Not now” is remembered.
  • beacon endpoint traces reindex creates it without asking.
  • Commands run by scripts, agents, pipes, --json or CI are never asked. They read the log and print a one-line note on stderr.
What it holds:
  • The same prompts, commands, output and file changes the runtime log holds, after the same redaction. The runtime’s raw payload is dropped except for the few fields trace summaries read.
  • Nothing leaves the machine. The file is readable only by you (mode 0600).
  • Traces whose last event is older than 90 days are removed, and the oldest traces are removed once the file reaches 1 GB. Change either with reindex --retention-days and reindex --max-size-mb.
If the log rotates more than five times between two trace commands, the files in between are deleted before the history reads them. status reports this as a gap. beacon endpoint traces reset deletes the history. beacon endpoint uninstall deletes it along with the runtime logs, unless you pass --keep-logs. Set BEACON_HISTORY_DB to keep the history somewhere else. For assistant message and reasoning events, an event’s content.text is the text retained in gen_ai.output.messages: what the assistant said, or its reasoning. The event’s label, such as Codex assistant message, stays in summary, and fills content.text only when the event retained no text. The retained text went through Beacon’s redaction and size limits when it was written, and content.redacted and content.truncated report either change. beacon memory evaluates traces from this same view.

​
Commands

​
Flags

All commands accept: list, search, and show also accept: list also accepts: search also accepts: reindex also accepts: show also accepts: With --event-type, --around-event still takes the original event number, and --before and --after count matching events.

​
Examples

Check the local history
Create the local history, keeping 30 days
List recent traces
Search event text
Show a focused event window

Local dashboard

Inspect the same local endpoint activity in the loopback dashboard.

Local JSONL

Understand the runtime log that traces and the local history are read from.