Skip to content

Latest commit

 

History

History
77 lines (51 loc) · 2.22 KB

TELEMETRY.md

File metadata and controls

77 lines (51 loc) · 2.22 KB

Telemetry for Docker cagent

The telemetry system in Docker cagent collects anonymous usage data to help improve the tool. All events are processed synchronously when recorded. Telemetry can be disabled at any time.

On first startup, Docker cagent displays a notice about telemetry collection and how to disable it, so users are always informed.

Quick Start

Disable telemetry

# Environment variable
TELEMETRY_ENABLED=false cagent run agent.yaml

# The application defaults to enabled when no environment variable is set

Enable debug mode (see events locally)

# Use the --debug flag to see telemetry events printed locally
cagent run agent.yaml --debug

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

For Developers

Telemetry is automatically wrapped around all commands. If you need to record additional events, use the context-based approach:

// Recommended: Use 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 telemetry calls:
telemetry.TrackCommand("run", args)

Event Types

The system uses structured, type-safe events:

  • Command events: Track CLI command execution with success status
  • Tool events: Track agent tool calls with timing and error information
  • Token events: Track LLM token usage by model, session, and cost
  • Session events: Track agent session lifecycle with separate start/end events and aggregate metrics

Events are processed synchronously when Track() is called, sending HTTP requests immediately.

Configuration

Telemetry is enabled by default. To disable it, set:

  • TELEMETRY_ENABLED=false