Бывало у вас такое: месяцами пилишь архитектуру, фичи летят одна за другой, тесты зелёные. Всё работает. А потом в какой-то момент ловишь себя на мысли: «Черт, я вообще перестал понимать, как эта штука работает».
Именно это произошло со мной во время разработки PAD+ AI. После очередного раунда из миллионов тестов я осознал, что полностью потерял контроль над системой.
Проблема наблюдаемости в AI-системах
К тому моменту PAD+ AI уже умел многое: работал с памятью, пайпланами, эмоциями, Truth Loop и персонами. Результаты становились всё лучше, но вылезла неожиданная проблема.
Когда система ошибалась, было совершенно непонятно, почему. Она просто выдавала ответ. Иногда отличный, иногда странный, иногда вообще непредсказуемый. Всё происходило где-то внутри.
Обычно всё выглядит просто: отправил запрос, получил ответ. Но стоит добавить память, RAG, пару агентов и внешние сервисы — и эта линейная схема превращается в клубок. На уровне результата видно только вход и выход, но совершенно неясно:
-
какие именно компоненты участвовали в обработке;
-
в каком порядке они отрабатывали;
-
где конкретно возникла задержка или ошибка;
-
как менялось состояние системы по ходу дела.
В сложных системах это приводит к полной потере объяснимости. Я видел только вход и выход. А между ними было абсолютное чёрное пространство.
Так появилась концепция трасс
После очередной серии неудачных тестов я задал себе вопрос, который в итоге перевернул архитектуру проекта: «А что, если попробовать посмотреть на проблемы изнутри?»
Так и родилось название X-Ray. Простая аналогия: мне нужен был инструмент, который работает как рентген, показывая не просто симптом, а всю «костную структуру» процесса выполнения.
Я перестал смотреть на отдельные события и начал анализировать сам путь выполнения. Каждый пользовательский запрос превратился в отдельную Trace. Внутри неё каждая операция стала отдельным Span. В итоге получилась структура, напоминающая дерево выполнения:
Trace├── Safety├── Intent├── RAG├── Knowledge Graph├── Semantic Memory├── Persona├── Generate├── Truth Loop└── Response Guard
Теперь можно было увидеть не только последовательность выполнения, но и время прохождения каждой фазы, взаимосвязь между этапами и полный путь обработки запроса.
Сразу проясню один момент
Давайте расставим точки над «i»: X-Ray — это не замена логам.
Логи просто кричат «тут упало» или «произошло событие X». Трасса же говорит: «вот полный путь, которым система пришла к результату, со всеми зависимостями, временными метками и контекстом». Это позволяет восстанавливать полную картину обработки запроса даже спустя недели. Именно тогда стало понятно, что мы имеем дело с совершенно другим классом инструментов.
Почему X-Ray вынесло в отдельный проект
Изначально X-Ray создавался исключительно для PAD+ AI и жил внутри его когнитивного pipeline. Но довольно быстро выяснилась интересная вещь: библиотека практически ничего не знает о когнитивной архитектуре.
Ей безразлично, что именно крутится внутри: LLM, REST API, Telegram-бот, микросервис или платёжная система. Любой процесс можно представить как последовательность связанных операций. Это означало, что X-Ray можно использовать далеко за пределами моего ИИ-проекта. Так он превратился в самостоятельную библиотеку.
Что представляет собой X-Ray сегодня
Сегодня это production-ready библиотека наблюдаемости, которую можно встроить практически в любой Python-проект. Её задача — не управлять приложением и не принимать решения, а максимально подробно фиксировать ход выполнения.
Под капотом X-Ray реализует:
-
модель Trace / Span;
-
прозрачное распространение
trace_idмежду сервисами (propagation); -
middleware-интеграцию (например, для FastAPI);
-
persistence — запись трасс на диск с автоматическим восстановлением после перезапуска;
-
гибкие режимы работы:
live,shadow,readonly,disabled; -
аудит целостности трасс и поиск нарушений причинно-следственных связей;
-
инструменты валидации и санитизации повреждённых данных;
-
REST API для доступа к трассам и результатам аудита.
По своей роли X-Ray можно сравнить с бортовым самописцем самолёта. Он не предотвращает ошибки и не исправляет их автоматически. Он делает гораздо более важную вещь: сохраняет полную картину произошедшего, чтобы инженер мог понять, почему система пришла именно к такому результату.
Persistence и восстановление
Каждый завершённый трейс записывается на диск в JSON. При перезапуске все трейсы восстанавливаются автоматически. Активные трейсы помечаются как interrupted, но все их спэны сохраняются.
trace_store/├── traces/{trace_id}.json├── spans/{trace_id}/span_{id}.json├── index.json├── archive/ # Архивы retention└── quarantine/ # Повреждённые данные
Пример интеграции в FastAPI
Для подключения X-Ray к приложению на FastAPI достаточно добавить middleware и передавать идентификатор трассы между вызовами. Базовая интеграция занимает буквально несколько минут.
1. Подключение middleware:
from fastapi import FastAPI, Requestfrom aethon.xray.http_propagation import fastapi_extract_xrayapp = FastAPI()@app.middleware("http")async def xray_middleware(request: Request, call_next): headers = fastapi_extract_xray(request) trace_id = headers.get("trace_id", "") response = await call_next(request) if trace_id: response.headers["X-Trace-Id"] = trace_id return response
Нюанс:
fastapi_extract_xrayвозвращает не скаляр, а словарь из 5 полей:trace_id,span_id,parent_span_id,logical_ts,causal_depth. Это необходимо для полной поддержки propagation-контекста между сервисами.
2. Обёртка внешних вызовов:
from aethon.xray import start_span, SpanKindasync def call_provider(): span = start_span(kind=SpanKind.EXTERNAL, name="provider_call") try: result = await provider.call() span.end(success=True) return result except Exception: span.end(success=False) raise
3. Конфигурация persistence (в коде):
from aethon.xray.trace_store import store# Включение записи трейсов на дискstore.configure_persistence("./data/trace_store")
4. Проверка работоспособности:
GET /health → {"status": "ok", "mode": "live", "trace_store": true}GET /xray/audit/{trace_id} → {"trace_id": "...", "all_passed": true}GET /xray/traces → {"traces": [...]}
После этого система начинает автоматически строить полную картину выполнения запросов, сохранять трассы, поддерживать несколько режимов работы, проводить аудит целостности данных и восстанавливать историю после перезапуска.
Где X-Ray уже работает
X-Ray не остался на бумаге. Сегодня он работает в продакшене как часть приложения PAD+ AI, развёрнутого на Render.
Что можно увидеть в реальном времени:
Pasted image 20260716230033.png
Каждый запрос, проходящий через PAD+, оставляет за собой полную трассу, и за этим можно наблюдать в реальном времени:
🔴 Live-режим через WebSocket. Специальный endpoint /api/v1/xray/ws отправляет события trace_event на фронтенд. Вы видите, как запрос проходит через все стадии pipeline: Safety → Intent → Retrieve → Persona → Generate → Verify → Remember → Emit. Каждая стадия подсвечивается, показывается время выполнения и статус. Это как смотреть на ЭКГ в реальном времени.
📊 Визуализация pipeline. Фронтенд-компонент XRayPipeline.jsx показывает активную стадию, завершённые этапы и общее время обработки.
📜 История трейсов. Через endpoint GET /api/v1/xray/recent?limit=50 можно получить последние 50 завершённых сессий с деталями: user_message, start_time, events, metadata, stage_times и total_time_ms. Компонент TraceHistory.jsx позволяет искать и фильтровать их по статусу.
🔍 Детальный просмотр и экспорт. Через GET /api/v1/xray/sessions/{session_id} можно получить полную информацию о конкретной сессии и экспортировать данные в JSON или CSV для внешнего анализа.
💾 Персистентность. В памяти хранятся последние 100 сессий, а завершённые трейсы сохраняются на диск.
Область применения
После отделения от PAD+ AI оказалось, что X-Ray можно использовать для микросервисной архитектуры, AI-приложений с несколькими LLM-провайдерами, Telegram- и VK-ботов, систем обработки документов, RAG-приложений, платёжных шлюзов и распределённых API.
Фактически, любая программа, в которой важно понимать не только итог работы, но и путь, которым система к нему пришла, может использовать X-Ray.
Но на этом история не закончилась
После появления X-Ray произошло ещё одно неожиданное открытие. Система действительно научилась видеть всё, что происходит внутри: каждую фазу, каждую ошибку, каждое отклонение и деградацию.
И однажды возник следующий вопрос: если система уже умеет видеть собственные проблемы… почему она не может начать исправлять их самостоятельно?
Именно этот вопрос позже привёл к созданию ещё одного независимого проекта — HEALER. Но это уже совсем другая история.
Ссылки и материалы
📖 PAD+ AI v4.0: исследовательская когнитивная архитектура поверх LLM — первая статья о проекте, для которого изначально создавался X-Ray. Рекомендую начать с неё, чтобы понять контекст.
💻 GitHub: xray-integration-kit — исходный код библиотеки. Репозиторий пока приватный, но если хотите изучить архитектуру, предложить улучшения или просто обсудить трассировку — пишите, открою доступ заинтересованным.
🔗 PAD+ AI на Render — живое демо, где можно увидеть работу X-Ray в реальном времени.
📚 https://github.com/Ovladimirovich/xray-integration-kit/blob/master/docs/xray/INSTALL.ru.md — полное руководство по установке и настройке X-Ray: минимальная интеграция за 5 минут, описание режимов работы, структура persistence и production-чеклист.
💬 Telegram: @padplusai — для вопросов, предложений и запросов на доступ к репозиторию.
ссылка на оригинал статьи https://habr.com/ru/articles/1060004/