Instrumentation: Управление сэмплированием трейсов в Proto Observability Platform

Mon, 01 Jan 0001 00:00:00 +0000

На этой странице:

Что такое сэмплирование
Область применения
Приоритет сэмплирования и заголовок x-protoobp-sampling-priority
Три уровня, где принимается решение о сборе
Параметры сэмплирования и значения по умолчанию
Настройка полного сбора
Правила сэмплирования по сервисам и операциям
Принудительное сохранение и отбрасывание в коде (force keep / drop)
Сэмплирование отдельных спанов
Частые причины потери спанов
Влияние перехода на полный сбор
Как проверить фактические настройки

Что такое сэмплирование

Сэмплирование — это механизм выборочного сбора трейсов. Чтобы снизить накладные расходы на инструментируемое приложение, сеть и хранилище, трейсер сохраняет и отправляет в агента не все трейсы, а заданную их долю. Остальные трейсы отбрасываются целиком.

Proto Observability Platform использует head-based sampling: решение о сохранении или отбрасывании трейса принимается один раз, в самом начале трейса (на корневом спане), и затем распространяется по всей цепочке вызовов. Благодаря этому трейс не «разрывается» — сохраняются либо все спаны трейса, либо ни одного.

Обратите внимание

Сэмплирование выполняется на стороне источника — трейсером приложения, трейсером Nginx или агентом. Платформа приёма полученные трейсы не сэмплирует. Поэтому если часть трейсов приходит неполной или не приходит вовсе, настройки нужно искать в конфигурации трейсеров и агента.

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

Правила и параметры, описанные на этой странице, действуют для трейсеров ProtoOBP и Datadog — они используют совместимую модель сэмплирования (head-based sampling, заголовок приоритета *-sampling-priority, параметры sample_rate / rate_limit / sampling_rules). Это относится ко всем поддерживаемым языкам и средам: Go, Java, Python, Node.js, PHP, Ruby, .NET и Nginx.

Имена переменных различаются только префиксом семейства:

ProtoOBP-трейсеры — переменные окружения POBP_*, system properties -Dpobp.* (для JVM), директива Nginx protoobp_sample_rate.
Datadog-трейсеры — переменные окружения DD_*, system properties -Ddd.* (для JVM), директива Nginx datadog_sample_rate.

OpenTelemetry и New Relic — другие конвенции

Для трейсеров OpenTelemetry сэмплирование настраивается иначе — через сэмплер OTEL (OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG, а в коллекторе — otel-sampler / otel-sampler-ratio), см. страницу OpenTelemetry. Трейсер New Relic использует собственную (адаптивную) выборку, настраиваемую в его конфигурации. Параметры POBP_* / DD_* и заголовок x-protoobp-sampling-priority на них не распространяются.

Приоритет сэмплирования и заголовок `x-protoobp-sampling-priority`

Решение о сохранении трейса передаётся между сервисами в служебном HTTP-заголовке распространения контекста x-protoobp-sampling-priority. Это не пользовательская настройка и не серверный параметр — значение проставляет трейсер, а нижестоящие сервисы наследуют его, чтобы принять то же решение для своей части трейса.

Заголовки семейств не взаимозаменяемы

ProtoOBP-трейсеры используют заголовок x-protoobp-sampling-priority, Datadog-трейсеры — x-datadog-sampling-priority. Платформа приёма понимает оба, но в пределах одной цепочки трейсеры должны использовать один формат распространения: ProtoOBP-модуль не читает x-datadog-*, и наоборот. Если сервис ProtoOBP-семейства и сервис Datadog-семейства идут в одной цепочке, между ними произойдёт разрыв контекста, если формат распространения не согласован явно. Внутри однородного парка (только ProtoOBP или только Datadog) распространение работает без дополнительной настройки.

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

Значение	Смысл	Кто ставит
`1` (AUTO_KEEP)	трейс сохранить, все спаны собираются	трейсер по авто-рейту
`0` (AUTO_REJECT)	трейс отбросить, спаны не отправляются	трейсер по авто-рейту
`2` (USER_KEEP)	принудительно сохранить (сработало правило/`sample_rate`)	пользовательское правило
`-1` (USER_REJECT)	принудительно отбросить	пользовательское правило

Значения 0 и 1 — это автоматическое решение трейсера по рейтам от агента. Значения 2 и -1 появляются, когда сработало явное правило (sampling_rules или заданный sample_rate). Приоритет 2 (USER_KEEP) важен ещё и тем, что такой трейс не отбрасывается агентом (см. уровень агента).

Три уровня, где принимается решение о сборе

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

Уровень	Где работает	Что делает
1. Трейсер приложения (Go, Java, Python, Node.js, PHP, Ruby, .NET)	внутри вашего сервиса	принимает решение keep/drop, ставит приоритет `0`/`1`, ограничивает частоту по своему лимиту
2. Трейсер Nginx	в Nginx	то же для входного трафика; настраивается директивой
3. Агент	protoobp-agent	вторичный сэмплер: рассчитывает целевой темп сбора и может дополнительно отбрасывать авто-трейсы

Решение принимается в «голове» трейса

При head-based sampling решение о сохранении трейса принимает первый сервис в трейсе («голова» — тот, кто получил запрос без входящего контекста). Оно проставляется в заголовок x-protoobp-sampling-priority и распространяется вниз по цепочке. Нижестоящие сервисы уважают это решение и не пересматривают его своим sample_rate — они продолжают трейс с тем же приоритетом. Поэтому для полного сбора достаточно настроить сбор на точке входа трейса, а не на каждом сервисе по отдельности.

Уровни 1 и 2 в таблице — это разные роли одного и того же трейсера: он выступает «головой» (принимает решение), если начинает трейс, и «продолжателем» (наследует решение), если получил контекст от вышестоящего сервиса.

Параметры сэмплирования и значения по умолчанию

JVM-трейсеры (Java) дополнительно принимают те же параметры в форме system property (-Dpobp.* / -Ddd.*), которая имеет приоритет над переменной окружения. Nginx настраивается директивой в конфигурационном файле.

Назначение	Переменная (env / JVM)	По умолчанию	Для 100% сбора
Заголовок контекста	`x-protoobp-sampling-priority`	проставляет трейсер	—
Глобальная доля сбора	`POBP_TRACE_SAMPLE_RATE` JVM: `-Dpobp.trace.sample.rate`	не задано → авто-сэмплирование агентом	`1.0`
Правила по сервису/операции	`POBP_TRACE_SAMPLING_RULES` JVM: `-Dpobp.trace.sampling.rules`	не задано (правил нет)	JSON, `sample_rate: 1.0`
Формат шаблонов в правилах	`POBP_TRACE_SAMPLING_RULES_FORMAT`	`regex`	—
Лимит частоты трейсера	`POBP_TRACE_RATE_LIMIT` JVM: `-Dpobp.trace.rate.limit`	`100` трейсов/сек (Nginx — `200`)	поднять
Директива сбора (Nginx)	`protoobp_sample_rate`	не задано → делегируется агенту	`protoobp_sample_rate 1.0;`
Отправка трейсов агенту	`POBP_TRACE_ENABLED` JVM: `-Dpobp.trace.enabled`	`true`	не `false`

Назначение	Переменная (env / JVM)	По умолчанию	Для 100% сбора
Заголовок контекста	`x-datadog-sampling-priority`	проставляет трейсер	—
Глобальная доля сбора	`DD_TRACE_SAMPLE_RATE` JVM: `-Ddd.trace.sample.rate`	не задано → авто-сэмплирование агентом	`1.0`
Правила по сервису/операции	`DD_TRACE_SAMPLING_RULES` JVM: `-Ddd.trace.sampling.rules`	не задано (правил нет)	JSON, `sample_rate: 1.0`
Формат шаблонов в правилах	`DD_TRACE_SAMPLING_RULES_FORMAT`	`regex`	—
Лимит частоты трейсера	`DD_TRACE_RATE_LIMIT` JVM: `-Ddd.trace.rate.limit`	`100` трейсов/сек (Nginx — `200`)	поднять
Директива сбора (Nginx)	`datadog_sample_rate`	не задано → делегируется агенту	`datadog_sample_rate 1.0;`
Отправка трейсов агенту	`DD_TRACE_ENABLED` JVM: `-Ddd.trace.enabled`	`true`	не `false`

Уровень агента (apm_config.target_traces_per_second, по умолчанию 10 трейсов/сек) настраивается в конфигурации агента и является общим для всех трейсеров в контуре — см. подраздел Агент.

Значение *_TRACE_SAMPLE_RATE — число от 0.0 до 1.0 включительно: 0.0 означает «трейсы не собираются», 1.0 — «собираются все трейсы», 0.6 — «собирается 60% трейсов». Значения вне диапазона отклоняются с предупреждением в логе (не применяются).

Значение лимита `0` запрещает всё, а не «снимает лимит»

*_TRACE_RATE_LIMIT = 0 (и target_traces_per_second: 0 у агента, начиная с 7.35) означает «не пропускать ни одного трейса», а не «без ограничения». Чтобы снять ограничение на пиках, поднимите значение выше пикового темпа трейсов (например, 100000), а не ставьте 0.

Настройка полного сбора

Ниже — как включить полный сбор (sample_rate = 1.0) по каждому типу трейсера. Напомним: решение принимается в «голове» трейса и распространяется вниз, поэтому в первую очередь настраивается сервис — точка входа (см. подраздел про бизнес-процессы о том, где именно применять эти настройки).

Приложение (все языки)

Переменные окружения одинаковы для всех языковых трейсеров (Go, Java, Python, Node.js, PHP, Ruby, .NET) — различается только префикс семейства.

Через переменные окружения:

POBP_TRACE_SAMPLE_RATE=1.0
POBP_TRACE_RATE_LIMIT=100000 # поднять лимит выше пикового темпа (0 запрещает всё!)

Для JVM-трейсеров (Java) — как system properties при запуске:

java -javaagent:/path/pobp-java-agent.jar \
 -Dpobp.trace.sample.rate=1.0 \
 -Dpobp.trace.rate.limit=100000 \
 -Dpobp.service=billing-bp \
 -jar app.jar

Через переменные окружения:

DD_TRACE_SAMPLE_RATE=1.0
DD_TRACE_RATE_LIMIT=100000 # поднять лимит выше пикового темпа (0 запрещает всё!)

Для JVM-трейсеров (Java) — как system properties при запуске:

java -javaagent:/path/dd-java-agent.jar \
 -Ddd.trace.sample.rate=1.0 \
 -Ddd.trace.rate.limit=100000 \
 -Ddd.service=billing-bp \
 -jar app.jar

Nginx

Директива наследуется по контекстам http → server → location; директива в более вложенном контексте имеет приоритет. Это позволяет включить полный сбор только на маршрутах БП:

http {
 protoobp_sample_rate 1.0; # база
 server {
 location /business-process/ {
 protoobp_sample_rate 1.0; # гарантированно 100% на маршруте БП
 }
 }
}

http {
 datadog_sample_rate 1.0; # база
 server {
 location /business-process/ {
 datadog_sample_rate 1.0; # гарантированно 100% на маршруте БП
 }
 }
}

Агент

У агента есть собственный сэмплер с целевым темпом apm_config.target_traces_per_second (по умолчанию 10 трейсов/сек). Он применяется к авто-трейсам (приоритет 0/1); трейсы, помеченные трейсером как USER_KEEP (2) через правила или заданный sample_rate, агент не дорезает — это ещё один довод использовать правила сэмплирования для критичных БП.

Параметр задаётся в конфигурационном файле агента protoobp.yaml:

apm_config:
 target_traces_per_second: 100

либо переменной окружения POBP_APM_TARGET_TPS.

Об именах и значениях у агента

Устаревший синоним apm_config.max_traces_per_second (env POBP_APM_MAX_TPS) ещё работает, но рекомендуется target_traces_per_second.
target_traces_per_second: 0 не отключает лимит, а (начиная с 7.35) прекращает отправку трейсов в приёмник. Чтобы снять ограничение — поднимите значение.
Ошибочные трейсы удерживаются отдельным error-сэмплером (apm_config.errors_per_second, по умолчанию 10 трейсов/сек) независимо от основного лимита.
Редкие трейсы — отдельный rare-сэмплер (apm_config.enable_rare_sampler, по умолчанию выключен; при включении удерживает редкие комбинации сервис/операция/ресурс, до 5 трейсов/сек).
Error- и rare-сэмплеры игнорируются для сервисов, у которых заданы правила сэмплирования (*_TRACE_SAMPLING_RULES), и по умолчанию не удерживают спаны, отброшенные через manual.drop.

Полнота сбора для бизнес-процессов

Чтобы трейсы, необходимые для мониторинга бизнес-процесса (БП), всегда содержали полный набор спанов, воспользуйтесь свойством head-based sampling: решение принимается в «голове» трейса и распространяется вниз.

Определите точку входа БП — сервис (или Nginx-маршрут), с которого начинается трейс бизнес-процесса. Именно он выступает «головой» и принимает решение о сборе.
Включите полный сбор на точке входа — sample_rate = 1.0 глобально либо адресным правилом (см. Правила сэмплирования). Нижестоящие сервисы унаследуют решение автоматически — настраивать каждый из них не требуется.
Поднимите лимит частоты (*_TRACE_RATE_LIMIT) на точке входа выше пикового темпа — иначе на пиках нагрузки трейсы БП будут отброшены даже при sample_rate = 1.0. Не ставьте 0 — это запретит все трейсы.
Проверьте лимит агента (apm_config.target_traces_per_second) — при высоком темпе БП его тоже нужно поднять.

Когда нужно настраивать не только точку входа

Наследование решения работает, только пока контекст трейса непрерывно передаётся по цепочке. Полный сбор нужно обеспечить дополнительно, если:

в цепочке есть неинструментированный сервис или прокси, срезающий заголовок x-protoobp-sampling-priority (x-datadog-sampling-priority), либо участок с protoobp_disable — за таким разрывом следующий сервис становится новой «головой» и принимает решение заново (может отбросить трейс);
сервис БП является самостоятельной точкой входа — вызывается не только в рамках этого БП, но и напрямую; тогда для него задаётся собственное правило.

В этих случаях включите полный сбор (или адресное правило) на соответствующих сервисах, а обрыв инструментирования — устраните.

Рекомендуемый способ — адресные правила сэмплирования для точки входа БП, а не глобальный sample_rate = 1.0 по всему ландшафту.

Правила сэмплирования по сервисам и операциям

Рекомендуемый подход — не включать полный сбор глобально по всему ландшафту, а адресно для сервисов БП. Для этого служит переменная с JSON-массивом правил (формат правил одинаков для обоих семейств):

POBP_TRACE_SAMPLING_RULES (JVM: -Dpobp.trace.sampling.rules).

DD_TRACE_SAMPLING_RULES (JVM: -Ddd.trace.sampling.rules).

[
 { "service": "billing-bp", "name": "http.request", "resource": "POST /pay", "sample_rate": 1.0 },
 { "service": "orders-bp", "resource": "POST /orders", "sample_rate": 1.0 },
 { "sample_rate": 0.1 }
]

Поля правила:

Поле	Обязательное	Назначение
`sample_rate`	да	Доля сбора `0.0`–`1.0` для трейсов, попавших под правило. `1.0` = все.
`service`	нет	Имя сервиса (шаблон, см. ниже). Нет поля → любой сервис.
`name`	нет	Имя операции спана (шаблон).
`resource`	нет	Ресурс/эндпоинт (например, `POST /orders`) — самая точная адресация под маршрут БП.
`tags`	нет	Словарь `{"тег":"значение"}`; правило срабатывает при совпадении тегов корневого спана.

Формат шаблонов: по умолчанию regex

Поля service, name, resource сопоставляются как регулярные выражения (по всей строке, без учёта регистра) — это формат по умолчанию. Специальные символы regex (., *, ?, + и т.д.) трактуются соответственно: например, orders-.* — «orders- и любой суффикс». Формат можно переключить на glob (* — любая подстрока, ? — один символ) переменной POBP_TRACE_SAMPLING_RULES_FORMAT=glob (для Datadog — DD_TRACE_SAMPLING_RULES_FORMAT=glob). Для точечной адресации сервиса БП надёжнее указывать точное имя (как в примерах) — оно корректно работает в обоих форматах.

Ключевые нюансы применения:

Порядок важен: побеждает первое совпавшее правило (сверху вниз). Специфичные правила БП размещайте вверху, общее правило с низким рейтом — в конце.
Правило применяется к корню трейса (root span); принятое решение затем распространяется на все нижестоящие спаны.
sample_rate в правиле переопределяет глобальный *_TRACE_SAMPLE_RATE.
Правила не отменяют лимит частоты. Даже при sample_rate: 1.0 трейсы сверх *_TRACE_RATE_LIMIT получат 0. Для БП с высоким RPS лимит нужно поднять отдельно.
Пустое правило {"sample_rate": 1.0} без фильтров ловит всё — держите его последним.

Пример: сервисы БП собираются на 100%, остальной трафик — на 10%.

POBP_TRACE_SAMPLING_RULES='[{"service":"billing-bp","sample_rate":1.0},{"service":"orders-bp","resource":"POST /orders","sample_rate":1.0},{"sample_rate":0.1}]'
POBP_TRACE_RATE_LIMIT=100000

DD_TRACE_SAMPLING_RULES='[{"service":"billing-bp","sample_rate":1.0},{"service":"orders-bp","resource":"POST /orders","sample_rate":1.0},{"sample_rate":0.1}]'
DD_TRACE_RATE_LIMIT=100000

Принудительное сохранение и отбрасывание в коде (force keep / drop)

Помимо доли и правил, отдельный трейс можно принудительно сохранить или отбросить прямо в коде приложения — это удобно для критичных транзакций (всегда сохранять) и для шумных служебных вызовов вроде health-check (всегда отбрасывать).

Force keep — пометьте спан тегом manual.keep: этот спан и все дочерние будут собраны. Трейс получает приоритет 2 (USER_KEEP) и не отбрасывается ни лимитом трейсера, ни агентом.
Force drop — тег manual.drop: ни один дочерний спан не собирается; error- и rare-сэмплеры агента при этом игнорируются.

// .NET: всегда сохранять трейс критичной операции
using Protoobp.Trace;

using (var scope = Tracer.Instance.StartActive("checkout"))
{
 scope.Span.SetTag(Protoobp.Trace.Tags.ManualKeep, "true");
 // логика операции
}

В других языках — эквивалентный тег manual.keep / manual.drop (например, в Java — константа MANUAL_KEEP из API трейсера).

// .NET: всегда сохранять трейс критичной операции
using Datadog.Trace;

using (var scope = Tracer.Instance.StartActive("checkout"))
{
 scope.Span.SetTag(Datadog.Trace.Tags.ManualKeep, "true");
 // логика операции
}

В других языках — эквивалентный тег manual.keep / manual.drop (например, в Java — константа DDTags.MANUAL_KEEP).

Ставьте `manual.keep` до распространения контекста

Помечайте спан на входе трейса (корневом спане), до того как контекст ушёл к нижестоящим сервисам. Если пометить позже, трейс может не сохраниться целиком по всей цепочке. Для бизнес-процессов это самый надёжный способ гарантировать полный сбор: manual.keep на входной операции БП собирает трейс целиком, минуя лимиты трейсера и агента.

Сэмплирование отдельных спанов

Если нужен не весь трейс, а конкретный спан (например, для метрик, построенных на спанах), задайте POBP_SPAN_SAMPLING_RULES (у Datadog-трейсеров — DD_SPAN_SAMPLING_RULES). Такие правила сохраняют отдельные спаны, даже когда трейс отброшен head-based-сэмплированием. Обратное невозможно: этими правилами нельзя отбросить спан, уже сохранённый head-based-решением.

Поля правила: service, name, sample_rate, max_per_second (ограничение спанов в секунду для правила).

POBP_SPAN_SAMPLING_RULES='[{"service":"my-service","name":"http.request","sample_rate":1.0,"max_per_second":50}]'

Частые причины потери спанов

Даже при намерении собирать «100%» спаны могут теряться по следующим причинам:

*_TRACE_SAMPLE_RATE меньше 1.0 — собирается лишь часть трейсов; остальные получают приоритет 0. По умолчанию значение не задано, и трейсер использует авто-сэмплирование по рейтам от агента.
Лимит частоты трейсера *_TRACE_RATE_LIMIT — по умолчанию 100 трейсов/сек на инстанс сервиса (у Nginx-трейсера — 200). При пиках нагрузки трейсы сверх лимита получают 0 даже при sample_rate = 1.0. Это самая частая причина «пропадающих» спанов. Лимит применяется к трейсам, оставленным правилом или глобальным sample_rate (не к трейсам, оставленным по рейтам агента).
Лимит агента target_traces_per_second — по умолчанию 10 трейсов/сек; авто-трейсы без явного правила keep подпадают под этот лимит.
Значение лимита выставлено в 0 — это запрещает все трейсы (частая ошибка при попытке «снять лимит»).

(Здесь *_ — префикс семейства трейсера: POBP_ для ProtoOBP, DD_ для Datadog.)

Влияние перехода на полный сбор

На инструментируемый сервис:

Рост накладных расходов трейсера: CPU и память на формирование и буферизацию спанов, сетевой трафик до агента. Обычно умеренный, но заметен на высоконагруженных сервисах.
Снятие лимита частоты убирает защиту от всплесков — при резком росте RPS нагрузка на трейсер и агент растёт линейно.

На Proto Observability Platform:

Кратно возрастает объём принимаемых и хранимых спанов → рост нагрузки на конвейер приёма и на дисковое хранилище.
При неизменном сроке хранения (retention) объём данных на диске растёт пропорционально — может потребоваться расширение ёмкости хранилища. При недостатке ресурсов возможен рост задержки индексации.

Как проверить фактические настройки

Трейсеры приложений (Go, Java, Python, Node.js, PHP, Ruby, .NET) при старте печатают свою конфигурацию в лог — поля sample_rate, sampling_rules, rate_limit показывают фактические действующие значения (одинаково для семейств ProtoOBP и Datadog).
Агент — секция apm_config в конфигурационном файле protoobp.yaml.

Документация Proto Observability Platform – sampling priority

Instrumentation: Управление сэмплированием трейсов в Proto Observability Platform

Что такое сэмплирование

Обратите внимание

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

OpenTelemetry и New Relic — другие конвенции

Приоритет сэмплирования и заголовок `x-protoobp-sampling-priority`

Заголовки семейств не взаимозаменяемы

Три уровня, где принимается решение о сборе

Решение принимается в «голове» трейса

Параметры сэмплирования и значения по умолчанию

Значение лимита `0` запрещает всё, а не «снимает лимит»

Настройка полного сбора

Приложение (все языки)

Nginx

Агент

Об именах и значениях у агента

Полнота сбора для бизнес-процессов

Когда нужно настраивать не только точку входа

Правила сэмплирования по сервисам и операциям

Формат шаблонов: по умолчанию regex

Принудительное сохранение и отбрасывание в коде (force keep / drop)

Ставьте `manual.keep` до распространения контекста

Сэмплирование отдельных спанов

Частые причины потери спанов

Влияние перехода на полный сбор

Рекомендация

Как проверить фактические настройки

Документация Proto Observability Platform – sampling priority

Instrumentation: Управление сэмплированием трейсов в Proto Observability Platform

Что такое сэмплирование

Обратите внимание

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

OpenTelemetry и New Relic — другие конвенции

Приоритет сэмплирования и заголовок x-protoobp-sampling-priority

Заголовки семейств не взаимозаменяемы

Три уровня, где принимается решение о сборе

Решение принимается в «голове» трейса

Параметры сэмплирования и значения по умолчанию

Значение лимита `0` запрещает всё, а не «снимает лимит»

Настройка полного сбора

Приложение (все языки)

Nginx

Агент

Об именах и значениях у агента

Полнота сбора для бизнес-процессов

Когда нужно настраивать не только точку входа

Правила сэмплирования по сервисам и операциям

Формат шаблонов: по умолчанию regex

Принудительное сохранение и отбрасывание в коде (force keep / drop)

Ставьте `manual.keep` до распространения контекста

Сэмплирование отдельных спанов

Частые причины потери спанов

Влияние перехода на полный сбор

Рекомендация

Как проверить фактические настройки

Приоритет сэмплирования и заголовок `x-protoobp-sampling-priority`