Documentation
¶
Overview ¶
Package telemetry sends anonymous command-usage events to Segment.
Telemetry is opt-out: it fires unless disabled via a well-known opt-out environment variable or the persisted telemetry config preference (see internal/config.IsTelemetry). Only the command path, the names (never values) of flags the user set, the outcome ("success"/"failure"), the wall-clock duration, the Go type and message of any error, a per-install anonymous instance ID, the operating system, and the detected AI coding agent (if any) are ever collected — no flag values, argument values, or other PII.
Modeled on circleci-cli's internal/telemetry package.
Index ¶
- func DetectCodingAgent() string
- func DisableTelemetry(cmd *cobra.Command)
- func IsTelemetryDisabled(cmd *cobra.Command) bool
- func RecordForSubcommands(cmd *cobra.Command)
- func RecordNow(cmd *cobra.Command, err error, duration time.Duration)
- func WithSender(ctx context.Context, s *Sender) context.Context
- type Config
- type Meta
- type Sender
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DetectCodingAgent ¶ added in v0.7.123
func DetectCodingAgent() string
DetectCodingAgent returns a stable name for the AI coding agent chunk-cli appears to have been invoked from, based on well-known environment variables those agents set in their shells. Returns "" if no known agent is detected, which is the common case for a human running chunk directly.
func DisableTelemetry ¶
DisableTelemetry marks cmd so RecordForSubcommands skips wrapping it. Used for commands that should never report their own invocation, such as the hidden receive-telemetry command.
func IsTelemetryDisabled ¶
IsTelemetryDisabled reports whether DisableTelemetry was called on cmd.
func RecordForSubcommands ¶
RecordForSubcommands wraps every descendant command's RunE so it reports a command_invocation event after running, without requiring per-command changes.
func RecordNow ¶
RecordNow reports a command_invocation event immediately: the full command path, the sorted comma-joined names (never values) of flags the user set, the outcome ("success" or "failure"), the wall-clock duration in milliseconds, and — on failure — the Go type and message of the error. chunk-cli events are distinguished from circleci-cli events via Context.App.Name ("chunk-cli").
Types ¶
type Config ¶
type Config struct {
// Send enables sending events to Segment via the delegate subprocess.
Send bool
// Log enables logging events to stderr for debugging.
Log bool
// Binary is re-exec'd with JSON-encoded events on stdin when Send is true.
Binary string
// WriteKey is the Segment write key used by the delegate subprocess.
WriteKey string
// Endpoint is the Segment endpoint. Optional; defaults to segment.io.
// Normally only set for testing.
Endpoint string
// TestDestination, when non-nil, is added as an event destination so
// tests can record events and assert on them synchronously without
// spawning a subprocess or hitting the network.
TestDestination destination
Metadata Meta
}
Config configures a Sender.
type Meta ¶
type Meta struct {
Version string
InstanceID uuid.UUID
// UserID is the authenticated CircleCI user UUID. When non-zero it is sent
// as UserId so events can be attributed to a real user. The install UUID
// (InstanceID) is always sent as AnonymousId regardless.
UserID uuid.UUID
// OS is the operating system chunk-cli is running on, e.g. runtime.GOOS.
OS string
// CodingAgent is the AI coding agent chunk-cli was invoked from (e.g.
// "claude-code", "cursor"), or "" if none was detected. See
// DetectCodingAgent.
CodingAgent string
}
Meta describes the fields attached to every tracked event.
type Sender ¶
type Sender struct {
// contains filtered or unexported fields
}
Sender tracks anonymous command-usage events. A nil *Sender is valid and silently drops events, so callers never need to nil-check it.
func FromContext ¶
FromContext returns the Sender attached to ctx, or nil if none was attached.
Source Files
Directories