USDT / eBPF probes

AngaraBase встраивает USDT-пробы (User Statically-Defined Tracing) — точки инструментации для eBPF-инструментов (bpftrace, bcc, perf).

Zero-overhead, пока не подключён трейсер: в бинаре это NOP-инструкции.
Без рестарта: трейсер цепляется к работающему процессу.
Провайдер — angarabase; пробы компилируются с feature usdt (включён по умолчанию). Сборка --no-default-features их исключает.

Проверка наличия проб

# пробы встроены?
readelf -n ./angarabase-server | grep -A5 stapsdt

# список доступных проб
bpftrace -l 'usdt:./angarabase-server:angarabase:*'

Каждая проба несёт tag — u64-хеш (xxh64) метки запроса. По умолчанию 0 (нетегированный трафик; operator_*-пробы для него вообще не срабатывают). Тег позволяет фильтровать только интересующие запросы.

-- на сессию:
SET query_tag = 'demo-heavy-report';
RESET query_tag;

-- на отдельный запрос (hint в комментарии):
/*+ angarabase:tag=demo-heavy-report */ SELECT * FROM orders;

В bpftrace фильтр /* tag */ != 0 оставляет только тегированный трафик.

Сигнатуры основных проб

Аргументы в bpftrace — arg0, arg1, … в порядке ниже.

Проба	Аргументы
`query_start`	`session_id u64`, `query_fingerprint u64`, `tag u64`
`query_end`	`session_id`, `query_fingerprint`, `total_us`, `outcome u8`, `tag`, `rows`
`phase_start`	`session_id`, `phase u8`, `tag`
`phase_end`	`session_id`, `phase u8`, `duration_us`, `tag`
`lock_wait_start`	`session_id`, `lock_type u8`, `tag`, `resource_id`
`lock_wait_end`	`session_id`, `wait_us`, `tag`
`io_start`	`session_id`, `op_type u8`, `bytes u32`, `tag`, `table_id u32`
`io_end`	`session_id`, `latency_us`, `tag`
`operator_start`	`session_id`, `tag`, `operator_type u8`, `table_id u32` (только tag≠0)
`operator_end`	`session_id`, `tag`, `operator_type u8`, `rows_out`, `duration_us` (только tag≠0)

Энумы (append-only):

phase: 0=parse, 1=plan, 2=execute, 3=commit
outcome: 0=Ok, 1=Error, 2=Timeout, 3=Cancelled
lock_type: 0=Row, 1=Page, 2=Table, 3=Transaction
op_type (io): 0=PageRead, 1=PageWrite, 2=WalFlush, 3=Fsync

Помимо них есть расширенные группы проб (тот же провайдер): net_stall_*, sched_wait_*, parallel_*, vector_batch_* / vector_fallback, io_uring_*, optimizer_plan_*, qos_enqueue / qos_reject, write_phase_b_*, fsync_timeout. Полный список — командой bpftrace -l выше.

Примеры bpftrace

Латентность запросов

bpftrace -e '
usdt:./angarabase-server:angarabase:query_end {
  $duration_us = arg2;   // total_us
  $outcome     = arg3;   // 0 = Ok
  if ($outcome == 0) { @latency_us = hist($duration_us); }
  else { @failed++; }
}
interval:s:5 { print(@latency_us); printf("failed: %d\n", @failed); clear(@failed); }'

Тайминг по фазам

bpftrace -e '
usdt:./angarabase-server:angarabase:phase_end {
  $phase = arg1; $us = arg2;   // phase: 0=parse 1=plan 2=execute 3=commit
  @by_phase[$phase] = hist($us);
}
interval:s:10 { print(@by_phase); }'

Контеншн блокировок

bpftrace -e '
usdt:./angarabase-server:angarabase:lock_wait_end {
  $wait_us = arg1;
  @lock_wait = hist($wait_us);
  if ($wait_us > 1000) { printf("SLOW LOCK: session=%d wait=%dus\n", arg0, $wait_us); }
}
interval:s:5 { print(@lock_wait); }'

Только тегированный трафик (по тегу)

bpftrace -e '
usdt:./angarabase-server:angarabase:lock_wait_end /arg2 != 0/ { @lock_us_by_tag[arg2] = hist(arg1); }
usdt:./angarabase-server:angarabase:io_end        /arg2 != 0/ { @io_us_by_tag[arg2]   = hist(arg1); }'

Безопасность

Для подключения eBPF нужны привилегии: sudo setcap cap_bpf+ep /usr/bin/bpftrace или запуск от root.
Пробы могут раскрывать поведение запросов; ограничьте доступ к bpftrace отдельной группой.

Если проб нет

Бинарь собран с --no-default-features (пробы исключены) — пересоберите со стандартными feature.
Неверный путь к бинарю в usdt:<path>:angarabase:*.
Нет привилегий BPF (см. выше) или несовместимое ядро.

См. также

Tracing — OTel-спаны запросов в stderr/JSONL.
Мониторинг — метрики Prometheus.
Диагностика — EXPLAIN, angara_stat_*, медленный лог.

AngaraBook