Documentation
¶
Overview ¶
Package telemetry provides opt-in anonymous usage analytics for the StackEye CLI.
Telemetry is disabled by default and requires explicit user consent. When enabled, it collects anonymous usage data to help improve the CLI: - Command names and exit codes - Execution duration - CLI version and platform info - Anonymized organization ID (SHA-256 hash prefix)
NO personal data, API keys, error messages, or identifiable information is collected.
Environment variable STACKEYE_TELEMETRY=0 disables telemetry regardless of config.
Index ¶
- Constants
- func CheckAndPromptConsent(stdin io.Reader, stdout io.Writer) (bool, error)
- func MarkPrompted() error
- func ResetClient()
- type Client
- func (c *Client) Flush(timeout time.Duration)
- func (c *Client) GetLastEvent() *Event
- func (c *Client) IsEnabled() bool
- func (c *Client) Reload()
- func (c *Client) SetEnabled(enabled bool)
- func (c *Client) SetEndpoint(endpoint string)
- func (c *Client) Track(ctx context.Context, command string, exitCode int, duration time.Duration)
- type Event
Constants ¶
const ConsentMessage = `` /* 193-byte string literal not displayed */
ConsentMessage is the message shown to users when prompting for telemetry consent.
const ConsentPrompt = "Enable telemetry? [y/N]: "
ConsentPrompt is the prompt shown after the consent message.
const DefaultEndpoint = "https://api.stackeye.io/v1/telemetry/cli"
DefaultEndpoint is the telemetry API endpoint.
const EnvTelemetry = "STACKEYE_TELEMETRY"
EnvTelemetry is the environment variable to override telemetry settings. Set to "0" or "false" to disable telemetry regardless of config.
Variables ¶
This section is empty.
Functions ¶
func CheckAndPromptConsent ¶
CheckAndPromptConsent checks if the user has been prompted for telemetry consent. If not, it prompts them and saves their preference. Returns true if telemetry is enabled after the check.
This should be called early in CLI initialization, but only for interactive sessions. Non-interactive sessions (piped input, CI/CD) should skip the prompt.
func MarkPrompted ¶
func MarkPrompted() error
MarkPrompted marks the user as having been prompted for telemetry consent, without changing their telemetry preference. This is useful when the user explicitly enables/disables via command.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client handles telemetry event collection and transmission.
func GetClient ¶
func GetClient() *Client
GetClient returns the global telemetry client. The client is initialized once and reused across the CLI lifetime.
func (*Client) Flush ¶
Flush waits for all pending telemetry events to be sent. Call this before exiting the CLI to ensure events are not lost. Returns after all pending sends complete or timeout expires.
func (*Client) GetLastEvent ¶
GetLastEvent returns the most recent event for debugging purposes. Returns nil if no event has been tracked.
func (*Client) Reload ¶
func (c *Client) Reload()
Reload refreshes telemetry settings from config. Call this after changing telemetry preferences.
func (*Client) SetEnabled ¶
SetEnabled enables or disables telemetry. This does NOT persist the setting - use config.Save() for that.
func (*Client) SetEndpoint ¶
SetEndpoint overrides the telemetry endpoint (for testing).
type Event ¶
type Event struct {
// CLIVersion is the version of the CLI (e.g., "1.2.3").
CLIVersion string `json:"cli_version"`
// Command is the command name (e.g., "probe create").
Command string `json:"command"`
// ExitCode is the command's exit code (0 for success).
ExitCode int `json:"exit_code"`
// DurationMs is the execution time in milliseconds.
DurationMs int64 `json:"duration_ms,omitempty"`
// OS is the operating system (e.g., "linux", "darwin", "windows").
OS string `json:"os"`
// Arch is the architecture (e.g., "amd64", "arm64").
Arch string `json:"arch"`
// OrgIDHash is the first 16 characters of the SHA-256 hash of the org ID.
// Empty if not authenticated.
OrgIDHash string `json:"org_id_hash,omitempty"`
}
Event represents a telemetry event to be sent to the backend.
Source Files