https://github.com/eunomia-bpf/AgentSight
Zero instrucment system-level AI agent tracing in eBPF
https://github.com/eunomia-bpf/AgentSight
agent ebpf llm observability
Last synced: about 11 hours ago
JSON representation
Zero instrucment system-level AI agent tracing in eBPF
- Host: GitHub
- URL: https://github.com/eunomia-bpf/AgentSight
- Owner: eunomia-bpf
- License: mit
- Created: 2025-07-07T21:16:41.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2026-06-20T02:10:21.000Z (10 days ago)
- Last Synced: 2026-06-20T02:13:04.186Z (10 days ago)
- Topics: agent, ebpf, llm, observability
- Language: C
- Homepage: https://eunomia.dev/agentsight/
- Size: 41.8 MB
- Stars: 460
- Watchers: 4
- Forks: 65
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-cli-coding-agents - AgentSight - instrumentation eBPF observability for LLM/coding agents; captures syscall-level traces (file, process, network) without modifying the agent. MIT. (Harnesses & orchestration / Agent infrastructure)
- awesome-ai-agents-2026 - AgentSight - LLM/コーディングエージェント向けのゼロインストルメンテーション eBPF オブザーバビリティ。エージェントを変更せずに syscall レベル（プロセス、ファイル、ネットワーク）のトレースをキャプチャし、フルスタックの挙動分析を実現。MIT。 (📊 エージェント評価とオブザーバビリティ / 自動運転)
README
# AgentSight: System-wide AI agent profiling and monitoring with eBPF
[](https://opensource.org/licenses/MIT)
[](https://github.com/eunomia-bpf/agentsight/actions/workflows/ci.yml)
[](https://arxiv.org/abs/2508.02736)
[](https://dl.acm.org/doi/10.1145/3766882.3767169)
**English** | [中文](https://github.com/eunomia-bpf/agentsight/blob/master/README.zh-CN.md)
Your local first `perf`/`top`/`strace`/`nsight`-like tool for AI agents. See what agents actually do
to your machine, and connect those actions back to the prompts, model calls, and
tool decisions that triggered them.
Run `agentsight` around Claude Code, Codex, Gemini CLI,
OpenCode, OpenClaw, or any command. AgentSight records:
- processes and child processes, shell commands, cwd, argv, exit status, and duration
- files created, written, truncated, renamed, or deleted
- network destinations contacted
- prompts, responses, tool intent, and LLM/model/token
No SDK, no proxy, no vendor integration. AgentSight observes with eBPF and TLS traffic tracing, so it works even when the agent is a
closed-source CLI. **✨ Zero SDK Required**
## Quick Start
```bash
cargo install agentsight
# or: wget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight && chmod +x agentsight
sudo agentsight top
```
Live sessions ranked by model, session tokens, health, process family, tool calls, file activity, and network activity
## 🚀 Why AgentSight?
### Traditional Observability vs. System-Level Monitoring
Application-level tools such as [LangSmith](https://docs.langchain.com/langsmith/observability-concepts), [Langfuse](https://langfuse.com/docs/observability/overview), and [Phoenix](https://arize.com/docs/phoenix/) are great for traces, prompts, tokens, evals, and latency when you own the application code. Gateway/proxy tools such as [Helicone](https://docs.helicone.ai/getting-started/integration-method/gateway) are useful when you can route provider traffic through a managed endpoint.
AgentSight focuses on the layer those tools often miss: what the agent actually does at the system boundary. It observes existing binaries and CLI agents without SDKs or proxies, then correlates LLM traffic with process execution, file access, and system activity.
| **Challenge** | **Application-Level Tools** | **AgentSight Solution** |
|---------------|----------------------------|------------------------|
| **Framework Adoption** | ❌ SDK, callback, or gateway integration per app | ✅ Drop-in system tracer, no code changes |
| **Closed-Source CLIs** | ❌ Limited to what the tool exposes or logs | ✅ Observes existing binaries and CLI agents from outside |
| **Agent-Controlled Logs** | ❌ Logs can be incomplete, disabled, or modified | ✅ Kernel-level events independent of app logging |
| **TLS LLM Traffic** | ❌ Visible when routed through SDKs/proxies | ✅ Captures plaintext at SSL/TLS calls without a proxy |
| **System Actions** | ❌ Often misses subprocesses and local file activity | ✅ Tracks process execution, file access, and resource use |
| **Cross-Boundary Behavior** | ❌ Traces usually stop at framework/process boundaries | ✅ Correlates LLM traffic with process and file events |
AgentSight captures critical interactions that application-level tools miss:
- Subprocess executions that bypass instrumentation
- Plaintext LLM payloads at SSL/TLS call boundaries
- File operations and system resource access
- Cross-boundary behavior across LLM, process, and file events
## Usage
### Prerequisites
- **Linux kernel**: 4.1+ with eBPF support (5.0+ recommended)
- **sudo access**: eBPF probes are auto-elevated; your agent stays unprivileged
For source builds, see [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md).
### Installation
#### Cargo or Release Binary
For local use, install with `cargo install agentsight` or download the latest
release binary, then start with `sudo agentsight top`. Use the examples below when
you want to record a specific command or inspect saved sessions.
#### Docker
Docker is useful for container, CI, or isolated Linux environments, but it still needs privileged host access for eBPF. See [docs/docker.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/docker.md).
#### Build from Source
Build requirements and source build commands live in [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md).
### Querying Past Sessions
Every `record` session is automatically saved to an `agentsight-*.db` SQLite
file in the current directory. Start with the live and record commands, then
use `agentsight report` for structured queries:
```bash
sudo agentsight top # live ranked view of current agent sessions
agentsight monitor install-service # install/start the background monitor service
agentsight top --db run.db --once # ranked view of a saved session
sudo agentsight record -- claude # record a command
agentsight report # high-level run summary (default)
agentsight report list # recorded sessions in this directory
agentsight report prompts --json # full LLM request/response JSON
agentsight report token # token usage from latest DB, or local agent sessions
agentsight report token --group-by dir # token usage by session/process working directory
agentsight report audit --json # process spawns, file opens, API calls
agentsight report serve # open the web UI for the latest session in this directory
agentsight report export -o snapshot.json # export for web dashboard
agentsight report --local # summarize native Claude/Codex/Gemini sessions
```
### Offline Agent pprof Profiles
Use `agentpprof` when you want a no-sudo pprof/folded-stack/SVG summary of
local Codex or Claude session history:
```bash
cargo run --manifest-path agentpprof/Cargo.toml -- \
--project-root . \
--view tokens \
-o agent.pb.gz
go tool pprof -top agent.pb.gz
```
The `tokens` view is the best first flamegraph for cost analysis: it aggregates
real local Codex/Claude development sessions by project, agent, session tag,
prompt tag, model, and token kind.
Offline token profile generated from real local bpf-benchmark coding-agent sessions
See [agentpprof/README.md](agentpprof/README.md) for CLI details and
[docs/flamegraph](docs/flamegraph-example/README.md) for flamegraph examples, view
selection, and deterministic tagging rules.
### Web Interface
During a session, visit [http://127.0.0.1:7395](http://127.0.0.1:7395) for live traffic, process trees, and metrics:
- **Timeline View**: http://127.0.0.1:7395/timeline
- **Process Tree**: http://127.0.0.1:7395/tree
- **Event Log**: http://127.0.0.1:7395/logs
- **Metrics View**: http://127.0.0.1:7395/metrics
For a saved SQLite session, run `agentsight report serve --db run.db` and open the same routes.
Process tree visualization for agent subprocesses and file activity
Timeline visualization for LLM, process, file, and network events
Metrics visualization for memory and CPU usage
### Supported Agents
> **Privileges:** eBPF probes need root. Use `sudo` for live capture commands.
`record` auto-discovers binaries, SSL libraries, and container processes. Works out of the box for:
| Agent | Command |
|-------|---------|
| Claude Code | `sudo ./agentsight record -- claude` |
| Gemini CLI | `sudo ./agentsight record -- gemini` |
| Python (aider, open-interpreter, …) | `sudo ./agentsight record -c python` |
| Docker containers (OpenClaw, …) | `sudo ./agentsight record -c node --binary-path docker://openclaw` |
| Any command | `sudo ./agentsight record -- ` |
See [docs/agents.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/agents.md) for agent-specific setup, SSL quirks, browser capture, MCP stdio, and advanced flags.
### OpenTelemetry Export
AgentSight can export captured LLM calls as OpenTelemetry **GenAI**
(`gen_ai.*`) spans over OTLP/HTTP — standards-compliant agent telemetry for any
agent, with zero in-process instrumentation.
```bash
sudo ./agentsight debug trace --otel --otel-endpoint http://localhost:4318
```
See [docs/otel.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/otel.md) for
collector setup and backend integration.
## ❓ Frequently Asked Questions
**Q: What permissions does AgentSight need?**
A: eBPF probes need root privileges, so AgentSight may prompt for `sudo`. With `record -- `, the monitored agent still runs as your normal user; only the probes are elevated.
**Q: What's the performance impact?**
A: Our evaluation reports less than 3% CPU overhead for typical traced agent workloads.
**Q: Where does captured data go?**
A: `record` stores sessions as `agentsight-*.db` files in the current directory by default, and `report` reads the latest matching file from that directory unless you pass `--db`. When no default DB exists, report commands warn and fall back to local Claude/Codex/Gemini agent sessions where available. `monitor` stores its weekly background DBs under `~/.agentsight/monitor`, and `top` is read-only unless you explicitly pass `--db` to inspect a saved session. Use `agentsight report`, `agentsight report list`, `agentsight report audit --json`, and `agentsight report token` to inspect prior runs. Captured data can include prompts, responses, paths, headers, and network targets, so treat logs and DBs as sensitive.
**Q: Why doesn't AgentSight capture traffic from Claude Code, Node.js, or Gemini CLI?**
A: These applications statically link their SSL library (BoringSSL for Claude/Bun, OpenSSL for **all** Node.js — both NVM and system installs) into their own binary instead of using system `libssl.so`, so there's nothing for sslsniff to hook by default. AgentSight handles this for you: `record -- ` always discovers the binary, and `record -c node` now auto-discovers the Node binary too. For Claude attach mode, pass `--binary-path`. See the "Zero-Config: record" and "Monitoring Node.js AI Tools" sections.
**Q: What should I check if tracing fails?**
A: Verify you are on Linux with eBPF support, have `sudo` or `CAP_BPF`/`CAP_SYS_ADMIN`, and are using `record -- ` or the correct `--binary-path` for statically linked agents.
## 🤝 Contributing
We welcome contributions! After cloning and building (see [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md)), you can:
```bash
# Run tests
make test
# Frontend development server
cd frontend && npm run dev
# Build debug versions with AddressSanitizer
make -C bpf debug
```
### Key Resources
- [CLAUDE.md](https://github.com/eunomia-bpf/agentsight/blob/master/CLAUDE.md) - Project guidelines and architecture
- [docs/design/README.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/design/README.md) - archived design notes and research drafts
## 📄 License
MIT License - see [LICENSE](https://github.com/eunomia-bpf/agentsight/blob/master/LICENSE) for details.
---
**💡 The Future of AI Observability**: As AI agents become more autonomous and capable of self-modification, traditional observability approaches become insufficient. AgentSight provides independent, system-level monitoring for safe AI deployment at scale.