Files
crank/docs/observability.md
bsodfather 54ce770682
CI / Rust Checks (pull_request) Failing after 13m41s
CI / UI Checks (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Deploy (pull_request) Skipped
Community Release / release (push) Failing after 13m33s
feat(epic3): deliver the accepted Epic 3 scope through Story 3.17
Recovery delivery of the accumulated, TL-accepted Epic 3 work that had never been
committed to Git (stories 3.6-3.17, see the crank board). Story 3.18 is not accepted
yet and is deliberately excluded: its logging surface, its capability registration,
its oracle projections and its tests are not part of this tree.

Accepted scope
- 3.6 typed static Resource Drafts; 3.7 publication and exact binding of static
  Resource Versions; 3.8 MCP discovery/read and revocation of static Resources;
- 3.9 Resource import/export in API and UI plus TLS dependency maintenance;
  3.10 REST-backed Resource templates; 3.11 shared REST read runtime and the MCP
  revision/capability foundation;
- 3.12 parameterised Prompt Drafts with preview; 3.13 Prompt publication and exact
  version binding to Agents; 3.14 MCP prompts; 3.15 Prompt import/export;
- 3.16 composite Prompts with published Resources (dependency content scan plus
  dynamic read through the accepted 3.11 runtime, admin preview and MCP prompts/get);
- 3.17 bounded MCP completion suggestions from typed published schemas and the
  resources/list admission fix for bound template publications.

Accepted evidence being reused (unchanged code paths)
- 3.16 candidate: core 7, admin-api 22, registry 4, mcp-server 4, UI 6; one final
  `just verify` run 1651 passed / 0 failed / 2 ignored.
- 3.17 candidate: full run 1672 passed / 0 failed / 2 ignored, QA targeted reruns and
  a real MCP Inspector 2.12.0 client smoke.

Delivery engineering in this commit
- CI: one event per change (feature branches are gated by their pull request, push
  runs only on main), story events run the changed packages, the full workspace suite
  stays the feature/release gate; no cache/sharding without a measured runner check.
- Release: the packaged archives, checksums and SBOM are now uploaded to the Gitea
  release entry of the tag instead of dying with the runner workspace.

Not included on purpose: Story 3.18 work, build caches, runtime databases, local
credentials and scratch evidence.

Refs: crank kanban t_e39d7263; baseline 1b6db09bd1.
2026-10-25 09:08:22 +00:00

446 lines
29 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Наблюдаемость
## Эксплуатационные журналы stdout
`admin-api` и `mcp-server` используют один жизненный цикл наблюдаемости и
одинаковую однострочную JSON-схему:
```json
{
"timestamp": "2026-07-26T12:34:56.789Z",
"level": "INFO",
"service": "admin-api",
"version": "0.3.1",
"environment": "production",
"target": "admin_api::request_context",
"event": "admin.request.completed",
"request_id": "019...",
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"fields": {
"method": "GET",
"route": "/api/operations",
"status": 200
}
}
```
Обязательны `timestamp`, `level`, `service`, `version`, `environment`,
`target`, `event` и объект `fields`. Поля `request_id` и `trace_id` независимы
и появляются только при наличии соответствующего контекста. Имена событий
статичны и имеют вид `<компонент>.<объект>.<исход>`.
Форматирование не использует ANSI. Одна строка stdout всегда соответствует
одному JSON-объекту.
### Сквозная корреляция
Admin API и MCP принимают `x-request-id` как непрозрачный идентификатор.
Допустимое входное значение сохраняется без изменений. Если заголовок
отсутствует или содержит пробелы, управляющие символы, `,`, `;`, не-ASCII
символы либо больше 128 байт, Crank создаёт UUIDv7.
Request ID и отдельный Trace ID:
- возвращаются в `x-request-id`/`x-trace-id` успешного или ошибочного ответа;
- записываются в корневой span входного запроса;
- типизированно передаются в runtime;
- заменяет статические или полученные из mapping значения
`x-request-id` и `x-correlation-id` перед исходящим REST-запросом;
- сохраняются в прикладной истории вызова.
`request id` не является `trace id` и не подменяет распределённую
трассировку.
### Очистка
Перед сериализацией рекурсивно очищаются пароли, секреты, токены, ключи
доступа, authorization, cookie, query, полные payload, body, arguments,
result и response. Составные имена полей проверяются по тем же правилам.
Из URL удаляются учётные данные, query и fragment.
Пределы одного события:
- строка: 1024 байта;
- массив: 32 элемента;
- объект: 64 поля;
- вложенность: 8 уровней;
- вся строка JSON вместе с завершающим переводом строки: 16 КиБ.
Усечение сохраняет корректный UTF-8 и JSON. Секрет заменяется целиком на
`[REDACTED]`; его часть, длина или хеш не выводятся. Если после очистки
событие превышает 16 КиБ, `fields` заменяется ограниченным признаком
усечения. Произвольное представление `Debug` не считается безопасным
структурированным значением: для вложенных данных используется
предварительно очищенный JSON.
Уровень и окружение задаются через `CRANK_LOG_LEVEL` и
`CRANK_ENVIRONMENT`. Для stdout не требуются внешние службы, фоновые очереди
или сетевые endpoint. Их отсутствие не влияет на readiness.
## Критические ошибки
Необязательный Sentry-совместимый канал включается одним значением:
```env
CRANK_SENTRY_DSN=https://public-key@errors.example.com/1
```
Пустой или отсутствующий `CRANK_SENTRY_DSN` полностью отключает канал.
Неверное непустое значение останавливает запуск до приёма запросов, при этом
само значение не попадает в ошибку. Стандартная переменная `SENTRY_DSN` не
используется.
Канал получает только необработанные panic и явно классифицированные
критические ошибки. Ожидаемые ошибки HTTP, MCP, runtime и внешних API остаются
в обычных журналах, показателях и трассах. Для критического события допустимы
только:
- закрытая категория `panic`, `startup`, `internal` или `data_integrity`;
- `service`, `release` и `environment`;
- доступные `request_id` и `trace_id`;
- статическое сообщение без исходного текста ошибки.
События группируются по паре `service` и закрытой категории, поэтому одинаковая
ошибка `admin-api` и `mcp-server` не объединяется в один инцидент. Если
обязательные поля идентичности не помещаются в заданный предел события, запуск
останавливается безопасной типизированной ошибкой до приёма запросов.
До отправки удаляются request, user, breadcrumbs, URL, query, cookie,
authorization, payload, произвольные contexts и extra, а также исходный текст
panic или ошибки. Performance tracing, журналы, показатели и отслеживание
сессий Sentry SDK отключены. Отказ внешнего приёмника не меняет результат
продуктового запроса и не создаёт рекурсивное событие.
GlitchTip и другие Sentry-совместимые приёмники не входят в Community Compose.
Их доступность не участвует в `/health` и `/ready`.
## Показатели Prometheus
`admin-api` и `mcp-server` создают отдельные поверхности показателей. Они не
смешиваются с продуктовыми маршрутами:
| Сервис | Значение по умолчанию |
|---|---|
| `admin-api` | `127.0.0.1:9464` |
| `mcp-server` | `127.0.0.1:9465` |
На каждом адресе существуют только:
- `/metrics` — показатели Prometheus;
- `/health` — статическая проверка самого listener-а.
Любой другой путь возвращает `404`. `/health` этой поверхности не заменяет
`/ready` рабочего сервиса. Ошибка запуска listener-а останавливает процесс до
приёма рабочих запросов.
Loopback доступен без авторизации. Для любого non-loopback адреса обязателен
отдельный `CRANK_METRICS_BEARER_TOKEN`; без него конфигурация отклоняется при
старте. Токен не переиспользует сессию администратора или ключ MCP. Оба
маршрута внешней поверхности требуют `Authorization: Bearer ...`.
Community Compose не содержит Prometheus или Grafana и не публикует порты
9464/9465 на host. Для сетевого сборщика необходимо явно:
1. задать `CRANK_ADMIN_METRICS_BIND=0.0.0.0:9464` и
`CRANK_MCP_METRICS_BIND=0.0.0.0:9465`;
2. передать непустой `CRANK_METRICS_BEARER_TOKEN`;
3. подключить сборщик к внутренней сети Compose либо отдельно опубликовать
нужные порты с ограничением firewall.
Токен сборщика хранится в файле, а не в `prometheus.yml`. Актуальная
конфигурация Prometheus использует `authorization.credentials_file`:
```yaml
scrape_configs:
- job_name: crank-admin
static_configs:
- targets: ["admin-api:9464"]
authorization:
type: Bearer
credentials_file: /run/secrets/crank_metrics_token
- job_name: crank-mcp
static_configs:
- targets: ["mcp-server:9465"]
authorization:
type: Bearer
credentials_file: /run/secrets/crank_metrics_token
```
Семейства первой версии:
- `crank_http_requests_total`, `crank_http_request_duration_seconds`,
`crank_http_inflight`;
- `crank_mcp_requests_total`, `crank_mcp_request_duration_seconds`,
`crank_mcp_active_sessions`, `crank_mcp_session_metrics_fresh`,
`crank_mcp_active_streams`;
- `crank_tool_invocations_total`, `crank_tool_invocation_duration_seconds`;
- `crank_upstream_requests_total`,
`crank_upstream_request_duration_seconds`;
- `crank_runtime_inflight`, `crank_runtime_limit_rejections_total`,
`crank_runtime_cache_total`, `crank_idempotency_total`,
`crank_confirmation_total`;
- `crank_db_pool_connections`;
- `crank_catalog_tools`, `crank_catalog_estimated_context_tokens`,
`crank_catalog_warnings`;
- `crank_invocation_history_lost_total`,
`crank_telemetry_export_failures_total`.
Recorder добавляет к рядам проверенные статические labels `service`,
`version`, `environment`. Остальные labels имеют закрытый набор значений.
Эти три labels классифицированы как `process_constant`: они валидируются один
раз при запуске и образуют ровно одну tuple на процесс. Имена, типы, help,
process ownership, допустимые значения product labels и buckets определены в
независимом нижнем crate `crank-metrics`. Его deterministic machine snapshot —
[`schemas/metrics-registry-v2.json`](schemas/metrics-registry-v2.json); прежний
[`schemas/metrics-registry-v1.json`](schemas/metrics-registry-v1.json) сохранён
byte-for-byte как compatibility input.
Product-код вызывает только типизированный фасад;
прямая production-зависимость от `metrics` вне `crank-metrics` и
`crank-observability` запрещена архитектурной проверкой Cargo metadata.
Запрещено использовать workspace, идентификаторы агента, операции или
запроса, фактический URL, текст ошибки, payload и пользовательский текст.
HTTP route берётся только из шаблона Axum; неизвестные маршруты и методы
сворачиваются в `unmatched` и `OTHER`.
`crank_mcp_active_sessions` отражает число ещё не истёкших транспортных
сессий в общем хранилище, а `crank_mcp_active_streams` — число открытых в
этом экземпляре SSE-потоков. `crank_mcp_session_metrics_fresh=0` означает,
что последнее bounded чтение session store завершилось ошибкой/timeout и
значение active sessions нельзя считать свежим; успешное чтение возвращает
freshness в `1`. Прикладные ошибки JSON-RPC и
`tools/call.result.isError=true` учитываются отдельно от успешного HTTP 200.
Счётчики cache, idempotency и confirmation описывают переходы
соответствующих стадий: hit/miss и ошибки хранилища, execute/replay/conflict
и required/approved/invalid token. Отменённый future runtime или upstream
завершает соответствующее измерение закрытым исходом `aborted`, поэтому
фактически начатый вызов не исчезает из показателей.
Buckets длительности фиксированы кодом:
`0.005`, `0.01`, `0.025`, `0.05`, `0.1`, `0.25`, `0.5`, `1`, `2.5`, `5`,
`10`, `30`, `60` секунд. Это пока техническая шкала, а не SLO. Registry v2
(`schemas/metrics-registry-v2.json`, генерируется Rust descriptor table,
`schema_version=2`) содержит те же 23 family и фиксирует допустимые
HTTP-идентичности как единственное typed перечисление route+owners: union 91,
admin-проекция 86, mcp-проекция 8, общие ровно `/health`, `/ready`,
`unmatched`. Тринадцать Resource-шаблонов
(`/api/admin/workspaces/{workspace_id}/resources` и его `{resource_id}`,
`.../import`, `.../archive`, `.../content`, `.../export`, `.../preview`,
`.../publish`, `.../revoke`, `.../versions/{version}`,
`.../versions/{version}/content`, `.../versions/{version}/export`) и шесть
Prompt-шаблонов (`.../prompts`, `.../prompts/import`, `.../prompts/{prompt_id}`,
`.../prompts/{prompt_id}/export`, `.../prompts/{prompt_id}/preview`,
`.../prompts/{prompt_id}/versions/{version}/export`) принадлежат
только admin-api и больше не смешиваются с `unmatched`.
Бюджет кардинальности считается **на процесс**, а не на union:
- admin-api — 15 family, 6 285 logical, 19 515 rendered, 12 348 exemplar slots;
- mcp-server — 23 family, 1 083 logical, 3 558 rendered, 2 310 exemplar slots.
Hard ceilings — 6 285 logical / 19 515 rendered / 12 348 exemplar
slots на процесс и 8 388 608 bytes (8 MiB) на готовый exposition. Ранее
logical ceiling поднимали с 5 563 до 5 585 явным решением владельца только для
регистрации уже существующего revoke-маршрута Resource, затем для трёх адресов
переноса документов Story 3.9 (import, export текущей и конкретной версии)
владелец явно разрешил поднять все три потолка до фактического бюджета
admin-api: 5 585 → 5 795, 17 638 → 17 975, 11 270 → 11 368. Для трёх адресов
переноса шаблонов сообщений Story 3.15 (`/prompts/import`,
`/prompts/{prompt_id}/export`, `/prompts/{prompt_id}/versions/{version}/export`)
владелец разрешил поднять все три потолка до фактического бюджета admin-api:
6 075 → 6 285, 18 855 → 19 515, 11 928 → 12 348; exposition-лимит 8 MiB не
менялся. Histogram
budget включает finite buckets, `+Inf`, `_sum` и `_count`; 8 MiB ограничивает
**ответ**, а не heap: полный рендер и OpenMetrics-index всё ещё аллоцируют
память до проверки размера. Изменение domain или buckets требует обновления
versioned snapshot и evidence. Registry v1
(`schemas/metrics-registry-v1.json`) сохраняется byte-for-byte как
compatibility input и не пере-генерируется.
Процесс один раз фиксирует закрытый сервис до установки recorder, gauges,
background producers и metrics listener; повтор того же сервиса идемпотентен,
конфликт — типизированная terminal-ошибка startup. До фиксации facade-вызовы
— безопасный no-op. Известный route чужого сервиса записывается как
`unmatched` с сохранением method/status/duration, но никогда не создаёт ключ
чужого route.
Обычный scrape сохраняет Prometheus text 0.0.4. Клиент с
`Accept: application/openmetrics-text` получает OpenMetrics 1.0 и `# EOF`.
Validated 32-hex Trace ID может присутствовать только как latest bounded
histogram exemplar; он никогда не является label и не меняет aggregate.
Отсутствующий, invalid или unsampled Trace ID просто не создаёт exemplar.
Размер готового exposition ограничен 8 MiB; превышение возвращает статический
`503` без частично усечённого тела и не влияет на product listener.
## Распределённые трассы
Crank принимает и передаёт стандартный W3C `traceparent` на границах Admin
API, MCP и исходящих REST-вызовов. Ровно один canonical parent принимается;
duplicate, malformed, uppercase и zero-ID значения заменяются новым local
trace без echo входа. `x-request-id` остаётся отдельным идентификатором
запроса, а `x-trace-id` — безопасным локальным support ID. Caller
`tracestate` ограничен 512 байтами/32 members, baggage — 8192 байтами/64
members; Community allowlist пуста, поэтому они не извлекаются и не
передаются.
Экспорт отключён по умолчанию: при пустых
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` и `OTEL_EXPORTER_OTLP_ENDPOINT` local
provider сохраняет span topology и Trace ID, но exporter, batch processor,
фоновая очередь и сетевой трафик не создаются. Поэтому response, runtime и
Invocation History получают Trace ID независимо от sampling/export. После
включения используется только OTLP/HTTP binary protobuf. Community Compose
не включает Collector или хранилище трасс: оператор подключает внешний
совместимый приёмник.
Уровень эксплуатационных журналов не отключает трассы. В OTLP попадают
только явно отмеченные spans с внутренней целью `crank::trace`; события
`tracing` не экспортируются, чтобы их поля не обходили очистку JSON-журналов.
Новые экспортируемые spans должны использовать ту же цель и содержать только
ограниченные безопасные атрибуты.
Очередь экспорта конечна. Экспорт выполняется вне обработки продуктового
запроса, поэтому недоступность приёмника не меняет HTTP, MCP или runtime
результат. Ошибки доставки учитываются в
`crank_telemetry_export_failures_total{signal_type="trace",exporter="otlp"}`
без журналирования endpoint, headers и без создания новой OTLP-трассы.
Входящий корректный `traceparent` становится родителем корневого span.
Некорректный заголовок трактуется как отсутствующий: запрос продолжается с
новой трассой, а исходное значение не возвращается и не журналируется.
Перед исходящим REST-запросом доверенный текущий контекст заменяет любой
`traceparent`, заданный в настройках операции.
### Стадии выполнения инструмента
Crank создаёт дочерний span только тогда, когда соответствующая стадия
фактически выполняется:
| Span | Значение |
|---|---|
| `mcp.rate_limit` | проверка ограничения частоты MCP-запроса |
| `mcp.access.check` | машинная проверка доступа |
| `mcp.catalog.load` | получение опубликованного каталога |
| `mcp.tools.resolve` | разрешение конкретного инструмента |
| `approval.check` | применимая проверка подтверждения |
| `runtime.execute` | выполнение инструмента в runtime |
| `runtime.arguments.map` | проверка схемы и отображение аргументов |
| `runtime.idempotency` | применимая проверка идемпотентности |
| `upstream.http` | фактический HTTP-вызов внешней системы |
| `runtime.response.transform` | отображение и проверка ответа |
| `auth.resolve` | применимое разрешение профиля авторизации и секретов |
| `approval.recovery` | фоновое восстановление подтверждённого вызова |
| `history.write` | запись прикладной истории |
| `db.query` | значимая операция PostgreSQL |
Например, ответ из кэша или повтор идемпотентного результата не создаёт
`upstream.http`. Операция без подтверждения и идемпотентности не создаёт
соответствующие spans. Отсутствующая стадия никогда не изображается успешной.
Атрибуты стадий имеют закрытый словарь: `outcome`, `error.category`,
`db.system` и `db.operation`. Значения задаются перечислениями из
`crank-trace`; пользовательские идентификаторы, URL, заголовки, query,
аргументы, ответы и текст ошибок туда передать нельзя. Ошибка содержит только
категорию, достаточную для локализации стадии. `request_id` присутствует
только в проверенном корневом span и сопоставляется с записью прикладной
истории.
Перед OTLP-сериализацией экспортёр повторно применяет разрешительный список
имён и атрибутов, удаляет события и ссылки span и очищает текстовое описание
статуса ошибки. Эта последняя граница действует независимо от очистки
эксплуатационных JSON-журналов и не позволяет новому инструментированию
случайно экспортировать пользовательские данные.
Точный список переменных и правила OpenBao приведены в
[описании runtime-конфигурации](runtime-config.md).
## Прикладные журналы и использование
Crank сохраняет в PostgreSQL данные о тестовых запусках и вызовах
опубликованных MCP-инструментов. Это отдельная прикладная история, а не
копия stdout.
Новые записи сохраняют точную Operation version и закрытую классификацию
`execution_stage`, `execution_error_code`, `retryability` и
`outcome_certainty`. Admin Draft Test и MCP используют одну taxonomy; transport
может отличаться, но не смысл результата. Legacy-записи до migration v5 имеют
`NULL` в этих полях — Crank не выдумывает исторические исходы.
`outcome_unknown` означает, что внешний side effect мог произойти до timeout
или transport failure. Такой исход требует ручной сверки и никогда не является
сигналом для автоматического повтора. Request ID и Trace ID остаются полями
корреляции и не используются как Prometheus labels.
Если внешнее действие завершилось, но PostgreSQL отклонил запись истории,
Crank не меняет фактический результат и не повторяет действие. Вместо
синтетической записи создаётся эксплуатационный инцидент `DC-08`:
- `admin.invocation_history.lost` или `mcp.invocation_history.lost` в stdout;
- внутренний монотонный счётчик без пользовательских меток;
- `crank_invocation_history_lost_total` и закрытый показатель потери
экспорта;
- только закрытые поля `source`, `invocation_status` и `error_category`.
Текст ошибки PostgreSQL, payload и секреты в событие не передаются. Внешняя
публикация не влияет на результат уже завершённого действия.
## Журналы
В журнал попадают:
- операция;
- агент, если вызов пришел через MCP;
- Request ID и Trace ID;
- статус;
- HTTP status code внешнего API;
- время выполнения;
- краткий preview запроса и ответа;
- execution stage, error code, retryability и certainty, если вызов завершился
ошибкой.
Previews проходят единый redaction/size limit до записи в PostgreSQL, Admin API
и CSV. Raw credentials, arbitrary headers/body и неограниченный текст ошибки не
являются частью Invocation History. Legacy-записи могут иметь пустые typed
execution fields; новые записи должны содержать Request ID и Trace ID.
Admin Logs API поддерживает workspace-scoped фильтры `period`, `level`,
`status`, `source`, `operation_id`, `agent_id`, `search` и deterministic opaque
cursor pagination. Detail view показывает те же безопасные поля и не раскрывает
foreign-scope metadata через counts или разные формы ошибок. CSV export
использует те же filters/auth/redaction и дополнительно экранирует
spreadsheet-formula cells.
При обновлении опубликованного MCP-каталога событие `mcp.catalog.analyzed`
содержит `tool_count`, `serialized_bytes`, `estimated_context_tokens`,
`largest_tool_estimated_context_tokens`, `recommended_context_tokens`,
`exceeds_recommended_budget` и число предупреждений качества. По этим полям
можно заметить рост цены `tools/list` до того, как он ухудшит выбор
инструментов моделью.
## Использование
Раздел использования агрегирует:
- количество вызовов;
- успешные и ошибочные вызовы;
- долю ошибок;
- задержки p50, p95 и p99;
- распределение вызовов по операциям;
- распределение по Agent;
- outcome groups `success`, `upstream`, `client`, `schema`, `crank`.
Периоды считаются в UTC как half-open interval `[start, end)`, поэтому запись
на правой границе периода не дублируется в соседнем окне. Retention удаляет
только старые Invocation History rows по typed observable outcome. Cleanup
сохраняет публичный usage horizon последних 90 дней даже при более агрессивном
requested cutoff и возвращает typed policy/outcome (`requested_cutoff`,
`effective_cutoff`, deleted count, preserved window). Published Version audit,
Agent snapshots и immutable release evidence не являются объектами retention
cleanup.
## Для чего это нужно
- проверить, вызывают ли агенты нужные инструменты;
- увидеть ошибки маппинга или внешнего API;
- найти медленные endpoint-ы;
- понять, какие инструменты реально используются.