telemetry

Documentation

Overview

Package telemetry defines structured diagnostic events and the redaction boundary that keeps them private. The boundary is the type system itself: the Event struct has no field that can hold raw pane content, prompts, secrets, or environment — only counts, classes, booleans, and hashes. Accidental content capture is therefore a compile error, not a runtime hope.

Privacy posture (per the directive):

• Telemetry is opt-in. This version ships NO network sink at all, so there is no egress to leak; the event struct, redaction boundary, previewer, and kill switches all exist so a future sink is a small, auditable addition.
• Strictly local diagnostic logging (under --debug) is the only thing that writes anything, and only to a local file.
• MUXRAY_NO_TELEMETRY / DO_NOT_TRACK / config hard-disable everything.
• All telemetry operations are non-fatal.

Index

• func DebugLogPath() string
• func ExternalEnabled() bool
• func Fingerprint(clean string) string
• func KillSwitch() bool
• func Record(e Event, debug bool)
• func Show(e Event) string
• type Event

Functions

func DebugLogPath

func DebugLogPath() string

DebugLogPath returns the path of the local debug log.

func ExternalEnabled

func ExternalEnabled() bool

ExternalEnabled reports whether external (network) telemetry would be emitted if a sink existed. It requires explicit opt-in via config and is overridden by the kill switch. This version has no sink, so this only informs `telemetry show`.

func Fingerprint

func Fingerprint(clean string) string

Fingerprint returns a short, irreversible hash of cleaned text — a stable identifier for "the same screen" that carries none of the content.

func KillSwitch

func KillSwitch() bool

KillSwitch reports whether telemetry is hard-disabled by environment. A hard disable suppresses even the local debug log.

func Record

func Record(e Event, debug bool)

Record writes the event to a local debug log when debug logging is on. It never performs network I/O in this version and never panics — telemetry must not affect the critical path.

func Show

func Show(e Event) string

Show renders the event exactly as it would be recorded/sent. Because the sink (future) reuses this same Event, the preview equals the payload by construction.

Types

type Event

type Event struct {
	MuxrayVersion      string  `json:"muxray_version"`
	OS                 string  `json:"os"`
	Arch               string  `json:"arch"`
	TmuxVersion        string  `json:"tmux_version,omitempty"`
	Command            string  `json:"command"`
	DurationMS         int64   `json:"duration_ms"`
	Success            bool    `json:"success"`
	ErrorClass         string  `json:"error_class,omitempty"`
	Program            string  `json:"program,omitempty"`
	Status             string  `json:"status,omitempty"`
	RuleID             string  `json:"rule_id,omitempty"`
	Confidence         float64 `json:"confidence,omitempty"`
	ANSINormalized     bool    `json:"ansi_normalized"`
	LineCount          int     `json:"line_count"`
	CharCount          int     `json:"char_count"`
	Truncated          bool    `json:"truncated"`
	DiffChanged        *bool   `json:"diff_changed,omitempty"`
	DiffHunks          int     `json:"diff_hunks,omitempty"`
	SnapshotReadOK     *bool   `json:"snapshot_read_ok,omitempty"`
	SnapshotWriteOK    *bool   `json:"snapshot_write_ok,omitempty"`
	Harness            string  `json:"harness,omitempty"`
	ContentFingerprint string  `json:"content_fingerprint,omitempty"`
	InvocationID       string  `json:"invocation_id"`
}

Event is a single invocation's diagnostic record. Every field is a safe, low-cardinality, content-free signal. There is intentionally no field for raw text, prompts, completions, file contents, or environment variables.