Observability

Почему одного terminal log мало

Если агент что-то сделал, но команда не может восстановить ход событий, это не production workflow. Terminal dump помогает только тому, кто был рядом. Reviewer'у, incident owner и следующему run нужны structured events, session trace и короткий run summary.

Что логировать с первого дня

Минимальный event stream:

Event	Что фиксирует
task_selected	Какая задача запущена и почему она ready.
context_built	Какие docs и constraints попали в prompt.
agent_started	Backend, model, sandbox, permissions.
tool_call	Команды, файлы, внешние обращения, результат.
diff_created	Какие файлы изменены.
check_started	Какие checks запускаются.
check_failed	Exit code, stderr summary, failure category.
result_classified	done, needs_review, blocked или failed.

Для более зрелого harness events удобно группировать в trace:

run trace
  task span
  context span
  model call span
  tool call span
  check span
  review span

Каждый span должен иметь start/end time, status, cost или duration, input/output summary, error category и ссылку на artifact, если полный payload нельзя хранить в log из-за privacy.

Как это выглядит в реальном run

Ниже — сокращённый фрагмент настоящего JSONL log из lab-цепочки: harness v03 строит ALGI clinician report через policy gate (examples/harness-labs/, задача algi-02-clinician-report):

{"ts": "...T10:32:55.417Z", "event": "task_loaded", "task_id": "algi-02-clinician-report", "title": "Build ALGI clinician report slice"}
{"ts": "...T10:32:55.417Z", "event": "workspace_selected", "workspace": "/tmp/algi-ch03", "policy": ".../policies/local-dev.json"}
{"ts": "...T10:32:55.417Z", "event": "context_ready", "files": ["specs/pain-diary.bdd.md", "AGENTS.md", "algi/domain.py", "tests/test_domain.py"]}
{"ts": "...T10:32:55.417Z", "event": "backend_started", "backend": "scripted", "fixture": "../fixtures/algi-clinician-summary"}
{"ts": "...T10:32:55.418Z", "event": "policy_check", "action": "write_file", "path": "algi/domain.py", "allowed": true, "reason": "allowed workspace path"}
{"ts": "...T10:32:55.419Z", "event": "file_written", "path": "algi/domain.py", "bytes": 2773}
{"ts": "...T10:32:55.419Z", "event": "policy_check", "check": "unit tests", "command": ["python3", "-m", "unittest", "discover", "-s", "tests"], "allowed": true, "reason": "allowed by prefix"}
{"ts": "...T10:32:55.419Z", "event": "check_started", "check": "unit tests"}
{"ts": "...T10:32:55.501Z", "event": "check_finished", "check": "unit tests", "exit_code": 0}
{"ts": "...T10:32:55.502Z", "event": "result_classified", "result": "done", "reason": "all checks passed"}

По одному этому фрагменту reviewer может ответить на вопросы, которые обычно приходится вытаскивать из чата: какая задача была запущена, какой context попал в run, какие writes прошли policy, какие checks запускались и почему выбран result. Это и есть evidence chain из главы Оценка harness.

Называйте тип сбоя

Сбой без категории трудно чинить. Полезно различать:

• tool failure;
• sandbox failure;
• context failure;
• spec failure;
• test failure;
• integration failure;
• permission failure;
• model behavior failure;
• human decision needed (нужно решение человека).

Отдельный useful check для agents с user communication: promise-action consistency. Если agent написал пользователю «я создал refund», «я отправил email» или «я обновил запись», log должен подтверждать tool call и successful external state. Иначе это false promise, даже если текст выглядит вежливо и уверенно.

Что должно попасть в run summary

Run summary должен отвечать на вопросы:

• что пытались сделать;
• какой context использовался;
• какие изменения внесены;
• какие checks прошли или упали;
• почему выбран outcome;
• что делать дальше.

На что не соглашаться

• Логи только как raw terminal dump.
• Нет связи между task, prompt, diff и checks.
• Отсутствие failure category.
• Скрытые retries без истории.
• Невозможно понять, какие permissions были у run.

Что сделать руками

Разберите один agent run по логам и заполните шаблон run summary. Если summary нельзя заполнить без воспоминаний автора, observability пока недостаточно.