Observability
AMOF provides comprehensive observability across AI agent sessions, workspace operations, and release lifecycle. Every significant action is recorded, costs are tracked, and audit trails are maintained.
Session Telemetry
Every agent session tracks detailed performance and cost metrics in .amof/sessions/<id>/telemetry.json.
| Metric | Description |
|---|---|
| Input tokens | Tokens sent to the LLM (per call and cumulative) |
| Output tokens | Tokens received from the LLM |
| Cost (USD) | Per-call and session-total cost |
| Latency | Per-call response time in milliseconds |
| Provider failures | Consecutive failure count per provider |
| Tool calls | Count and type of each tool invocation |
| Modified files | Set of files changed during the session |
| Guardrail events | user_confirmed and user_rejected counters |
Budget Monitoring
| Threshold | Action |
|---|---|
| 50% | Warning to stderr |
| 75% | Warning to stderr |
| 90% | Critical warning to stderr |
| 100% | Session terminated |
Event Logging
AMOF maintains append-only JSONL event logs for every agent session and run.
Event format
{
"timestamp": "2026-03-03T14:30:00.000Z",
"type": "tool_call",
"content": {"tool": "Write", "path": "src/app.py", "result": "success"},
"level": "info",
"run_id": "abc123",
"ecosystem": "aws-boilerplate"
}| Type | Description |
|---|---|
| llm_request | Request sent to LLM (model, tokens, prompt summary) |
| llm_response | Response received (tokens, cost, latency) |
| tool_call | Tool invocation (name, parameters, result) |
| tool_error | Tool execution failure |
| guardrail_block | Guardrail prevented an action |
| plan_created | Planner produced an execution plan |
| subtask_start | Subtask execution began |
| subtask_complete | Subtask finished |
| budget_warning | Budget threshold crossed |
| session_start | Agent session started |
| session_end | Agent session ended |
Release Audit Trail
Every release action writes a structured record to releases/<tag>.json.
patch --alpha --> patch --alpha --> promote --beta --> promote --rc --> promote
(v1.0.0-alpha.1) (v1.0.0-alpha.2) (v1.0.0-beta.1) (v1.0.0-rc.1) (v1.0.0)Each step writes an audit record, commits version file changes, creates a Git tag, and pushes.
Workspace Auditing
After significant work sessions, audit records are written to ecosystems/<name>/audit/ containing:
- Summary -- What was accomplished
- Goals -- What was intended
- Decisions -- Design decisions and rationale
- Files Changed -- List of modified files with descriptions
- Commands Run -- Notable shell commands executed
- Errors -- Errors encountered and how they were resolved
Diagnostics
amof check
Verifies prerequisites are installed: git, docker, helm, aws, kubectl, python, terraform.
amof troubleshoot
| Area | What It Checks |
|---|---|
| Environment | API keys set, tools installed, .env loaded |
| Workspace | state.json valid, repos synced, branches correct |
| Agent errors | Recent session errors from events.jsonl |
| Configuration | agent.yaml valid, manifest valid, guardrails loaded |
Codebase Index Cost
| Type | Cost | When |
|---|---|---|
| Full index | $0.10 - $0.50 | First run or after major restructuring |
| Incremental index | $0.01 - $0.10 | Normal development (only changed files) |
| No-op | $0.00 | No changes since last index |