Documentation
¶
Overview ¶
Package telemetry records one usage event per CLI invocation and sends it to the Volcano API, which forwards it to product analytics (volcano-hosting POST /cli/telemetry).
What is sent is fixed by Event: command path, the names of flags the user set, the selected project and the resource names the command addressed (see resources), CLI version, platform, CI vendor, whether stdin is a terminal, the coding agent that ran the CLI, whether the Volcano plugin is installed for that agent, the exit code and duration, and for failed runs the error type, API status and code, and the redacted error message.
Telemetry is on by default. VOLCANO_TELEMETRY_DISABLED or `volcano telemetry disable` turn it off. The settings live in the telemetry block of ~/.volcano/config.json, read once when the process starts: a change applies from the next command. The first recorded invocation prints a one-time notice. Sending happens in a detached `volcano telemetry flush` process so a command never waits on the network.
Index ¶
Constants ¶
const ( // EnvDisabled turns telemetry off. EnvDisabled = "VOLCANO_TELEMETRY_DISABLED" // EnvDebug prints each event to stderr instead of sending it. Off unless // set. EnvDebug = "VOLCANO_TELEMETRY_DEBUG" )
Environment variables that control telemetry.
const SkipAnnotation = "telemetry.skip"
SkipAnnotation marks a command whose invocations, and its subcommands', are never recorded (`volcano telemetry`, so an opt-out is not itself reported).
Variables ¶
This section is empty.
Functions ¶
func CIVendor ¶
CIVendor returns the CI vendor id, "generic" when only CI is set, and "" outside CI.
func DisabledByEnv ¶
DisabledByEnv reports whether VOLCANO_TELEMETRY_DISABLED turns telemetry off.
Types ¶
type Event ¶
type Event struct {
DeviceID string `json:"device_id"`
InvocationID string `json:"invocation_id"`
Timestamp string `json:"timestamp"`
Command string `json:"command"`
Flags []string `json:"flags"`
CLIVersion string `json:"cli_version"`
OS string `json:"os"`
Arch string `json:"arch"`
CPUs int `json:"cpus"`
CIVendor string `json:"ci_vendor"`
StdinTTY bool `json:"stdin_tty"`
Agent string `json:"agent"`
AgentSource string `json:"agent_source"`
AgentMarkers []string `json:"agent_markers"`
PluginInstalled bool `json:"plugin_installed"`
PluginVersion string `json:"plugin_version"`
ExitCode int `json:"exit_code"`
DurationMS int64 `json:"duration_ms"`
ErrorKind string `json:"error_kind,omitempty"`
ErrorStatus int `json:"error_status,omitempty"`
ErrorCode string `json:"error_code,omitempty"`
ErrorMessage string `json:"error_message,omitempty"`
ProjectID string `json:"project_id,omitempty"`
// Resources maps a usage-line placeholder or flag name to the resource
// name or ID the command was given.
Resources map[string]string `json:"resources,omitempty"`
}
Event is the request body of POST /cli/telemetry. Field names are the wire contract with volcano-hosting; the server re-validates every value.
type Invocation ¶
type Invocation struct {
Command *cobra.Command // the executed command (cobra ExecuteC); may be nil
Err error
ExitCode int
Start time.Time
Stderr io.Writer // receives the first-run notice and debug output
StdinTTY bool
// Args are the raw command-line arguments, checked for --offline when
// flag parsing failed before cobra read it.
Args []string
}
Invocation is what the entry point knows about the command that just ran.
type Recorder ¶
type Recorder struct {
Getenv func(string) string
LookupEnv func(string) (string, bool)
Now func() time.Time
// LoadConfig reads the CLI config (config.Load).
LoadConfig func() (*config.Config, error)
// UpdateConfig changes the config under its lock (config.Update).
UpdateConfig func(mutate func(*config.Config) (bool, error)) error
// HomeDir is replaced with "~" in error messages (os.UserHomeDir).
HomeDir func() (string, error)
Send func(payload []byte) error
// PluginStatus reports whether the Volcano plugin is installed for a
// setup harness name; see setup.PluginStatus.
PluginStatus func(harness string) (bool, string)
// contains filtered or unexported fields
}
Recorder records the invocation of one CLI process. It reads the config once, on first use, and answers both Reporting and Record from that read. The zero value uses the real environment, config, and flush process; tests replace the fields. A Recorder must not be copied after first use.
func (*Recorder) Record ¶
func (r *Recorder) Record(inv Invocation)
Record records one invocation. It never fails the command: every error is swallowed, since telemetry must not change what the CLI does.
func (*Recorder) Reporting ¶
Reporting reports whether this process may send usage data, including the agent request headers: no env opt-out, not turned off with `volcano telemetry disable`, and the first-run notice already shown by an earlier process. A config that cannot be read, or a run before the notice (including every run in a home where the notice can never be saved), counts as off.
type State ¶
type State = config.TelemetryConfig
State is the telemetry block of ~/.volcano/config.json.
Source Files