Как мы отлаживали мультиагентную систему с помощью OpenTelemetry и SigNoz

Зачем читать эту статью

Мультиагентные системы — это мощно, но они ломаются неочевидными способами. Модель может вернуть успешный ответ, но результат будет бесполезен. Fallback может сработать так гладко, что никто не заметит, что основной агент мёртв. Латентность может утроиться, потому что один агент начал думать вдвое дольше. В этой статье я покажу на реальных примерах, как OpenTelemetry и SigNoz помогли нам найти 6 проблем, которые мы бы никогда не увидели, просто читая код. Вы узнаете, какие запросы к ClickHouse писать, как настроить алерты и как сделать так, чтобы ваша система сама себя чинила.

Что такое DevSwarm и как он устроен

DevSwarm — это мультиагентная система, которая по одному промпту генерирует полноценное full-stack приложение. Пять открытых моделей работают в ролях: планировщик, фронтенд, бэкенд, критик и доктор. Каждый шаг трассируется через OpenTelemetry и отправляется в SigNoz. Вот роли и модели:

• Планировщик (GLM-5.2): превращает промпт в план сборки и контракт API.
• Фронтенд (GLM-5.2): генерирует index.html по контракту.
• Бэкенд (Qwen3-Coder-480B): пишет Express-сервер по тому же контракту.
• Критик (Kimi-K2.7-Code): проверяет оба артефакта на соответствие контракту, безопасность и баги.
• Доктор (GLM-5.2): читает собственные трейсы и чинит маршрутизацию.

Критик — самая нагруженная часть. Фронтенд и бэкенд генерируются параллельно, затем независимая модель проверяет оба. Если найдены проблемы, они возвращаются агенту, который их исправит, и критик перепроверяет только изменения. После двух раундов система выдаёт честный вердикт.

Почему мы сначала сделали наблюдаемость, а не код

Мультиагентная система ломается иначе, чем обычное приложение. Вызов может успешно выполниться, но результат будет бесполезен. Fallback может незаметно спасти запрос. Латентность может вырасти из-за того, что один агент начал думать дольше. В логах запросов этого не видно. Поэтому первым рабочим артефактом в проекте стал не код генерации, а трейс.

SigNoz мы развернули через Foundry — один конфиг. Файлы casting.yaml и casting.yaml.lock хранятся в репозитории, так что развёртывание воспроизводимо.

Три сигнала и что они несут

Трейсы

Каждый вызов модели — это спан с именем llm.<роль> и атрибутами GenAI:

span.setAttributes({
    'gen_ai.operation.name': 'chat',
    'gen_ai.request.model': model,
    'gen_ai.usage.input_tokens': usage.prompt_tokens,
    'gen_ai.usage.output_tokens': usage.completion_tokens,
    'devswarm.role': role
});

Два события спана — ключевые для диагностики:

• fallback_promotion — запись о том, что основной агент отказал, какая модель его заменила и причина.
• critic_catch — каждая проблема, найденная критиком, с указанием цели и серьёзности.

Метрики

Шесть счётчиков и одна гистограмма: devswarm.tokens, devswarm.llm.calls, devswarm.llm.duration, devswarm.fallback.promotions, devswarm.critic.catches, devswarm.generations, devswarm.refinements. Размечены по роли, модели и исходу.

Логи

Структурированные записи для инцидентов: fallback, диагноз доктора, завершение генерации с вердиктом. Те же атрибуты ресурсов, что и у трейсов, чтобы лог и спан совпадали.

Весь слой трассировки выделен в библиотеку otel-swarm, которую можно подключить в любую мультиагентную систему.

Что мы узнали из трейсов: 6 откровений

1. Критик стоит в 15 раз дороже бэкенда

Токены и стоимость за одну генерацию:

Критик стоит в 15 раз больше бэкенда, потому что читает оба артефакта полностью, дважды. Никто не закладывает это в бюджет. Если вы строите шлюз ревью, он не будет округлением — это треть счёта.

2. Неудачная генерация стоит дороже успешной

Худшие генерации сжигали 232 000 токенов, лучшие — 74 000. Конвергенция — это не только метрика качества, но и метрика стоимости. Исправление бага в формате контракта дало больше экономии, чем любая замена модели.

3. Фронтенд — самое слабое звено

Запрос к ClickHouse по событиям критика:

SELECT
    JSONExtractString(e, 'attributeMap', 'severity') AS severity,
    JSONExtractString(e, 'attributeMap', 'target') AS target,
    count() AS catches
FROM signoz_traces.distributed_signoz_index_v3
ARRAY JOIN events AS e
WHERE serviceName = 'devswarm'
  AND name = 'agent.critic'
  AND JSONExtractString(e, 'name') = 'critic_catch'
GROUP BY severity, target
ORDER BY catches DESC;

Результат за неделю: 221 высокая, 46 средних, 10 низких проблем. Фронтенд — получатель 70% из них. Половина системы, генерирующая разметку и клиентское состояние, — источник багов, а не половина, работающая с базой данных.

4. Мы винили модель в лимитах, которые сами установили

Один из fallback-ов срабатывал из-за того, что мы ограничили время ответа модели до 30 секунд. Модель была в порядке, но лимит был слишком жёстким. Трейс показал, что падала не модель, а наш таймаут.

5. Мы винили провайдера в отказе модели

Когда модель возвращала ошибку, мы думали, что проблема у провайдера. Но трейс показал, что ошибка была в формате запроса — мы передавали неверные параметры. Провайдер был ни при чём.

6. Мы потратили дни на дизайн-систему, которая ухудшала результат

Мы написали дизайн-систему для генерации UI, но метрики показали, что приложения с ней имеют больше ошибок и ниже оценку пользователей. Без неё результаты были лучше. Пришлось удалить.

Алерты, которые будят агента, а не человека

У нас два правила алертов в observability/alerts/: всплеск fallback-ов и падение количества срабатываний критика. Оба шлют уведомление в вебхук swarm-doctor, который указывает на POST /api/doctor/webhook самого роя.

Когда алерт срабатывает, Доктор просыпается, читает трейсы за последний час и решает, что делать с таблицей маршрутизации. Он может повысить резервную модель, сбросить восстановленную основную или ничего не делать, а затем объясняет своё решение на русском языке, используя числа из трейсов.

Первый реальный диагноз: «Роль критика — явная проблема: её основная модель вызвала 6 fallback-продвижений из 9 вызовов (67%) с уровнем ошибок 22% и p95 латентностью 242 с. Бэкенд, планировщик и доктор здоровы».

Доктор сам трассируется, поэтому целитель так же наблюдаем, как пациент.

Практический вывод: что делать прямо сейчас

1. Добавьте OpenTelemetry в вашу мультиагентную систему. Начните с трассировки каждого вызова модели — это займёт пару часов, но окупится сторицей.

2. Используйте SigNoz для хранения и визуализации трейсов. Он self-hosted, прост в установке и поддерживает ClickHouse.

3. Настройте алерты на аномалии. Не ждите, пока пользователь сообщит о проблеме.

4. Сделайте так, чтобы ваша система могла сама себя чинить. Агент-доктор, читающий трейсы, — это не фантастика, а рабочий код.

5. Доверяйте телеметрии больше, чем интуиции. Почти всё, что мы думали о своей системе, оказалось неверным.