Основные понятия

В этом разделе описаны ключевые концепции, необходимые для работы с Monium Traces: модель данных, подходы к инструментации и семплирование.

Модель данныхМодель данных

ТрейсТрейс

Трейс — совокупность связанных спанов, представляющих полный путь выполнения конкретного запроса в системе. Трейс позволяет увидеть:

• последовательность операций и порядок их выполнения;
• временные затраты на каждый этап;
• взаимодействие между сервисами и компонентами;
• точки возникновения ошибок и задержек.

СпанСпан

Спан — базовый элемент распределенной трассировки, отдельная операция в вашей системе. Например, HTTP-запрос, вызов базы данных или выполнение функции.

Каждый спан содержит:

• Название — краткое описание операции. Используйте имена с низкой кардинальностью: не включайте в название уникальные идентификаторы. Например, GET /api/orders — хорошее имя, GET /api/orders/a3f82c1 — плохое.

• Статус — результат операции. В OpenTelemetry определены три значения:

  • UNSET — статус не задан явно.
  • OK — операция завершилась успешно.
  • ERROR — при выполнении произошла ошибка.

• Временные метки — время начала и окончания операции. Наличие длительности отличает спан от лога: спан описывает процесс, лог — мгновенное событие.

• Атрибуты — пары «ключ — значение» с метаданными операции. Атрибуты добавляют контекст для анализа и используются для поиска (например, http.status_code, db.system, order_id).

• События (Span Events) — структурированные записи внутри спана, которые фиксируют важные моменты операции. Каждое событие содержит временную метку, название и набор атрибутов. Типичное применение — запись информации об ошибках (exception.message, exception.stacktrace).

  Важно

  События не индексируются и недоступны для поиска. Если вам нужен поиск по этим данным, отправляйте их в логи.

• Ссылки (Span Links) — связи между спанами, в том числе из разных трейсов. Ссылки используются для представления асинхронных взаимодействий и пакетных операций. Например, когда консьюмер обрабатывает батч сообщений из очереди, каждое из которых было отправлено отдельным продюсером.

Организация данныхОрганизация данных

Данные трассировки в Monium Traces организованы по трем уровням, которые совпадают с проектной моделью Monium:

Сущность	Описание	Пример
Проект (Project)	Логическое объединение сервисов, квот и прав доступа.	Каталог в Yandex Cloud
Кластер (Cluster)	Окружение, в котором запущено приложение.	production, staging, testing
Сервис (Service)	Конкретное приложение или компонент, отправляющий трейсы.	api-gateway, billing-service, postgres

Значения проекта, кластера и сервиса указываются при настройке отправки данных.

ИнструментацияИнструментация

Инструментация — процесс добавления в код приложения механизмов для создания и отправки спанов. Без инструментации система остается «черным ящиком»: вы видите входные и выходные данные, но не можете проследить, что происходит внутри.

Monium Traces принимает данные по протоколу OpenTelemetry. Для отправки телеметрии используйте OpenTelemetry SDK или совместимые библиотеки — Monium Traces обеспечит обработку, хранение и визуализацию.

Существует два подхода к инструментации: автоматическая и ручная. Они решают разные задачи и на практике дополняют друг друга.

Автоматическая инструментацияАвтоматическая инструментация

При автоматической инструментации спаны создаются без изменения бизнес-логики приложения. Библиотеки и агенты OpenTelemetry перехватывают вызовы стандартных фреймворков и протоколов (HTTP, gRPC, клиенты БД) и самостоятельно формируют спаны с необходимыми атрибутами.

Характеристики:

• Быстрое внедрение — достаточно подключить агент или библиотеку.
• Автоматическое отслеживание HTTP-запросов, вызовов БД, gRPC, внешних API.
• Ограниченная гибкость: трассируются только поддерживаемые библиотеки и фреймворки.

Ручная инструментацияРучная инструментация

При ручной инструментации разработчик самостоятельно создает спаны в коде приложения через OpenTelemetry SDK. Этот подход позволяет трассировать операции, которые не покрываются автоматической инструментацией: внутреннюю бизнес-логику, кастомные обработчики, взаимодействие с нестандартными компонентами.

Характеристики:

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

Сочетание подходовСочетание подходов

На практике автоматическая и ручная инструментация дополняют друг друга:

1. Начните с автоматической инструментации — она покроет типовые протоколы (HTTP, gRPC) и стандартные компоненты (БД, кэши, очереди сообщений).
2. Анализируйте получившиеся трейсы — часто этого достаточно для диагностики.
3. Добавляйте ручную инструментацию в местах, где не хватает контекста: ключевые участки бизнес-логики, внутренние вызовы, обработка ошибок.

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

При трассировке всех запросов объем данных может быстро вырасти. Для успешных запросов, которые составляют большинство, полная трассировка, как правило, не нужна. Семплирование позволяет ограничить объем отправляемых данных, снижая стоимость обработки и хранения.

Head samplingHead sampling

Monium Traces поддерживает семплирование на стороне клиента (head sampling). Решение о том, сохранять ли трейс, принимается в момент создания корневого спана и распространяется на все дочерние спаны через контекст. Это гарантирует, что семплированный трейс всегда будет полным — без пропущенных спанов.

Основное ограничение head sampling — невозможно принять решение на основе данных всего трейса. Например, нельзя гарантировать сохранение всех трейсов с ошибками.

Для настройки head sampling в OpenTelemetry SDK доступны несколько встроенных семплеров — от полного сохранения всех трейсов до процентного отбора. Подробнее см. в документации OpenTelemetry.