Эксплуатация активности и потребления

Область применения

Руководство предназначено для администратора платформы. Раздел «Активность и потребление» показывает LLM-запросы, расход токенов и HTTP-запросы к агентам. Он предоставляет агрегаты, графики и журнал метаданных LLM-запросов за последние 30 суток. Денежная стоимость и полный жизненный цикл выполнения агента в эту поставку не входят. Агент остаётся непрозрачным процессом: расход его ключа связывается с ключом и агентом, личность инициатора LLM-запроса не определяется.

Нагрузочная квалификация AU-I05 ещё выполняется. Итоговые ресурсы, пропускная способность, задержки и условия приёмки будут зафиксированы после её завершения. Приведённые ниже параметры очереди и схемы описывают реализацию, но не подтверждают производительность или готовность промышленного контура.

Путь данных и границы надёжности

LLM Gateway / Agent Gateway
  → OTLP
  → OpenTelemetry Collector: очистка и нормализация → очередь на диске
  → ClickHouse: activity.otel_logs
  → Control Plane API: текущие права + ресурсные привязки → интерфейс

Используются agentgateway 1.5.0, OpenTelemetry Collector Contrib 0.156.0 и ClickHouse 26.8.10.6. Образы закреплены контрольными суммами в конфигурации поставки. Замена только номера версии без повторной проверки профиля недопустима. Версия нормализации — agentgateway-1.5-conservative/v2, схема хранения — activity-storage/v2.

Collector использует штатную постоянную очередь. PostgreSQL Control Plane хранит ресурсные привязки и небольшое состояние наблюдения за доставкой; промежуточного журнала событий в PostgreSQL нет. Отдельные агрегатные таблицы или брокер сообщений для этой функции не вводятся.

События содержат разрешённые метаданные. Текст запросов и ответов, токены авторизации, ключи API, произвольные заголовки и ответы с диагностикой провайдера не должны попадать в очередь, ClickHouse и пользовательский журнал. Не включайте полный вывод тела запросов для поиска неисправности Activity.

Что означает подтверждение доставки

Для события, принятого фильтрами поставляемого профиля, успешный ответ OTLP от Collector означает запись в постоянную очередь. Он не означает, что событие уже доступно через Control Plane. Параметр wait_for_result: false освобождает отправителя от ожидания ClickHouse, но не переносит подтверждение на момент до записи в очередь. Ошибка записи или переполнение возвращается отправителю как отказ.

После подтверждения данные переживают перезапуск Collector при сохранном том же томе и совместимой конфигурации очереди. До подтверждения события находятся на стороне Gateway: его аварийное завершение, недоступность Collector или исчерпание буферов могут привести к потерям. Запрос к модели или агенту не превращается в синхронную транзакцию с аналитическим хранилищем.

Доставка допускает повторные физические строки. Control Plane удаляет логические дубли при чтении, используя стабильные идентификаторы и содержимое события. Обычный count() по сырым строкам ClickHouse не является числом запросов. Противоречивые варианты одного события дают ошибку качества в затронутой разрешённой выборке, а не случайно выбранный результат.

Действующий профиль очереди

Перед очередью нет отдельного асинхронного обработчика пакетирования. Ограничитель памяти, преобразование и фильтр выполняются до подтверждения. Окончательный отказ экспорта или исчерпание повторов означает возможный разрыв истории. Нельзя считать бесконечную догрузку гарантированной.

Роли и сетевой доступ

Разделяйте учётные данные хранилища и пользовательские права Activity. Пользователи интерфейса и CLI обращаются только к Control Plane API; прямой доступ к ClickHouse им не требуется.

Collector — доверенный источник записи. Вычисляемые колонки ClickHouse не являются защитой от подделки событий обладателем его учётных данных: такой субъект уже может записывать исходные атрибуты. Секреты доступны только нужным процессам, хранятся в Kubernetes Secret и не включаются в URL, открытые значения конфигурации, Git или отчёты проверки.

Владелец агента получает агрегаты, но не автоматически детали его служебного ключа. Просмотр каталога, возможность вызвать агента, agent#diagnose или наблюдение за CP сами по себе не выдают Activity-доступ. Права проверяются при каждом чтении; ранее выданный курсор их не сохраняет.

Дополнительный доступ выдаётся существующим административным процессом Platform AuthZ, через отношение activity_diagnostician у точного api_key или agent. Назначение открывает всю доступную сохранённую историю ресурса, а не только будущие запросы. Новый интерфейс управления этими назначениями в Activity не предусмотрен.

Для операторского API AuthZ операция POST /v1/relationships/write получает точное отношение. Ниже структура запроса, не готовые идентификаторы среды:

{
  "updates": [{
    "operation": "OPERATION_TOUCH",
    "relationship": {
      "resource": {"objectType": "api_key", "objectId": "<key-id>"},
      "relation": "activity_diagnostician",
      "subject": {"object": {"objectType": "principal", "objectId": "<canonical-subject-id>"}}
    }
  }]
}

Для агента заменяется тип ресурса на agent и его идентификатор; для сервисного субъекта используется service. Канонический идентификатор субъекта строится из неизменяемых issuer и subject: обе строки кодируются отдельно в base64url без дополнения и соединяются символом |. Адрес электронной почты и отображаемое имя не заменяют этот идентификатор. Для отзыва применяется OPERATION_DELETE к тому же точному отношению. Административный токен AuthZ не передаётся в CP или браузер. Зафиксируйте назначение/отзыв в административном аудите и проверьте новое чтение через CP от затронутого субъекта. После отзыва недоступная карточка отвечает так же, как отсутствующая: 404.

В основном dev-local общий Collector сохраняет обычные OTLP-потоки на 4317/4318. Для Activity Service aip-activity-otlp:4317 направляет трафик на отдельный приёмник 4319. Вход разрешён только допущенным Gateway. Внутренние метрики Collector на 8888 читает выделенный CP Model Worker; расширять их доступ до всех Pod ради диагностики не требуется.

Включение и проверка

Параметры задаёт владелец развёртывания, а не пользователь интерфейса.

По умолчанию activity.enabled, activity.delivery.enabled и activity.observer.enabled выключены. Основная композиция dev-local включает их в обычном режиме и отдельно подключает профиль Agent Gateway. Общий контур и QA не становятся настроенными автоматически по факту установки этого чарта.

Последовательность включения:

1. Проверить закреплённые версии, свободное место, границы пространств имён, сетевые правила и отдельные секреты ролей.
2. Подготовить ClickHouse и применить задание схемы. Дождаться его успешного завершения и маркера activity-storage/v2.
3. Подключить профиль к Collector, постоянный том и учётные данные записи. Проверить готовность процесса, доступность ClickHouse и метрики очереди.
4. Подключить профили обоих Gateway, затем чтение CP и наблюдение. Проверить фактическую готовность управляемых Gateway и начало поступления событий.
5. Выполнить известный запрос, сверить его через API, журнал и карточку, проверить ограниченного пользователя и сохранность обычных OTLP-потоков. Зафиксировать начало доступной истории; предыдущие 30 суток не заполняются вымышленными данными.

Из каталога репозитория deploy для основного dev-local используются существующие действия:

python3 scripts/dev_local_garden.py deploy agent-platform --yes
python3 scripts/dev_local_garden.py run activity-main-smoke
python3 scripts/dev_local_garden.py test activity-provider-boundary

Первая проверка создаёт собственный LLM-ключ и отзывает его по завершении; его история сохраняется по обычным правилам. Испытания отказов и нагрузки проводятся в отдельном проверочном контуре, а не на общем Collector. Изменение профиля Collector применяется через развёртывание: простая правка файла не подтверждает, что работающий процесс перечитал его.

Отключение, догрузка очереди и откат

На время стабилизации третьего релиза функция по умолчанию отключена. На уровне процесса CP общий переключатель — AP_CONTROL_PLANE_ACTIVITY_ENABLED со значением false по умолчанию. В этом состоянии маршруты Activity отсутствуют в API и OpenAPI, запросы к ним возвращают HTTP 404; клиент ClickHouse и наблюдение за доставкой не запускаются даже при сохранённых настройках подключения. В штатном чарте activity.enabled задаёт этот переключатель и параметр интерфейса activityEnabled: при отключении раздел скрыт, а прямые ссылки не открывают страницы Activity и не вызывают её API.

У чтения и доставки разные границы. При AP_CONTROL_PLANE_ACTIVITY_ENABLED=true чтению также нужны AP_CONTROL_PLANE_ACTIVITY_CLICKHOUSE_URL и отдельный секрет чтения. Если функция включена, но подключение отсутствует, Activity возвращает activity_unavailable; остальные функции CP и вызовы моделей не превращаются в пустую историю или нулевые суммы.

AP_CONTROL_PLANE_ACTIVITY_EXPORT_ENABLED управляет добавлением доверенной привязки в политике моделей только при AP_CONTROL_PLANE_ACTIVITY_ENABLED=true. Это не самостоятельный выключатель чтения или OTLP на всех Gateway. В штатном чарте activity.enabled: false убирает подключение чтения и LLM-профиль вместе; профиль Agent Gateway принадлежит отдельной части композиции. Единой готовой CLI-команды для независимого отключения всех источников нет.

При плановом отключении или откате:

1. Зафиксировать время, текущие образы, схему, конфигурацию, PVC, состояния полноты и счётчики принятых/отклонённых событий. Сохранить резервную копию, если изменение схемы или версии создаёт риск восстановления.
2. В управляемой конфигурации закрыть чтение, если старый CP несовместим со схемой. Отключить новый экспорт на обоих Gateway, сохранив бизнес-маршруты. Изменения применять через композицию Garden, не отдельной ручной правкой Pod.
3. Проверить фактическое применение: новые запросы к модели и агенту успешны, а после завершения находившихся в работе запросов новых событий Activity от этих источников не появляется. Смена флага сама по себе этого не доказывает.
4. Оставить совместимые Collector, ClickHouse и прежний PVC очереди работающими. Не менять clickhouse/activity, file_storage/activity и путь хранения: преждевременное переименование может оставить принятую очередь недоступной.
5. Дождаться догрузки. Один нулевой отсчёт otelcol_exporter_queue_size не доказывает завершение всей доставки: дополнительно проверить завершение экспорта, отсутствие новых ошибок и сверить принятые идентификаторы/суммы. Если сверка невозможна или события потеряны, зафиксировать объяснённый разрыв истории, а не объявлять очередь полностью доставленной.
6. Только после этого выводить старый компонент из эксплуатации. Таблица, PVC и исторические привязки сохраняются. При повторном включении сначала проверяются схема и доставка, затем открывается чтение.

Общий Collector также обслуживает другие сигналы. Отключение Activity не должно останавливать весь Collector, удалять общие приёмники или менять посторонние конвейеры.

Совместимость схемы v2

Мигратор добавляет к исходным OTLP-колонкам вычисляемые e_*, EventValid и EventFingerprint. Они ускоряют чтение, не заменяют исходные события и не содержат решения о правах пользователя. При переходе с v1 значения вычисляются для существующих данных. Маркер v2 публикуется только после успешного завершения. Ожидание этой операции ограничено 600 с, задание Kubernetes — 900 с.

Повторный запуск после прерывания безопасно повторяет недовыполненное вычисление; готовая v2 проверяется без повторного пересчёта. При несовпадении версии чтение закрывается с activity_unavailable. Старый читатель, ожидающий маркер v1, несовместим с v2. Для отката нужен образ, умеющий читать v2, либо отключённое чтение до восстановления совместимости. Ручное понижение маркера, удаление вычисляемых колонок и запуск старого ClickHouse над новой директорией данных не являются процедурой отката.

Проверенный нагрузочный профиль

На локальном проверочном стенде пройдены два сценария с историей в один миллион LLM-запросов: 100 новых запросов/с в течение 10 минут и 300 запросов/с в течение 2 минут. Во время потока выполнялись 5 запланированных чтений/с с максимумом 10 одновременных соединений. Дополнительная проверка свежести читала журнал и сводки через тот же пул; её вызовы входят в фактическую нагрузку. Проверены точные идентификаторы, суммы токенов и действующие права пользователей.

Стенд: Ryzen 9 8940HX, 16 ядер/32 потока. Лимиты ClickHouse — cpu: 16, memory: 8Gi; CP API — cpu: 2, memory: 1Gi; генератор — cpu: 1, memory: 512Mi. На пике наблюдаемый максимум ClickHouse составил 5,42 ядра и 4,12 ГБ рабочей памяти. Это условия конкретной проверки, а не доказанный минимум ресурсов. Основной dev-local может иметь другие лимиты; результат не означает автоматического изменения его настроек.

Отдельно проверены пять минут недоступности ClickHouse при 100 запросах/с: 30 000 накопленных событий доставлены не позднее 16,74 с от начала восстановления при продолжающемся входящем потоке. Общий проверенный набор — 60 000 событий; отказ не превращал успешный LLM-ответ в подтверждение доставки.

Эти короткие прогоны подтверждают ограниченный сценарий. Они не определяют ёмкость хранения за месяц непрерывной пиковой нагрузки, режим высокой доступности или характеристики другой инфраструктуры. Перед выбором ресурсов для своей установки учитывайте фактический поток, размер событий и состав чтений.

Наблюдение и действия при отказах

Наблюдатель работает в существующем CP Model Worker, опрашивает разрешённые внутренние адреса каждые 15 с с пределом 2 с на обращение. Состояние и интервалы риска сохраняются в PostgreSQL. Опрос не выполняется внутри пользовательского запроса к модели или Activity API.

Сопоставляйте otelcol_exporter_queue_size и otelcol_exporter_queue_capacity со счётчиками otelcol_exporter_enqueue_failed_log_records, otelcol_receiver_refused_log_records, otelcol_exporter_send_failed_log_records и состоянием процесса. Учитывайте сброс счётчиков при перезапуске. Недоступная метрика означает неизвестное значение, а не ноль. По одному числу ошибок нельзя вычислить точное количество утраченных логических запросов.

При росте очереди проверьте доступность ClickHouse, задержки вставки и свободное место обоих томов. При отказе записи или исчерпании повторов сохраните интервал неполноты и диагностические метаданные без содержимого запросов. Не удаляйте файл очереди для восстановления «зелёного» состояния.

После отказа записи в закреплённой версии Collector показатель размера очереди может завышать сохранённый объём: внутренний счётчик увеличивается до попытки записи и не откатывается сразу при её ошибке. В проверке хранилища показатель вырос с 45 до 2 097 251 байта, хотя файл остался 32 КиБ с прежним SHA-256, отправитель получил 503, а число принятых записей осталось равным одному. Это сигнал возможного давления, а не подтверждение наличия этих байтов на диске. Испытание не устанавливает срок исправления счётчика после полной догрузки. При остановке сверяйте доставку и ошибки; не объявляйте события сохранёнными или потерянными исключительно по этому показателю.

Пороги оповещений согласуются с оператором среды. Ориентиры спецификации — занятость очереди от 80%, свободное место менее 20%, отказы записи, окончательные ошибки и отсутствие наблюдений. Это не автоматически установленный набор оповещений и не утверждённые нормативы производительности.

Хранение, резервные копии и восстановление

API всегда ограничивает историю последними 30 сутками по startedAt, включая карточку по известному идентификатору. Задержка физического удаления, старый курсор или поздняя доставка события не открывают просроченную историю.

В таблице действует TTL toDateTime(Timestamp) + INTERVAL 30 DAY DELETE. Физическое удаление происходит при фоновой обработке ClickHouse и не совпадает по времени с закрытием данных API. Контролируйте возраст самых старых просроченных записей, свободное место и состояние фоновых операций. Указанный в спецификации ориентир очистки в течение следующих 24 часов требует отдельного эксплуатационного подтверждения; короткая проверка TTL его не доказывает.

Перед изменением с риском восстановления подготовьте зашифрованную резервную копию в отдельном от тома данных PVC хранилище. Проверьте чтение манифеста, контрольные суммы и совместимость версии; ограничьте доступ и задайте удаление через 24 часа. Для копий, содержащих уже скрытые записи, согласованный предельный горизонт — 32 суток от startedAt: 30 суток истории, до суток очистки и до суток жизни копии. Он не заменяет согласование политики хранения среды.

Восстановление сначала выполняется изолированно:

1. Проверить версию ClickHouse, структуру таблицы и маркер схемы.
2. Восстановить копию в отдельное хранилище и сверить известные идентификаторы, число логических запросов и суммы токенов.
3. Убедиться, что просроченные события остаются закрыты API, даже если физически присутствуют, а доступ рассчитывается по текущим правам AuthZ.
4. Не восстанавливать прежние права из копии истории. Проверить закрытый доступ для постороннего субъекта и отсутствие секретов в результатах.
5. Только после проверки совместимости и очистки просроченной истории возвращать доступ к восстановленному контуру.

Узкая проверка восстановления в проверочном контуре использует небольшую зашифрованную копию на временной файловой системе. Она подтверждает процедуру сверки, но не является промышленным хранилищем резервных копий или проверкой восстановления после потери узла. Автоматические регулярные копии истории в dev-local не включены. Рабочий файл bbolt очереди нельзя просто скопировать и объявить проверенной резервной копией.

Ограничения поставки

Репликация истории, высокая доступность, восстановление после потери диска и численное обязательство по допустимой потере данных не подтверждены этим профилем. Постоянная очередь снижает риск при перезапуске процесса, но не превращает одиночный том в отказоустойчивое хранилище. Нагрузочные ресурсы, пределы задержек и результаты совместного чтения/записи остаются предметом итоговой квалификации AU-I05.

Общие процедуры сопровождения описаны в руководстве Control Plane.