Документация Adapstory

Метрики, трейсы, логи и профили для плагинов в продакшене.

Плагины получают инструментирование бесплатно, но понимание того, что эмитится и как читать — ускоряет дебаг на порядок.

Четыре столпа

Столп	Инструмент	Где смотреть
Метрики	Prometheus	`grafana.adapstory.com` → dashboard `Plugin Overview`
Трейсы	Tempo	`grafana.adapstory.com` → Explore → Tempo
Логи	Loki	`grafana.adapstory.com` → Explore → Loki
Профили	Pyroscope	`grafana.adapstory.com` → Pyroscope, или Tempo → Profiles link

Все четыре связаны по trace.id и tenant.id.

Автоинструментирование

Каждый pod плагина получает:

OTEL sidecar — собирает OTLP-трейсы с порта 4318.
Alloy eBPF DaemonSet — CPU-профили (без изменений в коде, interpreter tracer для Python/JVM/Go/V8/Ruby).
Fluent Bit — хвостит stdout контейнера, отправляет JSON в Loki.
ServiceMonitor — скрейпит /metrics на порту 9090 если есть.

Что эмитит SDK

Каждый handler @mcp_tool эмитит:

Span plugin.{name}.tool.{tool_name} с атрибутами:
- tenant.id, user.id, plugin.version, llm.session.id
- llm.tokens.prompt, llm.tokens.completion, llm.model, llm.cost_usd
Метрика plugin_tool_duration_seconds (histogram) с labels tool, tenant, version, outcome
Метрика plugin_llm_tokens_total (counter) с labels tool, tenant, model, direction (prompt/completion)
Log event plugin.tool.invoked + plugin.tool.completed на INFO

SLO которые платформа трекает за вас

SLO	Target	Window
Success rate инструмента	99.5%	30d
p99 latency инструмента	Декларирован в манифесте	30d
Burn бюджета LLM	Ниже декларированного `gatewayBudget`	1d rolling

Burn-rate алерты пейджат on-call при пробое 14.4× burn за 1h и 6× за 6h (Google SRE multi-window/multi-burn-rate). Настройка не нужна.

Добавление бизнес-метрик

Используйте SDK metrics helper:

from adapstory_plugin_sdk import meter

counter = meter.create_counter(
    name="plugin.courses_recommended",
    description="Recommendations emitted per tenant",
    unit="1",
)

counter.add(1, attributes={"course_type": course.kind})

Метрики автоматически префиксируются именем плагина и тегируются tenant.id. Появляются в Prometheus за ~30 секунд.

Добавление трейсов

OTel SDK уже сконфигурирован. Просто создавайте spans:

from adapstory_plugin_sdk import tracer

with tracer.start_as_current_span("rank_recommendations") as span:
    span.set_attribute("candidates", len(candidates))
    result = await rank(candidates)
    span.set_attribute("top_score", result[0].score)

Span автоматически становится child входящего tool-call span.

Дебаг в проде

Самый полезный запрос: фильтр Loki {plugin="your-name", tenant_id="..."} и tail пока вы воспроизводите. JSON-логи = можно pivot по любому атрибуту.

Flow на «у тенанта X медленно»:

Grafana → dashboard "Plugin Overview" → фильтр tenant=X.
Найти медленное перцентиль-окно → кликнуть sample span → открыть в Tempo.
В Tempo → кнопка "Profiles" → смотрим CPU flame graph на то же окно.
Cross-check панель llm_cost_usd — если там спайк, боттлнек в вызове модели, не в вашем коде.

Плагины не задают собственных Prometheus-алертов. Если нужен бизнес-алерт (например «качество рекомендаций упало») — эмитьте метрику и запросите dashboard/алерт через platform team, мы добавим его в custom-alerts.yaml monitoring-репо.

Это всё — вы готовы к production.

Observability