Трейсы приложений

Платформа принимает распределённые трейсы ваших приложений по протоколу OpenTelemetry (OTLP). Трейс показывает путь запроса по сервисам и где именно теряется время — в БД, во внешнем API или в коде.

Куда отправлять

Приём — по OTLP/HTTP (protobuf) на домене приёма данных:

https://ingest.voltir.tech/traces/v1/traces

Авторизация — агентским токеном вашего пространства в заголовке Authorization:

Authorization: Bearer <токен>

Токен — тот же, которым авторизуются агенты мониторинга. На любом сервере с установленным агентом он записан в /etc/monitoring-agent/agent.env (переменная TOKEN). Отдельный токен для приложений может выпустить администратор платформы — напишите вашему менеджеру.

Пространство определяется платформой по токену: указывать идентификаторы аккаунта не нужно и невозможно — данные всегда попадают только в ваше изолированное хранилище. Поддерживается именно OTLP по HTTPS (порт 443); OTLP/gRPC не принимается.

Быстрое подключение (любой язык)

SDK OpenTelemetry читают стандартные переменные окружения — обычно достаточно задать четыре:

OTEL_SERVICE_NAME=my-app
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.voltir.tech/traces/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <токен>"

Дальше — автоинструментация вашего стека:

Python: pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http, запуск через opentelemetry-instrument python app.py (или opentelemetry-instrument gunicorn …);
Node.js: npm i @opentelemetry/auto-instrumentations-node, запуск с node --require @opentelemetry/auto-instrumentations-node/register app.js;
Java: java -javaagent:opentelemetry-javaagent.jar -jar app.jar;
.NET, Go, PHP и другие — любой SDK OpenTelemetry с экспортёром OTLP/HTTP.

Через OpenTelemetry Collector

Если приложений много или им нельзя давать токен напрямую, поставьте рядом collector: приложения шлют в него без авторизации по локальной сети, а он — в платформу:

exporters:
  otlphttp/voltir:
    traces_endpoint: https://ingest.voltir.tech/traces/v1/traces
    headers:
      Authorization: "Bearer <токен>"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/voltir]

Где смотреть

В вашей Grafana (вход из портала по кнопке, без второго пароля):

дашборд «Трейсы» — обзор сервисов, частота и длительность операций, переход в конкретный трейс;
Explore → источник «Traces» — поиск по сервису, операции, длительности и меткам.

Сервис появляется в списках в течение минуты после первых принятых спанов.

Сэмплирование

На нагруженных приложениях не отправляйте каждый запрос — доли трафика достаточно, чтобы видеть распределение задержек:

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

0.1 — трассируется каждый десятый запрос; ошибки и медленные запросы при таком сэмплировании всё равно попадаются регулярно. Health-пробы и служебные URL лучше исключить из инструментации совсем.

Если трейсы не появляются

Проверьте ответ приёмника: успешная отправка возвращает 200; 401 — неверный или отозванный токен.
Убедитесь, что выбран протокол http/protobuf, а не gRPC (частая причина «молчания» SDK).
Сервер приложения должен иметь доступ до ingest.voltir.tech:443.
Спаны уходят пачками раз в несколько секунд — при коротких скриптах завершайте провайдер явно (shutdown), иначе последняя пачка теряется.