USDT / eBPF probes

AngaraBase embeds USDT probes (User Statically-Defined Tracing) — instrumentation points for eBPF tools (bpftrace, bcc, perf).

Zero overhead until a tracer attaches: they are NOP instructions in the binary.
No restart: the tracer attaches to a running process.
Provider is angarabase; probes are compiled with the usdt feature (on by default). A --no-default-features build excludes them.

Checking probes are present

# probes embedded?
readelf -n ./angarabase-server | grep -A5 stapsdt

# list available probes
bpftrace -l 'usdt:./angarabase-server:angarabase:*'

Every probe carries a tag — a u64 (xxh64) hash of a query label. Default is 0 (untagged traffic; operator_* probes do not fire for it at all). The tag lets you filter to just the queries you care about.

-- per session:
SET query_tag = 'demo-heavy-report';
RESET query_tag;

-- per query (comment hint):
/*+ angarabase:tag=demo-heavy-report */ SELECT * FROM orders;

In bpftrace, a /* tag */ != 0 predicate keeps only tagged traffic.

Core probe signatures

bpftrace arguments are arg0, arg1, … in the order below.

Probe	Arguments
`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 only)
`operator_end`	`session_id`, `tag`, `operator_type u8`, `rows_out`, `duration_us` (tag≠0 only)

Enums (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

Beyond these there are extended probe groups (same provider): net_stall_*, sched_wait_*, parallel_*, vector_batch_* / vector_fallback, io_uring_*, optimizer_plan_*, qos_enqueue / qos_reject, write_phase_b_*, fsync_timeout. List them all with the bpftrace -l command above.

bpftrace examples

Query latency

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); }'

Per-phase timing

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); }'

Lock contention

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); }'

Tagged traffic only (by tag)

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); }'

Security

Attaching eBPF needs privileges: sudo setcap cap_bpf+ep /usr/bin/bpftrace or run as root.
Probes can reveal query behavior; restrict bpftrace access to a dedicated group.

If there are no probes

The binary was built with --no-default-features (probes excluded) — rebuild with default features.
Wrong binary path in usdt:<path>:angarabase:*.
Missing BPF privileges (see above) or an incompatible kernel.

AngaraBook