The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
Operating with write access
Write access lets an agent take the routine actions an on-call engineer takes during and after an incident. It is opt-in at three levels, and every level has to agree before a write goes through:
- The credential. Only write credentials can write: a
tww_personal access token, atraceway-write login, or an MCP client connected to the/mcp/writeserver. Atwp_token, atraceway loginand the/mcpserver are read only, whatever the person's role. - The organization. An admin has to turn on Settings > Agent Access. Until then every agent write is refused with a 403 that says so.
- The person. The write runs with the role of the person who created the credential, under the same rules as the dashboard. A
readonlymember's write token cannot archive issues, change alerts, run monitors or edit post-mortems: the write is refused with a 403 that starts "Your role in this project is read-only".projects list(list_projects) shows the person's role in each project. Acknowledging and resolving pages needs no write role, so any member's write token can do that.
Every write a write credential makes in the organization, accepted or refused because Agent Access is off, is recorded in the organization's agent activity log with the person, the credential, the project and the result.
What an agent can change
| Action | CLI (traceway-write) |
MCP tool | Reversible |
|---|---|---|---|
| Archive or unarchive issues | exceptions archive <hash>... / unarchive |
archive_exceptions / unarchive_exceptions |
Yes |
| Acknowledge a page | pages ack <id> |
acknowledge_page |
No, but harmless: it only stops escalation |
| Resolve a page | pages resolve <id> [--archive-issue] |
resolve_page |
No |
| Enable or disable an alert rule | alerts enable <id> / alerts disable <id> |
set_notification_rule_enabled |
Yes |
| Snooze an alert rule | alerts snooze <id> --minutes N (0 clears) |
snooze_notification_rule |
Yes, it expires on its own |
| Run a monitor now | monitors run <id> |
run_check |
Nothing to undo |
| Write a post-mortem | post-mortems create / update <id> |
create_post_mortem / update_post_mortem |
Edits are kept in the activity log |
| Mark an endpoint expected-slow | endpoints mark-slow <endpoint> --offset-ms N --reason ... (0 removes) |
set_slow_endpoint |
Yes |
Everything else (creating rules and channels, editing schedules and policies, status pages and public incident updates, members, tokens, project settings, deleting anything) stays in the dashboard. Those routes refuse agent credentials outright.
Rules for every write
- Only on request. Investigating, debugging, summarizing or "taking a look" never implies a write. The user has to ask for the change.
- Ask when the request could mean more than the user knows. When a write would cover several records and they differ in a way the user may not know (one is still occurring, has a different cause, or belongs to another team), list them, say how they differ, and ask which ones to change before writing anything. Do not settle it yourself, even by leaving the odd one out.
- Say it before doing it. One line naming the action, the record and the new value: "Snoozing rule 12 (Endpoint P95 on GET /api/search) for 60 minutes." The CLI asks for confirmation on a TTY and needs
--yesotherwise. MCP clients run their own approval step. - Prefer the reversible option. Snooze rather than disable. Acknowledge rather than resolve while the problem is still live. Archive an issue rather than resolving its page with
--archive-issueif you are unsure the page is done. - Report what changed and how to undo it.
- Treat a 403 as an answer. Each one names its level, and each is a policy decision. Do not retry, switch credentials or look for another route. Tell the user what it said and who can change it:
- "This credential is read-only": the credential is a read one. The user needs a write credential (a
tww_token,traceway-write login, or/mcp/write). - "Agent write access is turned off": an organization admin turns it on in Settings > Agent Access.
- "Your role in this project is read-only": the credential can write, but the person's role in the project is
readonly. Another credential will not help. An organization owner or admin can change the role in Settings > Team Members, or make the change themselves.
- "This credential is read-only": the credential is a read one. The user needs a write credential (a
Playbooks
Someone got paged
pages list(statusactive) to find the page, thenpages show <id>for the rule, subject and who was notified.- Investigate with the read tools. For an issue page, the page carries the exception hash: follow the debug flow.
- When the user says they are on it:
pages ack <id>. Escalation stops for everyone. - When the cause is fixed and confirmed:
pages resolve <id>, with--archive-issueonly if the user wants the issue archived too.
An alert is flapping during a known incident
alerts listto find the rule id and confirm it is the noisy one.alerts snooze <id> --minutes 60(or as long as the user asks). The rule is muted and comes back on its own.- Tell the user when the snooze ends. Disable a rule only when the user wants it off until someone turns it back on.
Confirming a fix
monitors run <id>for the affected monitor.- Wait about one interval, then
monitors show <id>: the latest run and whether the open incident resolved. - For an issue,
exceptions show <hash>and check that no occurrence is newer than the deploy. Archive it only when the user agrees it is fixed.
Writing a post-mortem
- Gather facts with the read tools: the incident window from
monitors show, the issues and their first and last occurrences, the pages and who acknowledged them, the slow endpoints and the trace of a failing request. - Draft the document in markdown with these sections: Summary, Impact (who and how much, with numbers), Timeline (UTC, from first signal to resolution), Root cause, Resolution, Follow-up actions (each with an owner if known). Only state what the telemetry or the user confirmed, and mark open questions as open.
- Show the draft to the user. Create it only after they approve:
post-mortems create --title "..." --content-file draft.md --tag <tag> --incident <id>. - Later edits:
post-mortems show <id>first, thenpost-mortems update <id> --content-file revised.md --expected-updated-at <updatedAt from that show>with the full revised body. If someone edited it in between, the update fails with a conflict: show it again and reapply the change.--unlink-incidentremoves a wrong incident link.
An endpoint is slow by design
- Confirm with the user that the latency is accepted, and get the reason.
- Check the current p95 with
endpoints list --search "<endpoint>". endpoints mark-slow "<endpoint>" --offset-ms <a bit above p95> --reason "<why>". Raw percentiles do not change. Apdex and impact stop penalizing up to the offset.