telemetry

Documentation

Overview

Package telemetry — opt-in anonymous CLI telemetry client (S65.T01 / Q07).

Two send paths exist for backward compatibility:

• Send(event, props) — legacy strict opt-in via NSELF_TELEMETRY_OPT_IN=1.
• SendEvent(eventType, metadata) — v1.1.0+ path, opt-out model via IsEnabled().

Events POST to ping.nself.org/telemetry as JSON. Network failures are silently dropped (logged at DEBUG level). The CLI never blocks: each Send call dispatches a goroutine with a 3-second context deadline.

Privacy invariant: payloads MUST NOT contain email addresses, file paths, project names, license keys, or any user-identifying string. Only anonymous IDs and categorical values are permitted.

Index

• Constants
• func IsEnabled() bool
• func IsOptedIn() bool
• func LoadOrCreateInstallID() string
• func Send(event string, props map[string]any)
• func SendEvent(eventType string, metadata map[string]any)
• func SendInstallEvent()
• func WriteStatefile(enabled bool) error

Constants

const (
	// EventCLIInstall fires on nself install completion.
	// Metadata: version, os, arch, via (brew/script/binary).
	EventCLIInstall = "cli.install"

	// EventCLIFirstInit fires on the first nself init per install-ID.
	// Metadata: version.
	EventCLIFirstInit = "cli.first_init"

	// EventCLIFirstStart fires on the first nself start per install-ID.
	// Metadata: version, services_count.
	EventCLIFirstStart = "cli.first_start"

	// EventPluginInstall fires on every nself plugin install <name>.
	// Metadata: plugin_name, plugin_version, tier (free/pro).
	EventPluginInstall = "plugin.install"

	// EventEndpointFirstHit fires on the first successful Hasura query per install-ID.
	// Metadata: version.
	EventEndpointFirstHit = "endpoint.first_hit"
)

Event catalog for the CLI telemetry client (Q07 / T01-T05).

Five anonymous events are defined. The server de-duplicates "per-install-ID" events via a UNIQUE index on (install_id, event_type) for the three "first_*" variants. The CLI sends every time; ping_api discards duplicates server-side.

All event names are snake_case strings. No PII, no paths, no free-form text.

Functions

func IsEnabled

func IsEnabled() bool

IsEnabled reports whether CLI telemetry is currently active. Priority order (highest to lowest):

1. NSELF_TELEMETRY=0 → disabled
2. NSELF_TELEMETRY_OPT_OUT=1 → disabled (legacy env var)
3. ~/.config/nself/telemetry == "false" → disabled
4. ~/.nself/config.toml telemetry enabled = false → disabled
5. Default → enabled

IsEnabled does NOT check NSELF_TELEMETRY_OPT_IN (the old strict-opt-in gate used in v1.0.9 by IsOptedIn). That gate is preserved for backward compatibility but IsEnabled is the canonical check for the v1.1.0+ telemetry client.

func IsOptedIn

func IsOptedIn() bool

IsOptedIn returns true only when NSELF_TELEMETRY_OPT_IN=1 is set. This is a strict opt-in: the absence of the variable means no telemetry.

func LoadOrCreateInstallID

func LoadOrCreateInstallID() string

LoadOrCreateInstallID returns the persistent anonymous install-ID UUID. On first call it creates ~/.config/nself/install-id with a random UUID v4. Subsequent calls return the same value. The file is never deleted by the CLI. If the home directory cannot be determined, returns an empty string.

func Send

func Send(event string, props map[string]any)

Send dispatches an anonymous telemetry event to ping.nself.org in a background goroutine. It returns immediately regardless of network conditions.

Opt-in gate: if NSELF_TELEMETRY_OPT_IN != "1" this function is a complete no-op. Call site opt-in check: callers SHOULD check IsOptedIn() before building props to avoid unnecessary allocations, but Send itself is always safe to call without the guard — it will no-op internally.

func SendEvent

func SendEvent(eventType string, metadata map[string]any)

SendEvent dispatches one of the T01-T05 catalog events to ping.nself.org/telemetry using the v1.1.0+ opt-out model. It is a fire-and-forget goroutine with a 3-second hard deadline. Network failures are silently dropped.

Gate: returns immediately without dispatching if IsEnabled() is false.

Privacy: metadata values MUST be categorical or numeric only — never free-form user text, file paths, license keys, or any personally-identifying data.

func SendInstallEvent

func SendInstallEvent()

SendInstallEvent posts an anonymous "install completed" event to ping_api. It dispatches in a goroutine with a 4-second deadline and returns immediately. If telemetry is disabled (IsEnabled() == false), this is a no-op.

func WriteStatefile

func WriteStatefile(enabled bool) error

WriteStatefile writes the telemetry enabled state to ~/.config/nself/telemetry. This is used by the first-run prompt and by `nself telemetry on/off`.