/otel (bro)
All mechanics live in the bro CLI and @broject/otel. This skill
is policy only.
Prereq: bro on PATH or npx -y @broject/bro@0.
What it is
Every bro hooks <event> dispatch runs through the emitHook facade:
resolve the otel config section → apply the per-hook policy (on/off,
sample, collect allowlist) → build one record → write the
configured sink. Telemetry answers two operator questions at once:
which hooks are ACTIVE (counts + latency per event) and WHAT gets
collected (the allowlist is the whole contract — no payload field
leaves the machine unless named).
Off by default and free when off. enabled=false short-circuits
before any payload work: one memoized config read and a boolean per
hook. BRO_TELEMETRY=0 kills emission outright, same switch as the
command journal.
| Command | What it does |
|---|---|
bro otel status [--json] |
enabled? resolved exporter (file path / otlp endpoint), * + per-hook policies, event counts from the file sink |
bro otel test <hook> |
fire a synthetic payload through the facade — prints the exact exported record, the policy, and the payload fields the allowlist dropped |
bro otel on / bro otel off |
flip otel.enabled in bro.config.local.json — the local layer, never the committed config |
Enable
bro otel on # writes {"otel":{"enabled":true}} → bro.config.local.json
bro otel status # verify: exporter=file → <git-common>/bro/otel/hooks.jsonl
otel.enabled alone lights every hook at the meta-only level —
event name, session, client, duration, ok/error. Payload fields are
always explicit opt-in via collect.
Config reference
"otel": {
"enabled": false, // master switch
"exporter": {
"type": "file", // file | otlp | stdout
"path": "", // file sink; '' → <git-common>/bro/otel/hooks.jsonl
"endpoint": "", // otlp sink; '' → OTEL_EXPORTER_OTLP_* env / provider.env
"headers": {} // otlp only
},
"hooks": {
"*": true, // default policy: false | true | {sample, collect}
"post-tool": { "sample": 0.1, "collect": ["tool_name", "tool_response.success"] }
}
}
'*'is the default policy; a named hook entry overrides it;falsedrops the hook. Absent'*'reads astrue—enabledalone lights all hooks.'*': falseis the "enabled but silent" spelling.collectlists dotted payload paths (tool_input.command); scalar leaves land aspayload.<path>— objects, arrays, and missing paths drop silently.true(no object) means meta-only.sampleis the per-event keep probability0..1—0.1keeps ~10% of that hook's events.- Merge: local > project > global (standard layers).
otelis an operator section —bro doctorwarns if a repo commits it; usebro.config.local.*or~/.config/bro/config.json.
Trust model (why a repo cannot aim your telemetry). Arming
(enabled), the exporter (type/path/endpoint/headers), and every
collect allowlist are read from operator-owned layers only: the
global config plus any project/local config file git ls-files reports
untracked — the file bro otel on writes in a real checkout. A
committed otel block is repo-controlled, so the facade ignores it
for everything except narrowing: it can turn telemetry off, drop a
hook, or lower a sample, but never arm, redirect, or collect. A
committed bro.config.local.json is still committed — the git index,
not the filename, is the verdict. In a directory git doesn't know,
every file is unattributable and only the global layer can arm. bro otel status prints a note when a committed enabled=true is ignored —
that is the opt-in step, not a bug.
Hook catalog
| bro event | host events | payload fields worth collecting |
|---|---|---|
session-start |
SessionStart | session_id, hook_event_name |
post-compaction |
PostCompaction | session_id |
pre-compact |
PreCompact | session_id |
prompt-submit |
UserPromptSubmit | session_id, prompt ⚠ content |
pre-tool |
PreToolUse | tool_name, tool_use_id, tool_input.command, tool_input.file_path |
post-tool |
PostToolUse, PostToolUseFailure | tool_name, tool_input.command, tool_response.success |
stop |
Stop | session_id, stop_hook_active |
permission |
PermissionRequest | tool_name, tool_input.command |
prepare-commit-msg, reference-transaction, post-merge |
git hooks | — (meta rows only) |
Meta fields (session, client, ms, ok, error) ride every row
for free — the allowlist only governs payload.*.
Reading the sink
The default file sink is one JSONL row per event at
<git-common>/bro/otel/hooks.jsonl (locked append, 512KB tail cap):
bro otel status # counts per event
jq -r .event .git/bro/otel/hooks.jsonl | sort | uniq -c
jq 'select(.event=="hook.post-tool") | .ms' .git/bro/otel/hooks.jsonl
For a collector: exporter.type=otlp posts OTLP/HTTP-JSON log records
(bro.hook.<event> bodies, attributes flattened) via a detached
poster — a dead collector loses the row, never stalls the hook. Point
exporter.endpoint or rely on OTEL_EXPORTER_OTLP_ENDPOINT; Grafana
dashboards under observability/grafana/ read the same bro.* event
shape the lane.<provider>.* events already use.
exporter.type=stdout writes rows to stderr — hook stdout is the
host's control channel; live debugging only.
bro otel test session-start previews without writing: it prints the
record a real event would produce plus the payload fields not collected list — check allowlists before enabling.
Migration note
bro fleet telemetry (the perf journals) and lane.<provider>.* otel
events keep working — they are session evidence and lane telemetry,
not hook telemetry. The facade is the aggregation layer for hook
events: use bro otel to answer "which hooks fire, how fast, with
what"; fleet telemetry for probe-level latency inside a hook.