Tracing

AngaraBase uses tracing. There are two levels of observability:

1. Server logs — verbosity is set by RUST_LOG (see Logging).
2. Query traces (OTel spans) — an optional per-query export of the accept → parse → plan → execute → storage → commit spans.

Export goes only to stderr (via the log) or to a local JSONL file. There is no network OTLP collector, no Jaeger/Tempo, no HTTP push.

Enabling query traces

Per-query traces are off by default. They are controlled by environment variables:

# 5% of queries to a local JSONL file
export ANGARABASE_OTEL_ENABLED=1
export ANGARABASE_OTEL_SAMPLE_RATE_PPM=50000
export ANGARABASE_OTEL_EXPORTER=file
export ANGARABASE_OTEL_ENDPOINT=/var/log/angarabase/query-traces.jsonl
./angarabase-server --config-path /etc/angarabase/angarabase.conf

With EXPORTER=stderr, span lines go to the regular server log (at info).

What a span carries

Each query trace carries identifiers you can use to correlate it with sys.* diagnostics:

• logical database and user;
• query class (QueryClass);
• queryid and planid (when available) — the same identifiers as in angara_stat_statements and EXPLAIN.

Reading the JSONL

# slow queries (>1s) from the trace file
jq 'select(.duration_ms > 1000)' /var/log/angarabase/query-traces.jsonl

# distribution by queryid
jq -r '.queryid' /var/log/angarabase/query-traces.jsonl | sort | uniq -c | sort -rn | head

For aggregate metrics (latency percentiles, slow-query rate) use the Prometheus endpoint — see Monitoring; for plan-level analysis see Diagnostics.

Security

⚠️ Spans and logs can contain SQL text with sensitive data.

• Restrict access to the trace file: chmod 640, owned by the service user.
• Configure rotation (see logrotate in Logging).
• Avoid 100% sampling with SQL text in production unless necessary — it is both volume and a leakage risk.

If there are no traces

• ANGARABASE_OTEL_ENABLED is not set to 1/true — spans are not written.
• ANGARABASE_OTEL_SAMPLE_RATE_PPM=0 — sampling is off.
• EXPORTER=file but ANGARABASE_OTEL_ENDPOINT is unset or the path is not writable — the line goes to the stderr log instead of the file.
• Too restrictive a RUST_LOG for the stderr exporter — raise the level (see Logging).

See also

• Logging — RUST_LOG, line format, rotation, aggregation.
• Monitoring — Prometheus metrics.
• Diagnostics — EXPLAIN, angara_stat_*, the slow log.