наблюдаемость: завершить базовый контур Community

Добавить структурированные журналы, метрики, трассировку и безопасный канал критических ошибок. Усилить границы рантайма, тесты, проверку зависимостей и сценарии развёртывания.
2026-07-31 01:01:14 +03:00
parent 99bd05c145
commit 0e8f1ca03a
160 changed files with 13506 additions and 1499 deletions
@@ -1,6 +1,286 @@
-# Журналы и использование
+# Наблюдаемость

-Crank сохраняет данные о тестовых запусках и вызовах опубликованных MCP-инструментов.
+## Эксплуатационные журналы 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...",
+  "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.
+
+Один идентификатор:
+
+- возвращается в `x-request-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`;
+- статическое сообщение без исходного текста ошибки.
+
+До отправки удаляются 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_active_sessions`;
+- `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_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 имеют закрытый набор значений.
+Запрещено использовать workspace, идентификаторы агента, операции или
+запроса, фактический URL, текст ошибки, payload и пользовательский текст.
+HTTP route берётся только из шаблона Axum; неизвестные маршруты и методы
+сворачиваются в `unmatched` и `OTHER`.
+
+Buckets длительности фиксированы кодом:
+`0.005`, `0.01`, `0.025`, `0.05`, `0.1`, `0.25`, `0.5`, `1`, `2.5`, `5`,
+`10`, `30`, `60` секунд. Это пока техническая шкала, а не SLO. Фактические
+series и расход памяти измеряются в истории 1.8; произвольный численный
+бюджет до замеров не назначается.
+
+## Распределённые трассы
+
+Crank принимает и передаёт стандартный W3C `traceparent` на границах Admin
+API, MCP и исходящих REST-вызовов. `x-request-id` остаётся отдельным
+идентификатором запроса. Baggage не извлекается и не передаётся.
+
+Экспорт отключён по умолчанию: при пустых
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` и `OTEL_EXPORTER_OTLP_ENDPOINT`
+provider, batch processor и фоновый поток не создаются. После включения
+используется только 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.
+
+Если внешнее действие завершилось, но 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 и секреты в событие не передаются. Внешняя
+публикация не влияет на результат уже завершённого действия.

 ## Журналы

@@ -15,7 +295,12 @@ Crank сохраняет данные о тестовых запусках и в
 - краткий preview запроса и ответа;
 - категория ошибки, если вызов завершился ошибкой.

-При обновлении опубликованного MCP-каталога отдельное событие `published agent catalog analyzed` содержит `tool_count`, `serialized_bytes`, `estimated_context_tokens`, `largest_tool_estimated_context_tokens`, `recommended_context_tokens`, `exceeds_recommended_budget` и число предупреждений качества. По этим полям можно заметить рост цены `tools/list` до того, как он ухудшит выбор инструментов моделью.
+При обновлении опубликованного MCP-каталога событие `mcp.catalog.analyzed`
+содержит `tool_count`, `serialized_bytes`, `estimated_context_tokens`,
+`largest_tool_estimated_context_tokens`, `recommended_context_tokens`,
+`exceeds_recommended_budget` и число предупреждений качества. По этим полям
+можно заметить рост цены `tools/list` до того, как он ухудшит выбор
+инструментов моделью.

 ## Использование