Telemetry
cagent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time.
On first startup, cagent displays a notice about telemetry collection so you’re always informed. All events are processed synchronously when recorded.
Disabling Telemetry
# Disable via environment variable
$ TELEMETRY_ENABLED=false cagent run agent.yaml
# Or export it in your shell profile
$ export TELEMETRY_ENABLED=false
ℹ️ Default
Telemetry is **enabled by default**. Set TELEMETRY_ENABLED=false to opt out.
What’s Collected ✅
- Command names and success/failure status
- Agent names and model types
- Tool names and whether calls succeed or fail
- Token counts (input/output totals) and estimated costs
- Session metadata (durations, error counts)
What’s NOT Collected ❌
- User input or prompts
- Agent responses or generated content
- File contents
- API keys or credentials
- Personally identifying information (PII)
💡 See events locally
Use --debug to see telemetry events printed to the debug log without sending them anywhere additional.
cagent run agent.yaml --debug
Event Types
The telemetry system uses structured, type-safe events:
| Event Type | What It Tracks |
|---|---|
| Command | CLI command execution with success status |
| Tool | Agent tool calls with timing and error information |
| Token | LLM token usage by model, session, and cost |
| Session | Agent session lifecycle with start/end events and aggregate metrics |
For Developers
Telemetry is automatically wrapped around all commands. To record additional events, use the context-based API:
// Recommended: context-based telemetry (clean, testable)
if telemetryClient := telemetry.FromContext(ctx); telemetryClient != nil {
telemetryClient.RecordToolCall(ctx, "filesystem", "session-id", "agentName", time.Millisecond*500, nil)
telemetryClient.RecordTokenUsage(ctx, "gpt-4", 100, 50, 0.01)
}
// Or use direct calls
telemetry.TrackCommand("run", args)
Events are processed synchronously when Track() is called, sending HTTP requests immediately.