Heron Traffic Observatory
Reconstruct agent activity and LLM performance from network traffic without changing workload code.
- Source repo
- Netis/heron
- Stars
- ★ 104
- Last updated
- 1mo ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 68/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude APICodex · Claude Code (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An agent developer investigating stalled tool calls or plan loops can inspect the complete interaction in a turn timeline.
- Not a fit if
- Teams that can only install monitoring on clients and cannot provide plaintext traffic
- Teams that need cross-cluster client tracing
- Website
- heron-ai.pages.dev ↗ set on GitHub
- Maintenance
- Commits in the last 6 monthslast commit 2026-10-12latest release v0.8.3 (2026-10-12)
- Source review
- 68/100 · Some gaps
What does this agent do, and when should you use it?
Heron passively observes agents and LLM services through libpcap, PCAP replay, cloud-probe ZMQ input, or an experimental Linux eBPF SSL-uprobe source. Parallel workers parse HTTP/SSE, detect wire APIs, and extract semantics; a turn tracker assembles agent turns while a metrics aggregator computes performance data. DuckDB is the default embedded store, with ClickHouse available as an alternative, and a built-in REST API and embedded React console serve results at localhost:3000. Heron runs where traffic is already decrypted, or can use optional eBPF capture on Linux, outside the request path. The README also documents named profiles for Claude Code and OpenAI Codex CLI, alongside OpenAI, Anthropic, and Gemini API formats.
Heron reads traffic from a live interface, .pcap files, or a cloud-probe ZMQ stream; optionally, Linux eBPF SSL uprobes capture TLS traffic at process SSL_read/SSL_write boundaries. It dispatches packets by connection, parses HTTP/SSE, and detects wire formats including OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini AI Studio. Semantic extraction feeds a turn tracker that assembles agent turns and sessions; the system records TTFT, end-to-end latency, TPOT, throughput, error rate, and other metrics, while retaining structured requests/responses and raw bodies. Users inspect calls, turns, service topology, and performance through the REST API or the console at localhost:3000, and can export selected turns or sessions as OpenAI-style messages JSONL.
- An agent developer investigating stalled tool calls or plan loops can inspect the complete interaction in a turn timeline.
- An inference-platform team mapping traffic from LiteLLM to vLLM or SGLang backends can use the topology graph and per-hop metrics.
- An operations team comparing TTFT, latency, throughput, and error rates across model endpoints can aggregate metrics from real traffic.
- A compliance or security team needing request/response evidence by agent kind and session can inspect call details and raw HTTP.
- A model-training team reusing real agent runs can export selected turns or sessions as JSONL trajectories.
How do you install or deploy this agent?
Linux and macOS can use the user-local installer without sudo. Live interface capture on Linux requires CAP_NET_RAW. Optional Linux eBPF TLS capture is experimental and requires a build with the ebpf cargo feature, CAP_BPF, and kernel BTF. You can also start with PCAP replay, which requires no capture privileges.
How do you use this agent?
Install Heron, replay a PCAP, then open the local console. For live interface capture, use the -i option; that mode requires the relevant capture privileges.
What are this agent's strengths and limitations?
- The observer stays outside the request path, needs no agent or SDK changes, and cannot block observed calls if it fails.
- The turn tracker automatically joins planning, tool calls, and results into addressable agent turns.
- One parser covers OpenAI, Anthropic, Gemini, and OpenAI-compatible services, and turns can be exported as JSONL training trajectories.
- The default is single-file embedded DuckDB, with an optional ClickHouse backend and an embedded console.
- Ordinary packet capture reads plaintext HTTP only; deployment must be at a decrypted traffic boundary or receive a trusted traffic source.
- Linux eBPF TLS capture is explicitly experimental and requires CAP_BPF, kernel BTF, and the ebpf build feature.
- The README states that Heron does not provide cross-cluster client tracing.
- ClickHouse requires additional configuration for high-volume analytics, while the designed PostgreSQL backend is not yet wired.
How does this agent compare with similar options?
Compared with SDK instrumentation, Heron avoids per-client changes but depends on observable plaintext traffic. Compared with a reverse proxy, it stays out of the request path and does not require clients to repoint through a proxy. Compared with server-side OpenTelemetry, it reconstructs calls and turns from traffic without relying on server-emitted tags. The README also identifies cross-cluster client tracing as a capability it gives up.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Heron Traffic Observatory This agent | 68 · Some gaps | CLIFree | ★ 104 | 1mo ago | Rust | OpenAI API · Claude API |
| ClawMetry | 71 · Some gaps | CLIFreemium | ★ 439 | 1d ago | Python | Codex · Claude Code |
| Langtrace | 48 · Major gaps | Library / SDKFreemium | ★ 1.2k | 1y ago | TypeScript | OpenAI API · Claude API |
| AgentSight | 69 · Some gaps | CLIFree | ★ 801 | 1d ago | C | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Install documentation offers user-local installation and narrower file or systemd capabilities, and marks eBPF as optional. Live capture still requires elevated capabilities, and the API exposes a capture-source update that rewrites configuration and restarts the process; the packet does not show confirmation or authorization controls for that action, so full marks are not justified. The docs disclose plaintext capture and possible retention of full request/response bodies, pcaps, and telemetry, with retention settings and uninstall backup guidance; the sample does not show redaction or access-control policy. Installation pipes a downloaded script to a shell. Checksum guidance exists, but dependency pinning or auditing evidence is absent.
The README, installation guide, and configuration guide are largely consistent about replay keeping the service available, retention, and building the console feature. The API and capture source show explicit error mapping and feature gating. The packet describes CI, fault-injection, and migration tests, but these are repository claims and the supplied materials do not include the complete workflows, test implementations, or codebase, so they receive only partial credit.
The materials address agent developers, inference operations, finance, compliance, and model training, and describe multiple capture sources, storage choices, supported platforms, and requirements. Boundaries include the need for plaintext visibility, HTTP/1.x limits, experimental eBPF, and skipped unsupported export formats. However, some coverage claims appear only in the README, and the packet does not provide a complete guide for choosing triggers and deployment environments.
Documentation has clear entry points for architecture, configuration, installation, metrics, and changes; installation, privilege, verification, build, and uninstall instructions are detailed. The Apache-2.0 metadata is supported by the license file. The README mentions releases and a roadmap, but the sample omits the full changelog, release process, and named maintenance responsibility. Examples are useful, though FAQ coverage is incomplete. AGENTS.md/CLAUDE.md mix contributor rules with product architecture, so they are not wholly user-facing product documentation.
The product turns observed traffic into calls, agent turns, service topology, metrics, and exportable training data, giving it clear value for the stated use cases. The console, API, metrics, and replay workflow have concrete uses. Installation guidance discusses permissions and configuration trade-offs, but the packet does not quantify storage, data-governance, or operational costs at high volume, so cost-benefit receives partial credit.
README claims about architecture and features are partly corroborated by the supplied configuration, API, capture source, and installation guide; limitations and experimental features are also identified. CI and soak claims are descriptions in the packet, not independently verified results, and key implementations and changelog details are absent from this sample. The materials sometimes distinguish facts from qualifications, but several performance and coverage claims lack direct evidence in the supplied files.
- Captured data may contain prompts, model responses, tool calls, and other sensitive plaintext; verify listener exposure, API access controls, data-directory permissions, and retention before deployment.
- Live capture and eBPF require elevated capabilities; eBPF is experimental and has specific kernel prerequisites.
- The installer examples download and execute a script; review it and verify release checksums before deployment.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.8.3 Heron v0.8.3
Release notes excerpt
[0.8.3] — 2026-10-12 Fixed - Active calls climbed without bound and never came back down. A deployment whose real concurrency peaked at 28 reported a near-constant 16,600 globally and 48,878 for one model. Concurrency was tracked as +1 per Start and −1 per Complete *by dimension*, and the two events name the model from different places: the Start from the request, the Complete from the response. A server that answers a request for one name with another — an alias, a canonical id — left every such call counted forever, and because …View on GitHub ↗ -
v0.8.2 Heron v0.8.2
Release notes excerpt
[0.8.2] — 2026-09-16 Performance - **Opening a large agent turn, and the services topology graph, were spending almost all of their time in one search.** aglake charges a fixed cost per search-position term, linear in the number of terms and independent of how many events match, so the no-JOIN read pattern — fetch the parent, then id IN (?, ?, …) for its children — bought nothing from batching the ids into one query and paid for every one of them serially. Measured on a production instance: opening an agent turn cost about 35 ms per call it contained, so the …View on GitHub ↗ -
v0.8.1 Heron v0.8.1
Release notes excerpt
[0.8.1] — 2026-09-12 v0.8.0 was tagged from this same content but never released: the aarch64-unknown-linux-musl leg of the release matrix failed to link, so no release was created and nothing shipped. 0.8.1 is that content plus the build fix — there is no released 0.8.0 to upgrade from. Changed - The aglake storage backend now targets aglake 0.3 and is named for it. The log platform Heron writes to renamed itself from sglog to Netis Aglake, and made the rename a breaking boundary rather than an alias layer — the REST …View on GitHub ↗
FAQ
Does Heron require a paid LLM service or API key?
Can ordinary packet capture inspect encrypted traffic?
What permissions does live capture need?
Does the console stop when PCAP replay finishes?
Does Heron provide cross-cluster client tracing?
Is Heron Traffic Observatory open source?
Is Heron Traffic Observatory still maintained?
Who makes Heron Traffic Observatory?
What is Heron Traffic Observatory's official website?
Thanks — we use this to improve the page.