telemetry

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 New(endpoint string, disabled bool) *Client
  • func NewWithInProcessFlush(endpoint string) *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, command string, flags []string, durationMS int64, ...)
  • func (c *Client) EmitEmulatorLifecycleEvent(ctx context.Context, event LifecycleEvent)
  • func (c *Client) GetEnvironment(ctx context.Context) Environment
  • func (c *Client) SessionID() string
  • func (c *Client) SetAuthToken(token string)
• type CommandEvent
• type CommandParameters
• type CommandResult
• type Environment
• type LifecycleEvent
• type LocalStackInfo

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.

Functions

func LoadOrCreateMachineID

func LoadOrCreateMachineID(ctx context.Context) string

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.

func RunFlush

func RunFlush(ctx context.Context, endpoint string, in io.Reader) error

RunFlush reads JSON-line eventBody values from `in` and POSTs each one to `endpoint`. It runs in the detached subprocess, bounded by flushTimeout.

func ToMap

func ToMap(v any) map[string]any

ToMap converts a telemetry event struct to a map[string]any for use with Emit.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func New

func New(endpoint string, disabled bool) *Client

func NewWithInProcessFlush

func NewWithInProcessFlush(endpoint string) *Client

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) Emit

func (c *Client) Emit(ctx context.Context, name string, payload map[string]any)

func (*Client) EmitCommand

func (c *Client) EmitCommand(ctx context.Context, command string, flags []string, durationMS int64, exitCode int, errorMsg string)

EmitCommand emits an lstk_command telemetry event. The Environment block is populated automatically from the client state.

func (*Client) EmitEmulatorLifecycleEvent

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

func (c *Client) GetEnvironment(ctx context.Context) Environment

GetEnvironment returns the common environment payload for telemetry events, using the auth token set via SetAuthToken.

func (*Client) SessionID

func (c *Client) SessionID() string

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

func (c *Client) SetAuthToken(token string)

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

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

type CommandParameters struct {
	Command string   `json:"command"`
	Flags   []string `json:"flags"`
}

CommandParameters holds the command name and set flags.

type CommandResult

type CommandResult struct {
	DurationMS int64  `json:"duration_ms"`
	ExitCode   int    `json:"exit_code"`
	ErrorMsg   string `json:"error_msg,omitempty"`
}

CommandResult holds the outcome of a command invocation.

type Environment

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

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

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.