Documentation
¶
Index ¶
- Constants
- func LoadOrCreateMachineID(ctx context.Context) string
- func RunFlush(ctx context.Context, endpoint string, in io.Reader) error
- func ToMap(v any) map[string]any
- type Client
- func (c *Client) Close()
- func (c *Client) Emit(ctx context.Context, name string, payload map[string]any)
- func (c *Client) EmitCommand(ctx context.Context, params CommandParameters, result CommandResult)
- func (c *Client) EmitEmulatorLifecycleEvent(ctx context.Context, event LifecycleEvent)
- func (c *Client) GetEnvironment(ctx context.Context) Environment
- func (c *Client) MachineID(ctx context.Context) string
- func (c *Client) SessionID() string
- func (c *Client) SetAuthToken(token string)
- type CommandEvent
- type CommandParameters
- type CommandResult
- type Environment
- type LifecycleEvent
- type LocalStackInfo
- type Option
Constants ¶
const ( LifecycleStartSuccess = "start_success" LifecycleStop = "stop" LifecycleStartError = "start_error" )
Lifecycle event type constants.
const ( ErrCodePortConflict = "port_conflict" ErrCodeImagePullFailed = "image_pull_failed" ErrCodeLicenseInvalid = "license_invalid" ErrCodeStartFailed = "start_failed" ErrCodeStartTimeout = "start_timeout" ErrCodeEmulatorMismatch = "emulator_mismatch" )
Error codes for start_error lifecycle events.
const FlushCommandName = "__flush-telemetry"
FlushCommandName is the argv[1] sentinel for the detached flusher subprocess. cmd.Execute must short-circuit on it before constructing a telemetry client, otherwise the flusher would emit events and spawn flushers recursively.
Variables ¶
This section is empty.
Functions ¶
func LoadOrCreateMachineID ¶
LoadOrCreateMachineID attempts to derive a stable, anonymized machine ID by trying in order: Docker daemon ID, /etc/machine-id, then a persisted random UUID. Prefixes (dkr_, sys_, gen_) indicate origin, matching the Python implementation in localstack-core so IDs can be correlated across tools.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func NewWithInProcessFlush ¶ added in v0.11.0
NewWithInProcessFlush returns an enabled Client whose Close flushes synchronously in-process, so tests can verify event delivery without forking the binary.
func (*Client) Close ¶
func (c *Client) Close()
Close hands pending events to a detached subprocess and returns immediately, so analytics endpoint latency never delays command exit.
func (*Client) EmitCommand ¶ added in v0.5.2
func (c *Client) EmitCommand(ctx context.Context, params CommandParameters, result CommandResult)
EmitCommand emits an lstk_command telemetry event. The Environment block is populated automatically from the client state.
func (*Client) EmitEmulatorLifecycleEvent ¶ added in v0.5.2
func (c *Client) EmitEmulatorLifecycleEvent(ctx context.Context, event LifecycleEvent)
EmitEmulatorLifecycleEvent emits an lstk_lifecycle telemetry event. The Environment field is populated automatically from the client state; any value set by the caller is overwritten.
func (*Client) GetEnvironment ¶ added in v0.5.2
func (c *Client) GetEnvironment(ctx context.Context) Environment
GetEnvironment returns the common environment payload for telemetry events, using the auth token set via SetAuthToken. The machine id comes from MachineID, which owns the lazy derivation and its disabled-client guard.
func (*Client) MachineID ¶ added in v0.22.0
MachineID is the anonymized machine identity stamped on this client's events (the salted hash produced by LoadOrCreateMachineID, never a raw Docker or system id). It is conveyed to extension processes through the runtime context so an extension emitting its own telemetry reports the same machine without re-deriving it.
The value is computed lazily on first use and cached for the process; every consumer (this accessor and event building via GetEnvironment) goes through here. Always empty when telemetry is disabled: a disabled client emits no events, so there is no identity to share — and the guard precedes the computation, so a disabled client never dials Docker or persists a generated id to derive a value it would only mask.
func (*Client) SessionID ¶ added in v0.21.0
SessionID is the per-process correlation id stamped on every event this client emits. It is conveyed to extension processes through the runtime context so an extension's own telemetry joins to the lstk invocation that dispatched it. Empty when telemetry is disabled, since a disabled client has no session.
func (*Client) SetAuthToken ¶ added in v0.5.2
SetAuthToken stores the resolved auth token for inclusion in telemetry events. Call this once the token is known (e.g. after keyring resolution or interactive login).
type CommandEvent ¶ added in v0.5.2
type CommandEvent struct {
Environment Environment `json:"environment"`
Parameters CommandParameters `json:"parameters"`
Result CommandResult `json:"result"`
}
CommandEvent is the payload for an lstk_command telemetry event.
type CommandParameters ¶ added in v0.5.2
type CommandParameters struct {
Command string `json:"command"`
Subcommand string `json:"subcommand,omitempty"`
Flags []string `json:"flags"`
Proxied bool `json:"proxied"`
}
CommandParameters holds the command name and set flags. Subcommand is the safe leading tokens of a proxied tool invocation ("s3 ls" for `lstk aws s3 ls`), empty for lstk's own commands. Proxied says the invocation asked for a wrapped tool, whatever happened next. It is never omitempty: JSONHas on the key is the pipe's cutover marker.
type CommandResult ¶ added in v0.5.2
type CommandResult struct {
DurationMS int64 `json:"duration_ms"`
ExitCode int `json:"exit_code"`
ErrorMsg string `json:"error_msg,omitempty"`
ProxyExitCode *int `json:"proxy_exit_code,omitempty"`
Cancelled bool `json:"cancelled"`
}
CommandResult holds the outcome of a command invocation. ProxyExitCode is the wrapped tool's exit code, present exactly when the tool ran to completion (0 included, -1 when an untrapped signal killed it); nil must marshal as an absent key, never null, because the pipe reads presence as "the tool ran". Cancelled is raw (a zero ExitCode is still a success) and, like Proxied, never omitempty. Contract: openspec/changes/distinguish-proxied-command-errors.
type Environment ¶ added in v0.5.2
type Environment struct {
LstkVersion string `json:"lstk_version"`
AuthTokenID string `json:"auth_token_id,omitempty"`
MachineID string `json:"machine_id,omitempty"`
OS string `json:"os"`
Arch string `json:"arch"`
}
Environment is the common environment block included in all telemetry events.
type LifecycleEvent ¶ added in v0.5.2
type LifecycleEvent struct {
EventType string `json:"event_type"`
Environment Environment `json:"environment"`
Emulator config.EmulatorType `json:"emulator"`
Image string `json:"image,omitempty"`
ContainerID string `json:"container_id,omitempty"`
DurationMS int64 `json:"duration_ms,omitempty"`
Pulled bool `json:"pulled,omitempty"`
LocalStackInfo *LocalStackInfo `json:"localstack_info,omitempty"`
ErrorCode string `json:"error_code,omitempty"`
ErrorMsg string `json:"error_msg,omitempty"`
}
LifecycleEvent is the payload for an lstk_lifecycle telemetry event.
type LocalStackInfo ¶ added in v0.5.2
type LocalStackInfo struct {
Version string `json:"version"`
Edition string `json:"edition"`
IsLicenseActivated bool `json:"is_license_activated"`
SessionID string `json:"session_id"`
MachineID string `json:"machine_id"`
System string `json:"system"`
IsDocker bool `json:"is_docker"`
ServerTimeUTC string `json:"server_time_utc"`
Uptime int `json:"uptime"`
}
LocalStackInfo mirrors the /_localstack/info response.
type Option ¶ added in v1.3.0
type Option func(*Client)
Option configures a Client built by New.
func WithSessionID ¶ added in v1.3.0
WithSessionID replaces the generated session id with a caller-supplied one (LSTK_SESSION_ID), so lstk's events join the caller's analytics session. It is internal-only and deliberately undocumented. An empty id keeps the generated one.
Source Files