[Документация Yandex Cloud](../../index.md) > [Monium](../index.md) > [Трейсы](index.md) > Основные понятия

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

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

## Модель данных {#data-model}

### Трейс {#trace}

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

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

### Спан {#span}

Спан — базовый элемент распределенной трассировки, отдельная операция в вашей системе. Например, 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`).

  {% note warning %}

  События не индексируются и недоступны для поиска. Если вам нужен поиск по этим данным, отправляйте их в [логи](operations/traces-logs.md).

  {% endnote %}

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

### Организация данных {#data-organization}

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

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

Значения проекта, кластера и сервиса указываются при [настройке отправки данных](../collector/index.md).

## Инструментация {#instrumentation}

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

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

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

### Автоматическая инструментация {#auto-instrumentation}

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

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

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

### Ручная инструментация {#manual-instrumentation}

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

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

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

### Сочетание подходов {#combining}

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

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

## Семплирование {#sampling}

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

### Head sampling {#head-sampling}

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

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

Для настройки head sampling в OpenTelemetry SDK доступны несколько встроенных семплеров — от полного сохранения всех трейсов до процентного отбора. Подробнее в [документации OpenTelemetry](https://opentelemetry.io/docs/concepts/sampling/).

{% note warning %}

Tail sampling (семплирование после полного сбора трейса) на данный момент не поддерживается.

{% endnote %}