Documentation
¶
Overview ¶
Package telemetry — anonymous, opt-in PostHog event emission for clawtool (ADR-014 F5, gemini's R4 pick).
Strict guarantee: never emits prompts, paths, file contents, secrets, or env values. The CLI dispatcher strips arg slices before passing to Track; we additionally allow-list the keys that can ride on a payload.
Per ADR-007 we wrap github.com/posthog/posthog-go. The client is nil-safe; passing nil to Track is a no-op so call sites don't need to gate every call.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EmitInstallOnce ¶ added in v0.22.4
EmitInstallOnce fires a `clawtool.install` event the first time it's called on a host AND the telemetry client is enabled. A marker file under $XDG_DATA_HOME/clawtool/install-emitted ensures every subsequent call is a no-op. Daemon boot is the natural place to call this — by the time `clawtool serve` runs on a fresh install we've already initialised the telemetry client and the marker can be created safely.
install_method comes from $CLAWTOOL_INSTALL_METHOD which the install.sh / brew formula / go install wrapper sets at install time. Empty / unrecognised falls through to "unknown" so we still get the event, just without source attribution.
The marker write happens BEFORE the Track call so a posthog outage can't cause repeated events on each retry. Worst case: we lose one install event entirely. Better than counting a single install ten times because the network was flaky.
func SetDebug ¶ added in v0.22.34
func SetDebug(on bool)
SetDebug toggles the debug trace at runtime. Wired from `clawtool serve --debug` so the operator can flip it without touching env.
func SilentDisabled ¶
func SilentDisabled() bool
SilentDisabled tells callers whether the env var explicitly disables telemetry regardless of config (for the "kill switch" use case operators want before talking on conference Wi-Fi).
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps a PostHog client + the per-host anonymous distinct ID. Nil-safe: `(*Client)(nil).Track(...)` is a clean no-op.
func New ¶
func New(cfg config.TelemetryConfig) *Client
New initialises the client when telemetry is enabled. Disabled config returns a nil-friendly client (Track is a no-op). Init failures degrade silently — telemetry is never load-bearing.
API key precedence: cfg.APIKey > cogitavePostHogKey baked-in default. Same for host. Operator-provided values always win so a self-hosted PostHog instance can capture the data instead of the shared cogitave project.
func (*Client) Enabled ¶
Enabled reports whether the client will actually emit. Useful for hot-path skips on expensive payload construction.
func (*Client) Track ¶
Track emits one event. Properties outside the allow-list are silently dropped. Safe to call on a nil receiver.
The c.client nil-check happens under c.mu so a Track racing a Close (which sets c.client = nil) can't dereference a nil posthog.Client. Pre-fix this checked nil OUTSIDE the lock then called Enqueue inside the lock — a Close that won the lock-race nil'd the field, and the next Track passed the outside-check only to nil-deref under the lock.
Source Files