Heron

Heron is a passive observability tool for AI agents and LLM APIs that reconstructs turns, tool calls, and performance metrics from network traffic or the host TLS boundary.

Strumenti Dev AI Monitoraggio e Log

Visita il Sito Web

Overview

Heron is a passive observability tool for AI agents and LLM APIs. It reconstructs agent activity from network traffic, or at the host TLS boundary, so users can inspect turns, tool calls, LLM interactions, and performance data without modifying the workloads being observed.

The project positions itself as a provider-side monitor: it does not sit in the request path, does not require SDK changes, and can be used by replaying a `.pcap`, capturing from a live interface, or ingesting traffic from a trusted source. The README also describes an experimental Linux eBPF capture path for encrypted traffic on host.

Its console and API surface expose timelines, turn reconstruction, and metrics such as TTFT, latency, throughput, error rate, and per-agent mix. The repository also highlights outputs for service-topology inspection and export of turns into fine-tuning-ready JSONL.

What Heron does

Agent turn reconstruction

Reconstructs multi-call agent interactions into single, addressable turns so you can follow planner, tool, result, and next-step sequences instead of raw requests.

Traffic-derived performance metrics

Measures live TTFT, latency, throughput, error rate, and per-agent mix from captured traffic and presents them in a local console and API.

Multiple capture paths

Works from `.pcap` replay, a live network interface, cloud-probe ingress, or an experimental Linux eBPF source for TLS-encrypted traffic on host.

Service topology view

Classifies serving topology from bytes on the wire and can display client-to-proxy-to-backend relationships as a directed graph.

SFT trajectory export

Exports turns or sessions as OpenAI-style messages JSONL with tool calls, results, and reasoning preserved for fine-tuning workflows.

Wire-API decoding

Recognizes several wire APIs, including OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini AI Studio.

Common use cases

Analyze captured agent sessions
Replay recorded packet captures to inspect agent behavior after the fact, including turn structure, tool usage, and timing, without needing access to the original runtime.
Observe production traffic without code changes
Monitor an inference host or TLS terminator to observe LLM traffic passively in environments where adding SDK instrumentation is impractical.
Map inference infrastructure
Inspect how a fleet routes requests through proxies and backends by using the service-topology view to infer which endpoints serve which roles.
Prepare training data from live traffic
Export real agent turns into OpenAI-style messages JSONL so they can be reused in downstream fine-tuning or dataset-building workflows.
Investigate latency and reliability issues
Use the CLI and local console to review timelines, metrics, and per-agent mixes during debugging or performance review.

Pros and Cons

Pros

Passive monitoring with no SDK changes required.
Can replay `.pcap` files, capture live traffic, or ingest from a trusted packet source.
Reconstructs full agent turns rather than leaving you with isolated HTTP calls.
Surfaces operational metrics such as TTFT, latency, throughput, and error rate.
Can export turns or sessions in a format suited to fine-tuning workflows.

Cons

The repository does not publish standalone Heron pricing in the collected sources.
The eBPF capture path is described as experimental and Linux-only.
Packet capture sees plaintext only, so Heron must be deployed where traffic is already decrypted unless the eBPF path is used.

FAQ

What does Heron monitor?

Heron reconstructs agent turns, tool calls, and LLM interactions from network traffic or from the TLS boundary. It is described as passive observability with no SDK changes and no proxy in the request path.

How do you use it?

The README shows a quick start that installs a user-local binary on Linux or macOS, then replays a `.pcap` with `heron --pcap-file capture.pcap --no-retention`. It also supports live capture from an interface such as `eth0` on Linux.

Which agent or API formats are supported?

The source highlights OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini AI Studio wire formats. It also calls out named profiles for Claude Code and OpenAI Codex CLI, plus a generic profile for other agents.

Where should Heron be deployed?

Heron is intended to run where traffic is already decrypted, such as on the inference host or behind the TLS terminator. The README also describes an experimental Linux eBPF capture path for on-host encrypted traffic.

Does Heron have published pricing?

The GitHub pricing page shows GitHub has free, Team, and Enterprise offerings, but it does not provide product pricing for Heron itself. The repository sources here do not state a Heron price.

Quick Facts

Category: Developer Tool
Primary use: Agent and LLM API observability
Deployment model: Provider-side or host-side passive capture
Interfaces mentioned: `.pcap`, live interface, cloud-probe ZMQ, Linux eBPF
Supported wire APIs: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini AI Studio
Repository: github.com/Netis/heron