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.
Once the user authenticates, events also carry their CircleCI user UUID and an identify call joins the anonymous IDs the install was reporting under to that user, so the journey before logging in is not attributed to a stranger. See Sender.Identify and IdentifyUser.
Modeled on circleci-cli's internal/telemetry package.
Index ¶
- func DetectCodingAgent() string
- func DisableTelemetry(cmd *cobra.Command)
- func IdentifyUser(ctx context.Context, userID uuid.UUID)
- 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 IdentifyUser ¶ added in v0.7.188
IdentifyUser de-anonymizes the current session: it attaches userID to every event the Sender in ctx reports from here on, and sends an identify call so Segment joins the anonymous identifiers this install was reporting under to that user. Call it right after an authentication flow persists a user ID.
It is best-effort, like the rest of telemetry: a missing Sender or a failed enqueue is silently ignored rather than breaking the auth flow the user actually asked for.
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
// SessionTrackingID, when non-zero, is used as AnonymousId so all chunk
// invocations within a session share a common anonymous identifier.
// When zero, InstanceID is used as AnonymousId instead.
SessionTrackingID 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.
UserID uuid.UUID
// OSName, OSVersion, KernelArch, and PlatformFamily populate the Segment
// OS and Device context fields. Best-effort: zero values are sent as-is.
OSName string
OSVersion string
KernelArch string
PlatformFamily string
// Extra is forwarded to Context.Traits on every event (e.g. "agent", "is_tty").
Extra map[string]any
}
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.
func (*Sender) Close ¶
Close flushes buffered events to their destinations. Safe to call multiple times and on a nil Sender.
func (*Sender) Identify ¶ added in v0.7.188
Identify sends a Segment identify joining this install's anonymous ID(s) to userID. One call goes out per anonymous ID (session and/or instance), so both the in-session and out-of-session histories join the user. No traits are sent. Safe to call on a nil or closed Sender; uuid.Nil is a no-op.
Source Files
Directories