> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# beacon endpoint traces

> Index and search local endpoint traces from Beacon runtime logs

## Command overview

`beacon endpoint traces` builds and reads a local trace index over the Beacon runtime JSONL log. Use it when you want a trace-oriented view of endpoint activity without starting the dashboard.

```bash title="Command syntax" theme={null}
beacon endpoint traces [command]
```

The index is local SQLite state derived from `runtime.jsonl`. Rebuilding it does not change the runtime log, and the command does not contact the network.

## Commands

| Command | Description |
| - | - |
| `beacon endpoint traces status` | Show the trace-store path, indexed trace count, event count, index rows, size, and last index time |
| `beacon endpoint traces reindex` | Rebuild the trace store from the current runtime JSONL log |
| `beacon endpoint traces list` | List local traces with harness, update time, and title |
| `beacon endpoint traces search <pattern>` | Search trace metadata or indexed event text |
| `beacon endpoint traces show <trace-id>` | Show events from one trace |

## Flags

All commands accept:

| Flag | Description |
| - | - |
| `--json` | Print results as JSON |
| `--log-path <path>` | Runtime JSONL log path. Defaults to the resolved endpoint log |
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths |

`list`, `search`, and `show` also accept:

| Flag | Description |
| - | - |
| `--limit <n>` | Limit returned traces or events. Defaults to `100` |
| `--event-type <types>` | Filter trace events by comma-separated event type |

`list` also accepts:

| Flag | Description |
| - | - |
| `--query <text>`, `-q <text>` | Filter traces by text |
| `--page <n>` | Page number for trace listing. Defaults to `1` |
| `--state <state>` | Filter by sharing state |
| `--visibility <visibility>` | Filter by sharing visibility |

`search` also accepts:

| Flag | Description |
| - | - |
| `--result-level trace` | Return matching traces. This is the default |
| `--result-level event` | Return matching events with snippets |

`show` also accepts:

| Flag | Description |
| - | - |
| `--offset <n>` | Start at this event number. Defaults to `1` |
| `--around-event <n>` | Center output around this event number |
| `--before <n>` | Events before `--around-event`. Defaults to `3` |
| `--after <n>` | Events after `--around-event`. Defaults to `3` |

## Examples

```bash title="Check the trace index" theme={null}
beacon endpoint traces status
```

```bash title="Rebuild from runtime JSONL" theme={null}
beacon endpoint traces reindex
```

```bash title="List recent traces" theme={null}
beacon endpoint traces list --limit 20
```

```bash title="Search event text" theme={null}
beacon endpoint traces search "npm install" --result-level event
```

```bash title="Show a focused event window" theme={null}
beacon endpoint traces show <trace-id> --around-event 42 --before 5 --after 10
```

## Related

<Columns cols={2}>
  <Card title="Local dashboard" icon="chart-line" href="/cli/dashboard">
    Inspect the same local endpoint activity in the loopback dashboard.
  </Card>

  <Card title="Local JSONL" icon="file-lines" href="/log-forwarding/local-jsonl">
    Understand the runtime log that the trace index is derived from.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.