Repository navigation
docs: update Agent Relay SIEM alert messages for v0.15.0 - #31985
Conversation
| | `build_status` | The latest build's status when Agent Relay rebuilds a workspace or the reaper evaluates it | | ||
| | `deadline` | Claude Code: when Anthropic stops waiting for a runner. Logged when the deadline passes before dispatch. | | ||
| | `status` | Reaper: the runner status the workspace reported, such as `working`, `done 1`, `failed <reason>`, or `orphaned` | | ||
| | `agent_lifecycle` | The workspace agent's lifecycle state, such as `starting` or `ready`, on `workspace built, runner handoff` and reaper records. Empty when no agent is connected. `starting` means startup scripts are still running, and `start_error` or `start_timeout` means they failed. | |
There was a problem hiding this comment.
Blocking: This locates agent_lifecycle by quoting workspace built, runner handoff as the lookup key, but the page's own "Match rules" section a few headings down says msg text can change between Agent Relay releases and warns readers not to rely on it that way. Tying the field's provenance to an unstable msg string is evidence (which code path emits it), not the reader-facing fact of when the field is present (docs/.style/content-guidelines.md#evidence-justifies-a-claim-and-does-not-belong-in-the-claim). (Reader Advocate)
Separately, in the same cell, "start_error or start_timeout means they failed" has no clean antecedent for "they": the clause-2 subject (start_error/start_timeout) is singular and isn't itself the thing that "failed," so the reader has to reach back into the prior clause's object ("startup scripts") to resolve it (docs/.style/style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent). (Copy Editor)
Combining both fixes:
| | `agent_lifecycle` | The workspace agent's lifecycle state, such as `starting` or `ready`, on `workspace built, runner handoff` and reaper records. Empty when no agent is connected. `starting` means startup scripts are still running, and `start_error` or `start_timeout` means they failed. | | |
| | `agent_lifecycle` | The workspace agent's lifecycle state, such as `starting` or `ready`, present once a workspace finishes building and on every reaper record. Empty when no agent is connected. `starting` means startup scripts are still running, and `start_error` or `start_timeout` means the scripts failed. | |
| | Rate threshold | `workspace build failed, reporting retryable and deleting` | Both | `job_error` | A template or infrastructure failure, such as exhausted quota. Agent Relay deletes the workspace right away, so `job_error` might be the only record of why. | | ||
| | Rate threshold | `workspace build passed the session deadline, reporting retryable and deleting` | Both | `pool` | Builds take longer than the pool's `dispatch_deadline`. | | ||
| | Rate threshold | `workspace build failed` | Both | `job_error` | A template or infrastructure failure, such as exhausted quota. Agent Relay deletes the workspace right away, so `job_error` might be the only record of why. | | ||
| | Rate threshold | `workspace build passed the session deadline, reporting failure` or `workspace build succeeded after the session deadline` | Both | `pool` | Builds take longer than the pool's `dispatch_deadline`. | |
There was a problem hiding this comment.
Blocking: This row now lists two different outcomes under one "Why": workspace build passed the session deadline, reporting failure (a failure) and the new workspace build succeeded after the session deadline (the build actually finished, just late). Two problems with that:
docs/agent-relay/claude-code.md's "Build budget" section still says unconditionally that "When a build misses the budget, Agent Relay reports the failure to Anthropic, cancels the build if it's still running, and deletes the workspace," anddocs/agent-relay/cursor.md's "Build deadline" section still says unconditionally that "When the deadline passes, Agent Relay deletes the workspace and the developer's chat showsagent-relay: workspace build exceeded the spawn budget." Neither page mentions the late-success case this new message implies exists; the oldsiem.mdwording ("...reporting retryable and deleting") matched those pages, the new wording no longer does. (Continuity Editor)- Even within this table, the shared "Why" column ("Builds take longer than the pool's
dispatch_deadline.") doesn't say whether an alert firing on the second value needs the same urgent response as the first, or is only an informational, late-success signal. (Newcomer)
Fix either by adding a sentence to claude-code.md and cursor.md describing the late-success case, or by splitting this row so each msg value has its own "Why" text that says whether it means failure or late success.
Documentation CheckBlocking
Related open PRs
Findings for agents- id: audience-1
persona: audience
class: rule
blocking: true
file: docs/agent-relay/monitoring/siem.md
line: 91
quote: "The workspace agent's lifecycle state, such as `starting` or `ready`, on `workspace built, runner handoff` and reaper records."
evidence:
- docs/agent-relay/monitoring/siem.md:206-211
rule: docs/.style/content-guidelines.md#evidence-justifies-a-claim-and-does-not-belong-in-the-claim
problem: The location clause names provenance (which msg string the field rides on) rather than what the reader does, and ties it to text the page itself warns is unstable between releases.
fix: "present once a workspace finishes building and on every reaper record"
verified: true
- id: language-1
persona: language
class: rule
blocking: true
file: docs/agent-relay/monitoring/siem.md
line: 91
quote: "`starting` means startup scripts are still running, and `start_error` or `start_timeout` means they failed."
evidence: []
rule: style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent
problem: "they" has no clean antecedent in its own clause; the reader must reach into the prior clause's object ("startup scripts") to resolve it.
fix: "`start_error` or `start_timeout` means the scripts failed"
verified: true
- id: consistency-1
persona: consistency
class: rule
blocking: true
file: docs/agent-relay/monitoring/siem.md
line: 228
quote: "`workspace build passed the session deadline, reporting failure` or `workspace build succeeded after the session deadline`"
evidence:
- docs/agent-relay/claude-code.md:220
- docs/agent-relay/cursor.md:199
rule: null
problem: claude-code.md and cursor.md still describe a missed deadline as unconditionally ending in failure and deletion, but the new split msg value implies a build can finish successfully after the deadline; this PR's edit is what exposed that contradiction.
fix: Add a sentence on claude-code.md and cursor.md describing the late-success case, or soften the unconditional "reports the failure ... and deletes" wording.
verified: true
- id: learner-2
persona: learner
class: missing
blocking: true
file: docs/agent-relay/monitoring/siem.md
line: 228
quote: "`workspace build passed the session deadline, reporting failure` or `workspace build succeeded after the session deadline`"
evidence: []
rule: null
problem: The row's shared "Why" column doesn't say whether the late-success message needs the same response as the failure message, so a reader can't tell from this table alone.
fix: Split the row so each msg value has its own "Why" text, or add a sentence distinguishing the two outcomes.
verified: trueAutomated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong. |
3e869c0 to
287e78f
Compare
495be2c to
81e696f
Compare
Agent Relay v0.15.0 made the reaper's 15-minute startup window configurable ([agent-relay#152](coder/agent-relay#152)) and added a reap delay ([agent-relay#134](coder/agent-relay#134)). - `configuration.md`: add `--reap-startup-grace` (Helm `reapStartupGrace`) and `--reap-delay`, plus the per-pool `reap_delay` field, under an intro that says how the two options differ. The Cursor `dispatch_deadline: 0` row now points at the startup grace. - `setup.md`: fix the script-ordering note and **Workspace lifecycle**, which hardcoded 15 minutes and said failed builds are deleted "on the next sweep". **Workspace lifecycle** now states the 30-second gap between sweeps, and **Choose cleanup settings** maps each goal to its setting. - `cursor.md`: fix the **Build deadline** bullet and the `pending` lifecycle row. - `troubleshooting.md`: the "session ended but its workspace remains" row mentions the reap delay. - `monitoring/index.md`: add the `delayed` verdict to `agent_relay_reaper_verdicts_total` and define it as a wait before `delete` or `failed`. Verification notes: - The chart has **no `reapDelay` value** at v0.15.0 (only `reapStartupGrace`; checked `values.yaml` and `templates/_helpers.tpl`), so the docs say to set `CODER_AGENT_RELAY_REAP_DELAY` through `extraEnv`. - Pending or starting builds wait `max(grace, dispatch_deadline)`. A finished build whose runner reports `pending` or nothing fails after the grace alone (`workspacereaper/lifecycle.go`). - The reap delay counts from the latest build's `Job.CompletedAt`, not from the worker's exit, so a session that ran longer than the delay gets no extra time (`reapDeadline` in `workspacereaper/reaper.go`). - `delayed` is only a metric label. A sweep records it when the verdict is `delete` or `failed` but the delay hasn't passed. The `Verdict` type has only `keep`, `delete`, `failed`, and `stuck`. - The reaper sleeps 30 seconds after it sweeps every pool, rather than running on a fixed ticker (`sweepLoop` in `servicereaper/reaper.go`). Stack 2/6. Review and merge in order: - #31834 (merged) - #31984 - #31985 - #31986 - #31987 - #32094 Refs DOCS-1171 > Generated by Coder Agents. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Bobby Ho <bobby@coder.com>
|
I have read the CLA Document and I hereby sign the CLA You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot. |
Match the log messages that Agent Relay v0.15.0 writes, and document the agent_lifecycle field from coder/agent-relay#154.
81e696f to
1143e43
Compare
Updates
monitoring/siem.mdto the log messages Agent Relay v0.15.0 writes.msgmsgworkspace ready, runner handoffworkspace built, runner handoff(agent-relay#154)workspace build passed the session deadline, reporting retryable and deletingworkspace build passed the session deadline, reporting failure(also listsworkspace build succeeded after the session deadline)workspace build failed, reporting retryable and deletingworkspace build faileddelete workspace failed, leaving for reconciliationdelete workspace failed, leaving it for the reaperThe PR also adds the
agent_lifecyclefield, which appears on the handoff record and on reaper records.Verification notes:
msginsiem.mdwas checked by greppinginternal/at9b96578and still matches.leaving for reconciliationdoesn't exist at v0.15.0. Its replacement comes fromDispatcher.deleteWorkspace.Stack 3/6. Review and merge in order:
Refs DOCS-1171