How tracewick/agent works
Tracewick Agent is a long-running Go sidecar that reads PHP spool-v2 files and delivers aggregated profiles to Pyroscope. Its main workflow is configured and started through the CLI, claims and parses spool files, groups compatible profiles, decodes/merges and encodes pprof, pushes to Pyroscope, then acknowledges, releases, rejects, or pauses delivery according to the result. Supporting branches include cardinality control, operational metrics, and delivery limits/policy. Relationships reflect the README and shown imports/calls; several implementation details are unsampled, so uncertain links are omitted.
Main entry points: drainer.go Drain pass · cli.go CLI runner · source.go Spool claims · config.go Configuration
Components 21
Runtime orchestration
- Agent command
cmd/tracewick-agent/main.go - CLI runner
internal/cli/cli.go - Configuration
internal/config/config.go - Polling agent
internal/agent/agent.go - Drain pass
internal/agent/drainer.go
Spool and aggregation
- Spool claims
internal/spool/source.go - Spool parsing
internal/spool/file.go - Window grouping
internal/aggregate/group.go - Aggregation keys
internal/aggregate/key.go - Cardinality gate
internal/aggregate/cardinality.go
Profile processing
- Profile decoding
internal/pprof/compact.go - Profile merging
internal/pprof/merge.go - Pprof encoding
internal/pprof/encode.go
Delivery controls
- Pyroscope client
internal/pyroscope/client.go - Push request encoding
internal/pyroscope/push.go - Delivery policy
internal/delivery/policy.go - Resource limits
internal/delivery/limits.go
Operations
- Prometheus metrics
internal/metrics/registry.go - Metrics endpoint
internal/metrics/server.go
Other components
- PHP spool writer
- Pyroscope
Connections 25
- PHP spool writer → Spool claims: writes files
README.md - Agent command → CLI runner: runs
cmd/tracewick-agent/main.go - CLI runner → Configuration: loads settings
internal/cli/cli.go - CLI runner → Polling agent: constructs and runs
internal/cli/cli.go - CLI runner → Metrics endpoint: starts
internal/cli/cli.go - Polling agent → Drain pass: drains repeatedly
internal/agent/agent.go - Polling agent → Spool claims: reads backlog
internal/agent/agent.go - Drain pass → Spool claims: claims files
internal/agent/drainer.go - Drain pass → Spool parsing: parses claims
internal/agent/drainer.go - Drain pass → Window grouping: groups profiles
internal/agent/drainer.go - Drain pass → Profile decoding: decodes profiles
internal/agent/drainer.go - Drain pass → Profile merging: merges groups
internal/agent/drainer.go - Drain pass → Pprof encoding: encodes pprof
internal/agent/drainer.go - Drain pass → Pyroscope client: pushes profiles
internal/agent/drainer.go - Drain pass → Delivery policy: classifies results
internal/agent/drainer.go - Drain pass → Spool claims: acks or releases
README.md - Pyroscope client → Push request encoding: encodes request
internal/pyroscope/client.go - Pyroscope client → Pyroscope: posts profiles
internal/pyroscope/client.go - Configuration → Spool claims: configures spool
internal/config/config.go - Configuration → Resource limits: sets limits
internal/config/config.go - Drain pass → Resource limits: enforces budgets
internal/agent/drainer.go - Window grouping → Aggregation keys: validates keys
internal/aggregate/group.go - Drain pass → Cardinality gate: limits label keys
- CLI runner → Prometheus metrics: creates registry
internal/cli/cli.go - Metrics endpoint → Prometheus metrics: serves metrics