From 0eeaf4cb79ff017ded99094216ff675419f3721a Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Sat, 7 Mar 2026 10:08:42 -0500 Subject: [PATCH] Add Logs Directory reference page to docs Co-Authored-By: Claude Opus 4.6 --- docs/docs.json | 1 + docs/reference/logs-directory.mdx | 138 ++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 docs/reference/logs-directory.mdx diff --git a/docs/docs.json b/docs/docs.json index 805d7b7f5..5fb0de484 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -79,6 +79,7 @@ "reference/dot-language", "reference/cli", "reference/cli-configuration", + "reference/logs-directory", "reference/architecture", "administration/advanced-setup", "administration/security" diff --git a/docs/reference/logs-directory.mdx b/docs/reference/logs-directory.mdx new file mode 100644 index 000000000..d9c968ad7 --- /dev/null +++ b/docs/reference/logs-directory.mdx @@ -0,0 +1,138 @@ +--- +title: "Logs Directory" +description: "Structure of Arc's local logs directory" +--- + +Arc writes all local run data to `~/.arc/logs/`. This directory contains daily CLI log files and a subdirectory for each workflow run. + +## Daily log files + +The CLI appends tracing output to a daily log file: + +``` +~/.arc/logs/2026-03-07.log +``` + +The log level defaults to `info`. Set `ARC_LOG=debug` or pass `--debug` for verbose output including HTTP connection pool diagnostics. + +## Run directories + +Each `arc run start` invocation creates a timestamped directory: + +``` +~/.arc/logs/arc-run-20260307-143022/ +``` + +The naming format is `arc-run-YYYYMMDD-HHMMSS`. You can override the location with `--logs-dir`. + +### Root-level files + +| File | Format | When written | Description | +|---|---|---|---| +| `manifest.json` | JSON | Run start | Run metadata — `run_id`, `workflow_name`, `goal`, `start_time`, `node_count`, `edge_count`, `run_branch`, `base_sha`, `labels` | +| `graph.dot` | DOT | Run start | Copy of the workflow graph | +| `run.pid` | Text | Run start | Process ID of the running CLI process. Presence indicates the run is active; an orphaned file indicates a crash. | +| `run.toml` | TOML | Run start | Copy of the original workflow file (only when the workflow is defined in TOML) | +| `progress.jsonl` | JSONL | Continuous | Event stream — one JSON object per line for every significant event (stage starts, completions, tool calls, retries, etc.). See [Observability](/execution/observability) for the full event catalog. | +| `live.json` | JSON | Continuous | Current execution state snapshot, overwritten on each event. Used for live monitoring. | +| `checkpoint.json` | JSON | After each node | Crash recovery state — `current_node`, `completed_nodes`, `node_retries`, `context_values`, `node_outcomes`, `next_node_id`, `git_commit_sha`, failure signatures. See [Checkpoints](/execution/checkpoints). | +| `conclusion.json` | JSON | Run end | Final result — `status`, `duration_ms`, `failure_reason`, `final_git_commit_sha`. Only present when the run completes (not for crashed or interrupted runs). | +| `final.patch` | Diff | Run end | Git diff from `base_sha` to final HEAD. Only present in git checkpoint mode. | +| `retro.json` | JSON | Run end | Post-run retrospective analysis — `smoothness_rating`, `learnings`, `friction_points`, `stages`. Omitted if `--no-retro` is passed. See [Retros](/execution/retros). | + +### `nodes/` subdirectory + +Each node execution writes artifacts into `nodes/{node_id}/`. When a node is retried, subsequent visits use `nodes/{node_id}-visit_{N}/` (where N starts at 2). + +Every node gets a `status.json` after completion containing `status`, `notes`, `failure_reason`, and `timestamp`. The remaining files depend on the handler type: + +**Agent and prompt nodes:** + +| File | Description | +|---|---| +| `prompt.md` | The full prompt sent to the LLM | +| `response.md` | The LLM's response text | +| `status.json` | Execution status with routing outcome | + +**Command nodes:** + +| File | Description | +|---|---| +| `script_invocation.json` | Command metadata — `command`, `language`, `timeout_ms` | +| `stdout.log` | Standard output | +| `stderr.log` | Standard error | +| `script_timing.json` | Timing info — `duration_ms`, `exit_code`, `timed_out` | + +**Nodes with git checkpointing:** + +| File | Description | +|---|---| +| `diff.patch` | Git diff of changes made during this stage | + +**Manager loop nodes:** + +Manager nodes that run sub-workflows write a nested `child/` directory containing a full run structure (manifest, checkpoint, nodes, etc.). + +### Other directories + +**`worktree/`** — When running in git checkpoint mode, Arc creates a Git worktree here as the working directory for agents and commands. + +**`assets/`** — Test artifacts collected from the execution environment (Playwright reports, JUnit XML, Cypress screenshots/videos). Located at `worktree/assets/` for local runs or within node directories for remote sandbox runs. + +## Browsing runs + +Use `arc run list` to scan the logs directory and display a table of all runs with their status, workflow name, and timestamps. Pass `--json` for machine-readable output. + +```bash +arc run list +arc run list --json +arc run list --filter workflow=my-workflow +``` + +## Full directory tree + +``` +~/.arc/logs/ +├── 2026-03-07.log # Daily CLI log +├── arc-run-20260307-143022/ # One directory per run +│ ├── manifest.json +│ ├── graph.dot +│ ├── run.pid +│ ├── run.toml +│ ├── progress.jsonl +│ ├── live.json +│ ├── checkpoint.json +│ ├── conclusion.json +│ ├── final.patch +│ ├── retro.json +│ ├── nodes/ +│ │ ├── plan/ +│ │ │ ├── prompt.md +│ │ │ ├── response.md +│ │ │ └── status.json +│ │ ├── work/ +│ │ │ ├── prompt.md +│ │ │ ├── response.md +│ │ │ ├── status.json +│ │ │ └── diff.patch +│ │ ├── work-visit_2/ # Retry of "work" node +│ │ │ ├── prompt.md +│ │ │ ├── response.md +│ │ │ ├── status.json +│ │ │ └── diff.patch +│ │ ├── test/ +│ │ │ ├── script_invocation.json +│ │ │ ├── stdout.log +│ │ │ ├── stderr.log +│ │ │ ├── script_timing.json +│ │ │ └── status.json +│ │ └── manager/ +│ │ ├── status.json +│ │ └── child/ +│ │ ├── manifest.json +│ │ ├── checkpoint.json +│ │ └── nodes/ +│ ├── worktree/ # Git worktree (git checkpoint mode) +│ │ └── assets/ # Test artifacts +│ └── assets/ # Or here for remote sandboxes +```