Вы поставили Prometheus, написали алерты на 5xx и p95 latency, у вас structured JSON-логи и сквозной request-ID. Сервер под этим стопом наблюдает за собой как надо — и при этом вы впервые узнаёте о проблеме из счёта за API: агент 40 минут крутился вокруг одной задачи, звал не тот инструмент и сжёг бюджет, а все ваши дашборды показывали зелёный. Это не дыра в вашем мониторинге. Это дыра в предположении, что сбой выглядит как ошибка.
Классический APM (application performance monitoring, «мониторинг производительности приложения») ловит отказы: процесс упал, запрос не ответил, статус 500. AI-агент почти никогда не «падает» в этом смысле. Он возвращает 200 на каждом шаге и при этом не приближается к цели. Наблюдаемость за агентом — это не «ещё один лог-файл», а отдельная дисциплина, потому что у агента есть три сущности, которых нет у обычного HTTP-клиента: цикл, решение какой инструмент звать и поток денег. Эта статья — установочная для серии: здесь задаём рамку и боль, словарь атрибутов (OpenTelemetry GenAI) разберём в №2, готовую телеметрию Claude Code и Copilot — в №3, а то, как собрать свой лёгкий слой на PHP, — в №6.
Термин-ловушка — снять сразу. В сети у нас есть статья «Наблюдение за DOM и производительность» — там наблюдатели это
IntersectionObserver/MutationObserverвнутри браузера, клиентский код следит за разметкой страницы. Здесь observability (наблюдаемость) — серверная: вы следите за тем, что делает модель и инструменты у вас на бэкенде. Одно русское слово, противоположные мишени. Дальше под «наблюдаемостью» мы имеем в виду именно серверную.
Часть I. Агент — это цикл, и это ломает всю вашу терминологию
1. Что такое «agent loop»
Код-ассистент, который «сам всё сделает», устроен не как «отправил промпт → получил ответ». Он устроен как цикл с памятью о состоянии (англ. agent loop — «петля агента»):
пока задача не завершена:
1. отправить модели текущий контекст (историю + результат последних шагов)
2. модель отвечает: либо текст пользователю, либо "хочу вызвать инструмент X с аргументами Y"
3. если вызов инструмента — исполнить X у себя (grep, запуск теста, правка файла, HTTP-запрос)
4. положить результат инструмента в контекст
5. goto 1
Каждый проход — это полноценный запрос к модели, в который кладётся вся накопленная история. Отсюда три следствия, каждое из которых само по себе меняет метрики.
Следствие 1: один «запрос» к агенту — это N запросов к модели. Когда вы смотрите requests per second к своему эндпоинту агента и думаете «у нас низкая нагрузка», вы меряете циклы, а не вызовы модели. Один цикл легко даёт 10–40 вызовов модели, и каждый следующий дороже предыдущего (об этом — экономика в №5). Метрика «сколько запросов к агенту» для планирования ёмкости и биллинга практически бесполезна — полезна «сколько итераций и токенов на завершённую задачу».
Следствие 2: у цикла есть состояние, и оно живёт в контексте, а не в памяти процесса. «Транзакция» агента — это conversation (беседа) с идентификатором. Именно он, а не request-ID, — ось, вокруг которой надо группировать всё: вызовы модели, инструменты, стоимость, решения. В OpenTelemetry GenAI это отдельный атрибут gen_ai.conversation.id, и это, кстати, единственный зафиксированный в реестре атрибут, который явно пропагируется (проталкивается) между операциями — остальные живут внутри операции (про реестр атрибутов — №2).
Следствие 3: цикл может не закончиться. У обычного HTTP-запроса конечность гарантирована сетевым стеком: кто-то закрыл соединение, истёк таймаут. У агентного цикла конечность — ваша ответственность. Если модель на каждом шаге решает «ещё один инструмент вызову и посмотрю», а вы не ограничили число итераций, вы получите корректный, валидный, каждый-шаг-успешный поток, который никогда не завершается. Это и есть runaway loop — первый из трёх сбоев, которые разберём в Части II.
Опора на базу. Что такое span, trace, как пробрасывать request-ID через
traceparentи куда складывать structured JSON-логи — всё это у вас уже должно быть, и это разбирает «Логирование и трассировка». Эта серия не пересказывает базу: она берёт её как данность и надстраивает агентную семантику — «что класть в span’ы, чтобы видеть цикл, а не только HTTP-статусы».
Часть II. Три класса сбоев, которые не бросают исключений
Это сердце статьи. Каждый класс — реальный сбой, который вы не увидите в логах уровня ERROR и не поймаете алертом на error rate.
1. runaway loop — бесконечная рекурсия, которая «успешна»
Агент вызывает инструмент, получает результат, вызывает тот же инструмент с теми же (или почти теми же) аргументами, снова получает результат, снова вызывает… Модель на каждом шаге думает, что она «продвигается», потому что в контексте появляются новые токены. Никакой ошибки нет. Каждый вызов вернул 200. Каждый инструмент отработал success: true.
Чем это кончается:
- счёт за API (или исчерпание купленного лимита токенов) улетает в космос за одну задачу;
p95 latencyвашего агента «в норме», потому что каждый отдельный шаг быстрый — медленно только целое;- пользователь видит «работает…», и вы включили мониторинг не туда.
Что это ловит: счётчик итераций на цикл (не на запрос) и алерт «цикл > K итераций». Это метрика-страховка, её нет в классическом APM. Ниже в Части V она появится как loop_guard.
2. tool misuse — валидный вызов не того инструмента
Агент имеет список инструментов (functions/tools, которые вы ему дали). tool misuse — не когда вызов упал, а когда вызов прошёл успешно и был не тем, который нужен:
- модель позвала
read_fileвместоedit_file(и получила 200 с содержимым файла, решив, что «что-то сделала»); - позвала инструмент с плохими аргументами, инструмент «успешно» вернул пустой результат, модель приняла пустоту как сигнал «ничего не найдено» и пошла дальше с неверной картиной;
- вызвала инструмент, который не должен был быть доступен агенту (у вас был
drop_tableв списке инструментов «для отладки»); - вызвала один инструмент столько раз, сколько не надо (надстройка над
runaway loop, но поведенчески это misuse конкретного инструмента).
Что это ловит: счётчик решений и исходов инструментов — tool.name, success, error_type, размер входа/выхода. У Claude Code это готовые метрики и события: tool_result несёт tool_name, success, duration_ms, error_type; отдельный tool_decision считает accept/reject правки (claude_code.code_edit_tool.decision). В классическом мониторинге у вас нет понятия «принято/отклонено решение» — оно есть только потому, что агент принимает решения.
3. Тихая деградация и каскад 4xx — «не та модель» против «провайдер не жив»
Здесь сбоев два, и их нельзя путать, иначе вы будете лечить не то.
- Каскад 429 (rate limit). Провайдер жив, но режет вас по частоте. Каждый отдельный шаг — валидный ответ с
429. Один 429 — retry, норма. Десятки подряд в пределах одного цикла — деградация, и если вы не отличаете «429 на одном провайдере» от «429 на всех», вы не заметите, что у вас весь выход в модель стал медленным, пока пользователь не уйдёт. - 403 уровня доступа к модели. Это не ошибка транспорта и не rate limit. Модель может быть в списке
/v1/modelsформально, но ваш аккаунт/команда не имеет к ней доступа — ответ403 team_model_access_denied. Если классифицировать это как «провайдер лежит» и включить circuit breaker — вы зря снимете живого провайдера. Если не отличить от «модели нет вообще» — вы будете будить ночного дежурного из-за опечатки в имени модели.
Прожитый кейс (без внутренних имён). В одной из наших связок «провайдер ↔ модель» 403 с классификацией «доступ запрещён на уровне команды» прилетал даже на эталонную модель, которая гарантированно доступна. Система, которая просто считывала «403 = провайдер нездоров», честно и правильно валила failover на следующего провайдера, хотя первый был абсолютно жив — падала конкретная пара «ключ↔модель», а не транспорт. Урок: код статуса сам по себе не классифицирует сбой для агента; классифицирует связка «код + кто именно + какая модель + какой эндпоинт». Это машина состояний, а не
if status != 200. Её скелет — в Части V, детальная сборка слоя — в №6.
Часть III. Почему «HTTP 200 = успех» ломается на агенте
Возьмите вашу типичную алерт-логику. Она почти наверняка выглядит как одно из:
error_rate > 1%по 5xx;http_requests_total{status=~"5.."};- health-check эндпоинта отвечает 200;
p95 latencyниже порога.
Теперь наложите на агентный цикл из Части I. Ни один из этих сигналов не краснеет при runaway loop, tool misuse или тихой деградации, потому что:
| Ваш сигнал | Что он меряет | Почему слеп к агенту |
|---|---|---|
| 5xx error rate | «сервер не ответил» | Агент получает 200 на каждом шаге цикла. Ошибки агента — это 200 с неверным решением внутри. |
| Health-check 200 | «процесс жив» | Живой процесс может крутить бесконечный цикл и жечь деньги — он и «жив», и «не работает» одновременно. |
| p95 latency (per request) | «один вызов быстрый» | latency шага в норме; latency задачи (= сумма N шагов) растёт квадратично, и его никто не мерит «на задачу». |
| Counter вызовов к агенту | «сколько циклов запустили» | Не говорит, сколько итераций сожрал каждый цикл. 1 цикл × 50 итераций = 50 × 1 цикл по деньгам, но не по этой метрике. |
Правильная ось для агента — успех, измеренный по факту полезного действия, а не по коду ответа. Три способа его определить:
- Завершённость цикла — цикл вышел по своему штатному признаку конца (
finish_reason=stop,tool_call= none, достигнут лимит итераций), а не оборвался таймаутом процесса. - Полезный исход — был создан PR, применена правка, дан ответ (у Claude Code это счётчики
pull_request.count,commit.count,lines_of_code.count). - Исход инструмента — каждый вызов инструмента помечен
success+duration_ms+error_type, а не «HTTP-статус инструмента».
Это не отменяет ваших текущих алертов — это надстройка над ними. Ваш Prometheus из «Метрики и мониторинг» остаётся мерить «жив ли сервер»; поверх появляется вопрос «а справился ли агент, и чего ему это стоило».
Часть IV. Три агентных сигнала и словарь, который их описывает
Если унести из статьи одно — унесите эти три сигнала. У классического APM их нет, потому что у классического приложения нет циклов, решений и счётчика денег на операцию.
Сигнал 1: итерации на задачу
Сколько проходов сделал цикл. Это ваш loop guard: без него runaway loop невидим. Как считать — в Части V.
Сигнал 2: стоимость на задачу
Накопленные input_tokens + output_tokens (+ cache_read / cache_write, у кого есть caching), пересчитанные в деньги. Claude Code отдаёт это прямо: метрика claude_code.token.usage (с атрибутом type = input/output/cacheRead/cacheCreation) и claude_code.cost.usage (USD). В OpenTelemetry GenAI для этого группа атрибутов gen_ai.usage.*:
# otel-genai-demo.py — как выглядят "итерации" и "стоимость" в терминах OTel GenAI
# (имена атрибутов — из реестра на 07.11.2026, СТАТУС = Development, см. ниже «осторожно»)
from opentelemetry import trace
tracer = trace.get_tracer("agent-loop")
def run_agent_turn(history):
# span на один вызов модели: операция = chat
with tracer.start_as_current_span("chat qwen3-coder") as span:
span.set_attribute("gen_ai.operation.name", "chat")
span.set_attribute("gen_ai.provider.name", "openai") # НЕ gen_ai.system (старое имя)
span.set_attribute("gen_ai.request.model", "qwen3-coder")
span.set_attribute("gen_ai.conversation.id", history.session_id) # ось цикла
resp = call_llm(history)
span.set_attribute("gen_ai.usage.input_tokens", resp.usage.input)
span.set_attribute("gen_ai.usage.output_tokens", resp.usage.output)
# длительность вызова модели — отдельная гистограмма, не generic-метрика:
# gen_ai.client.inference.duration (s), gen_ai.server.time_to_first_token (s)
return resp
Стоимость как сигнал отличается от стоимости как отчёта. Отчёт («сколько мы потратили за месяц») нужен бухгалтеру. Сигнал («эта конкретная задача сожрала 12k токенов и не завершается») нужен вам, чтобы поймать runaway loop до счёта. Это одно и то же число в разных разрезах: отчёт считает по аккаунту/дню, сигнал — по conversation.id.
Сигнал 3: решения (какой инструмент, принят/отклонён, успех/ошибка)
Здесь живёт tool misuse. OTel GenAI выделяет для этого отдельную операцию execute_tool (span execute_tool {gen_ai.tool.name}) и invoke_agent (когда поток управления ведёт LLM), а инструментные исходы и решения — то, что Claude Code кладёт в tool_result/tool_decision. Без этого сигнала вы видите «агент что-то делал», но не видите «агент не туда делал».
Осторожно: стандарт есть, но он Development — и имена уже менялись
Это не сноска, а предмет разговора. GenAI-семантические конвенции OpenTelemetry имеют статус Development (стабильны пока только общие error.type, server.*, network.*, exception.*). Более того, они переехали из основного репозитория semantic-conventions в отдельный open-telemetry/semantic-conventions-genai, и по дороге переименовали часть имён. Что изменилось и почему это важно при написании кода — полностью в №2; здесь зафиксируем правило серии:
Не хардкодьте дословное имя атрибута как контракт. Пишите слой так, чтобы смена имени (
gen_ai.system→gen_ai.provider.name,gen_ai.client.token.usage→gen_ai.client.inference.usage.*) была одной строкой конфигурации, а не миграцией дашбордов. Привязывайтесь к схеме («у меня есть поле «входные токены на вызов модели»»), а к имени атрибута — только на уровне адаптера, который вы меняете, когда спека сдвигается.
Часть V. Начать можно без SaaS: кольцевой журнал + breaker + loop guard
Самая частая реакция на «нужна observability» — «значит, надо поставить Langfuse/Grafana Cloud/Jaeger». Иногда да. Но для веб-мастера с PHP-сайтом на VPS, который встроил пару LLM-инструментов и не хочет отправлять содержимое промптов во внешний облачный SaaS, есть путь покороче и честнее по приватности (та же линия «владей данные сам», что в «Локальные модели для приватности»). Покажем три скелета — концепции, не имена конкретного продукта.
1. Кольцевой буфер последних N событий (event ring)
Когда провайдер начал валить 429, а потом вернул 403, вам не нужен весь лог за неделю — вам нужна последняя лента событий вызова, чтобы за минуту увидеть паттерн (это ровно то, что делает кольцевой журнал авторского слоя (из №6); здесь — абстрактная реализация).
<?php
// ai-event-ring.php — кольцевой журнал последних N событий AI-вызова.
// Хранится в одной option/таблице; без внешних зависимостей.
// Домены/ключи — плейсхолдеры example.test.
function ai_ring_push( array $event ): void {
$max = 200;
$ring = get_option( 'ai_event_ring', [] );
$event['ts'] = time();
// Нормируем в плоский массив: что за операция, чем, код, длительность, session.
$event['op'] = $event['op'] ?? 'unknown'; // chat | execute_tool | invoke_agent
$event['provider'] = $event['provider'] ?? 'unknown'; // id провайдера (не секрет!)
$event['model'] = $event['model'] ?? '';
$event['http'] = $event['http'] ?? 0; // код транспорта, 0 = не дошёл
$event['class'] = ai_classify( $event ); // ВАЖНО: не сырой http (см. ниже)
$event['dur_ms'] = $event['dur_ms'] ?? 0;
$event['conv'] = $event['conv'] ?? ''; // conversation.id — ось цикла
$ring[] = $event;
if ( count( $ring ) > $max ) {
$ring = array_slice( $ring, -$max ); // оставляем хвост: это и есть «кольцо»
}
// autoload=false — не тащим 200 событий в каждый автозагрузочный SELECT.
update_option( 'ai_event_ring', $ring, false );
}
function ai_ring_recent( int $n = 30 ): array {
$ring = get_option( 'ai_event_ring', [] );
return array_slice( $ring, -$n );
}Кольцо — это дешёвая замена «платформы логов» для задачи «загляни и посмотри, что происходило последние несколько минут». У него есть потолок глубины (200 событий), и это нормально: наблюдаемость агента нужна не для месячной аналитики, а чтобы ответить на «почему этот цикл не закончился прямо сейчас».
2. class вместо http: классификатор сбоя
Главная ошибка, которую делает слой «на кодах статусов»: он лечит код, а надо лечить класс сбоя (из Части II.3). Код 403 у вас означает и «провайдер жив, модели нет», и «ключ-пара-доступ запрещён», и «несанкционированный запрос» — а действовать надо по-разному.
<?php
// ai-classify.php — один источник правды: «что именно случилось».
// Возвращает класс, по которому решаем — retry / breaker / alert / ignore.
function ai_classify( array $event ): string {
$http = (int) $event['http'];
if ( 0 === $http ) {
return 'transport'; // curl/файрвол/таймаут — до API не дошли.
}
if ( 200 <= $http && $http < 300 ) {
return 'ok'; // транспорт ОК; semantic-успех — уже по содержимому (не здесь).
}
if ( 429 === $http ) {
return 'rate'; // провайдер ЖИВ, режет частоту. retry с backoff, НЕ breaker.
}
if ( 404 === $http ) {
return 'no_deploy'; // «модели нет на этом эндпоинте» — не болезнь провайдера.
}
if ( 403 === $http ) {
// Критично: 403 НЕ равен «провайдер мёртв». Часто это доступ к конкретной модели.
// Тело несёт код вида team_model_access_denied / model_not_found:
$detail = $event['detail'] ?? '';
if ( false !== strpos( $detail, 'access_denied' ) ) {
return 'access_denied'; // пара «ключ↔модель» запрещена; транспорт здоров.
}
return 'forbidden';
}
if ( 500 <= $http && $http < 600 ) {
return 'overload'; // провайдер/модель перегружены или легли. Кандидат под breaker.
}
return 'other';
}Заметьте: ok по транспорту ≠ успех агента. ai_classify отвечает на «дошёл ли запрос», а «полезно ли модель поступила» — уже по содержимому (finish_reason, tool_result.success), и это другая функция (Сигнал 3). Разделение принципиальное — именно оно спасает вас от «зря завалили живого провайдера».
3. Loop guard + breaker: счётчики, которых нет в APM
Два счётчика, без которых агентные сбои Части II невидимы.
<?php
// ai-loop-guard.php — и счётчик итераций (ловит runaway loop), и breaker
// (отделяет "болезнь" провайдера от опечатки/403-по-доступу).
// --- Loop guard: счётчик итераций НА conversation, не на запрос ---
function ai_iter_bump( string $conv ): ?int {
$key = 'ai_iter_' . md5( $conv );
$count = (int) get_transient( $key ) + 1;
set_transient( $key, $count, 3600 ); // окно жизни = типичной длительности одной задачи
if ( $count > 40 ) {
// Кандидат на runaway loop. Не убиваем молча: пишем событие в кольцо и алертим.
ai_ring_push( [ 'op' => 'invoke_agent', 'class' => 'loop_alarm', 'conv' => $conv, 'iter' => $count ] );
}
return $count;
}
// --- Circuit breaker: только по классам "болезнь транспорта/перегрузка" ---
// access_denied / no_deploy НЕ гасят провайдера — это не его болезнь.
function ai_breaker_register( string $provider, string $class ): void {
$fail_key = 'ai_br_fails_' . $provider;
$open_key = 'ai_br_open_' . $provider;
$is_illness = in_array( $class, [ 'transport', 'overload' ], true ); // НЕ 'rate', НЕ 'access_denied'
$fails = $is_illness ? (int) get_transient( $fail_key ) + 1 : 0;
if ( $fails >= 5 ) {
set_transient( $open_key, 1, 300 ); // «нездоров» на 5 минут → следующий шаг уйдёт на failover
delete_transient( $fail_key );
ai_ring_push( [ 'op' => 'invoke_agent', 'provider' => $provider, 'class' => 'breaker_open' ] );
} else {
set_transient( $fail_key, $fails, 60 ); // окно, в котором считается «подряд»
}
}
function ai_provider_unhealthy( string $provider ): bool {
return (bool) get_transient( 'ai_br_open_' . $provider );
}Три детали, за которые этот скелет уже стоит того, чтобы его иметь:
- loop guard считает итерации по
conversation— ровно то, чего нет у rps/latency, и ровно то, что делаетrunaway loopвидимым; - breaker открывается по классу, а не по коду — потому что 429 (
rate) — не повод валить провайдера (он жив, это retry), а 403access_denied— тем более (падает пара «ключ↔модель», не транспорт); - каждое интересное событие пишется в кольцо, и вы чините по ленте из Части V.1, а не гадаете.
Это не полноценная наблюдаемость-платформа — и не претендует. Это минимальный слой, который закрывает три сигнала Части IV, живёт на одном WordPress без sidecar’а и не отправляет содержимое промптов наружу. Полная сборка (журнал + breaker + health-монитор моделей + экспорт в Prometheus, чтобы встроиться в ваш metiki-i-monitoring) — №6.
Инструменты под задачу
- Разобрать ленту событий / найти паттерн в логах вызова — AI-анализатор логов на codestack.space: вставьте выгрузку кольцевого журнала (Часть V.1) или фрагмент логов провайдера — инструмент выделит, что происходит (каскад 429, повторяющийся инструмент, тихая деградация).
- Прогнать свой цикл агента и попросить разобрать построчно — AI-ассистент для кода: покажите свою реализацию loop/breaker и спросите «где этот цикл может уйти в runaway и не заметить этого».
Чек-лист граблей
- Мерить rps агента вместо итераций. 1 цикл × 30 итераций выглядит как «1 запрос, всё спокойно». Заведите счётчик итераций на
conversation.id— иначеrunaway loopдля вас невидим до счёта за API. - Считать 200 успехом. Успех агента — это завершённость цикла и исход инструмента (
success,finish_reason, создан ли PR), а не код ответа. Отдельный вызов мог вернуть 200 с неверным решением внутри. - Лечить код статуса, а не класс сбоя.
403— это и «модели нет», и «доступ к модели запрещён на уровне команды», и «не тот ключ». Breaker надо включать по классу (transport/overload— да,rate/access_denied/no_deploy— нет), иначе вы валите живого провайдера из-за опечатки в имени модели. - Открывать breaker по 429. Rate-limit — это «провайдер жив, но режет частоту»; правильный ответ — backoff+retry, а не failover на второго (второй через минуту начнёт резать так же). См. механику лимитов в «Защита API: rate limiting».
- Хардкодить имя атрибута
gen_ai.*как контракт. Спека —Developmentи уже переименовывала (gen_ai.system→gen_ai.provider.name,client.token.usage→client.inference.usage.*). Держите маппинг имён в одном адаптере. - Ставить платформу до того, как поняли, что мерить. Кольцевой журнал + loop guard + breaker (Часть V) дают основную пользу без Langfuse/Cloud/Jaeger и без утечки промптов. Платформа нужна, когда этих трёх сигналов мало, а не как первый шаг.
- Ждать ошибки там, где её не будет. Агент, уходящий в рекурсию, бросает 0 исключений и 0 ERROR-строк в логе. Ваш единственный индикатор — «цикл не завершился за ожидаемое число шагов и стоимость растёт». Если вы не меряете итерации/стоимость/завершённость, вы этого не увидите никогда.
- Смешать клиентское «наблюдение» с серверным.
IntersectionObserverиз статьи про DOM не имеет отношения к наблюдаемости агента. Уточняйте в команде, о каком из двух «наблюдений» речь — как мы делали с «воркером» в Edge-серии.
👤 Зарегистрируйтесь, чтобы добавить материал в закладки.
