AgentSight: System-wide AI agent tracing and monitoring with eBPF

English | 中文

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 a local trace of:

• 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 Instrumentation Required

Quick Start

cargo install agentsight
# or: wget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight && chmod +x agentsight
sudo agentsight top

If you downloaded the binary into the current directory, run sudo ./agentsight top. top loads eBPF probes, discovers local agents, and connects system activity to agent behavior in real time. See the Usage section for more examples and details.

🚀 Why AgentSight?

Traditional Observability vs. System-Level Monitoring

Application-level tools such as LangSmith, Langfuse, and Phoenix are great for traces, prompts, tokens, evals, and latency when you own the application code. Gateway/proxy tools such as Helicone 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.

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.

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.

Build from Source

Build requirements and source build commands live in docs/build.md.

Querying Past Sessions

Every stat -- <command> or record session is automatically saved to SQLite. Start with the perf-style commands, then use agentsight report for structured queries:

agentsight stat                              # counters for the latest saved session
sudo agentsight top                          # live ranked view of current agent sessions
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                       # all recorded sessions
agentsight report prompts --json             # full LLM request/response JSON
agentsight report token                      # token usage (auto-finds latest session)
agentsight report audit --json               # process spawns, file opens, API calls
agentsight report export -o snapshot.json    # export for web dashboard

Web Interface

During a session, visit 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

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:

Discover what's installed locally with ./agentsight discover.

See 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.

sudo ./agentsight debug trace --otel --otel-endpoint http://localhost:4318

See 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 -- <command> or stat -- <command>, 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 and stat -- <command> store sessions locally in SQLite by default. Use agentsight stat, agentsight top, 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 -- <command> 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 -- <command> or the correct --binary-path for statically linked agents.

🤝 Contributing

We welcome contributions! After cloning and building (see docs/build.md), you can:

# 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 - Project guidelines and architecture
• docs/design/README.md - archived design notes and research drafts

📄 License

MIT License - see 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.