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

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

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

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

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

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

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

Правила и параметры, описанные на этой странице, действуют для трейсеров 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.

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

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

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

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

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

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

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

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

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

• Трейсер:
• ProtoOBP
• Datadog

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

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

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

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

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

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

• Трейсер:
• ProtoOBP
• Datadog

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

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 запрещает всё!)

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; директива в более вложенном контексте имеет приоритет. Это позволяет включить полный сбор только на маршрутах БП:

• Трейсер:
• ProtoOBP
• Datadog

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.

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

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

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

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

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

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

• Трейсер:
• ProtoOBP
• Datadog

[
  { "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 }
]

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

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

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

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

• Трейсер:
• ProtoOBP
• Datadog

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-сэмплеры агента при этом игнорируются.

• Трейсер:
• ProtoOBP
• Datadog

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

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

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

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

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

Если нужен не весь трейс, а конкретный спан (например, для метрик, построенных на спанах), задайте 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%» спаны могут теряться по следующим причинам:

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