Есть одна коварная особенность в разработке сложных систем.

Иногда ты месяцами строишь архитектуру. Добавляешь новые возможности, исправляешь ошибки. Всё работает. А потом вдруг понимаешь одну очень неприятную вещь:

Ты больше не понимаешь собственную программу.

Именно это произошло и со мной во время разработки PAD+ AI. После миллионов тестов я осознал, что потерял контроль.

Проблема наблюдаемости в AI-системах

PAD+ AI уже умел многое: работал с памятью, пайплайнами, эмоциями, Truth Loop и персонами. Результаты становились всё лучше. Но возникла совершенно неожиданная проблема.

Когда система ошибалась, невозможно было понять почему. Она просто отвечала. Иногда отлично, иногда странно, иногда неожиданно. Но всё происходило где-то внутри.

Современные приложения на базе LLM обычно имеют простую архитектуру:

Запрос → Prompt → LLM → Ответ

Но при добавлении памяти, RAG, агентов и дополнительных сервисов система становится существенно сложнее. На уровне результата видно только вход и выход, но не видно:

• какие компоненты участвовали в обработке;

• в каком порядке выполнялись операции;

• где возникла задержка или ошибка;

• как изменялось состояние системы.

В сложных системах это приводит к полной потере объяснимости поведения. Я видел только вход. И видел выход. А между ними было абсолютное чёрное пространство.

Так появилась концепция трасс

После очередной серии тестов я задал вопрос, который полностью изменил архитектуру проекта:
«А что, если посмотреть на проблемы изнутри?»

Именно с этого вопроса началась история X-Ray. Название родилось сразу: ведь рентген позволяет увидеть то, что скрыто от глаз.

Я начал смотреть не на отдельные события, а на сам путь выполнения. Каждый пользовательский запрос превратился в отдельную Trace. Внутри неё каждая операция стала отдельным Span. Получилась структура, напоминающая дерево выполнения:

Trace
├── Safety
├── Intent
├── RAG
├── Knowledge Graph
├── Semantic Memory
├── Persona
├── Generate
├── Truth Loop
└── Response Guard

Теперь можно было увидеть не только последовательность выполнения, но и время прохождения каждой фазы, взаимосвязь между этапами и полный путь обработки запроса.

Важное уточнение: это не логирование

Важно отметить, что X-Ray не является системой логирования.

Логирование фиксирует события. X-Ray фиксирует структуру выполнения процесса. Это принципиально разные вещи. Лог говорит: «произошло событие X». Трасса говорит: «вот полный путь, которым система пришла к результату, со всеми зависимостями и временами».

Это позволяет восстанавливать полную картину обработки запроса — даже спустя дни и недели.

Именно в этот момент стало понятно, что речь уже идёт не о простом логировании. Получался совершенно другой класс инструмента.

Почему X-Ray стал самостоятельным проектом

Изначально X-Ray создавался исключительно для PAD+ AI и использовался внутри когнитивного pipeline. Но довольно быстро выяснилась неожиданная вещь: он практически ничего не знает о когнитивной архитектуре.

Ему безразлично, что именно работает внутри: LLM, REST API, Telegram-бот, микросервис или платёжная система. Любой процесс можно представить как последовательность связанных операций. Это означало, что X-Ray можно использовать далеко за пределами моего ИИ-проекта.

Именно тогда он превратился в самостоятельную библиотеку.

Что представляет собой 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, Request
from aethon.xray.http_propagation import fastapi_extract_xray

app = 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, SpanKind

async 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.

Ссылка: https://pad-plus-ai.onrender.com

Что вы можете увидеть в реальном времени

Каждый запрос, который проходит через 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+, оставляет за собой полную трассу — от Safety-проверки до финальной стадии Verify. Эти трассы сохраняются, аудируются и доступны для анализа в реальном времени.

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

После отделения от PAD+ AI оказалось, что X-Ray можно использовать для:

• микросервисной архитектуры;

• AI-приложений с несколькими LLM-провайдерами;

• Telegram- и VK-ботов;

• систем обработки документов и RAG-приложений;

• платёжных шлюзов и сложной бизнес-логики;

• распределённых API и агентных систем.

Фактически любая программа, в которой важно понимать не только итог работы, но и путь, которым система пришла к результату, может использовать X-Ray.

Но на этом история не закончилась

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

И однажды возник следующий вопрос:
Если система уже умеет видеть собственные проблемы… почему она не может начать исправлять их самостоятельно?

Именно этот вопрос позже привёл к созданию ещё одного независимого проекта — HEALER.

Но это уже совсем другая история.

Ссылки и материалы

? PAD+ AI v4.0: исследовательская когнитивная архитектура поверх LLM — первая статья о проекте, для которого изначально создавался X-Ray. Если вы ещё не читали, рекомендую начать с неё, чтобы понять контекст. https://habr.com/ru/articles/1055242/

GitHub: https://github.com/Ovladimirovich/xray-integration-kit — исходный код библиотеки. Репозиторий пока приватный, но если хотите изучить архитектуру, предложить улучшения или просто обсудить трассировку — пишите, открою доступ заинтересованным. https://github.com/Ovladimirovich/xray-integration-kit.git

? PAD+ AI на Render — живое демо, где можно увидеть работу X-Ray в реальном времени через WebSocket-визуализацию pipeline. https://pad-plus-ai.onrender.com/?spm=a2ty_o01.29997173.0.0.a48a55fbXrvt8z

INSTALL.ru.md — полное руководство по установке и настройке X-Ray: минимальная интеграция за 5 минут, описание режимов работы (live, shadow, readonly, disabled), структура persistence и production-чеклист.

Telegram: https://t.me/padplusai — для вопросов, предложений и запросов на доступ к репозиторию.