analytics

Documentation

Overview

Package analytics emits product-analytics events to PostHog.

This is distinct from the OTLP log export in internal/cliboot: that ships slog records to PostHog Logs, this captures discrete product events (provision, deprovision, password reset, query lifecycle) via the PostHog capture API. Both are gated on the same POSTHOG_API_KEY.

Events are attributed to an org using PostHog group analytics: the distinct_id is the org name and the event carries a group of type "organization". This lets dashboards break down and aggregate by org.

The default tracker is a no-op until SetDefault installs a real one (done by cliboot.InitAnalytics at startup when POSTHOG_API_KEY is set), so call sites can unconditionally call analytics.Default().Capture(...).

Index

• Constants
• func SetDefault(t Tracker)
• type Tracker
  • func Default() Tracker
  • func NewPostHogTracker(apiKey, host string) (Tracker, error)

Constants

const GroupTypeOrg = "organization"

GroupTypeOrg is the PostHog group type used to attribute events to an org.

Functions

func SetDefault

func SetDefault(t Tracker)

SetDefault installs the global Tracker. Passing nil installs a no-op tracker.

Types

type Tracker

type Tracker interface {
	// Capture records an event. orgID attributes the event to an org via group
	// analytics; an empty orgID falls back to a non-org distinct_id and omits
	// the group (e.g. standalone single-tenant mode). props may be nil.
	Capture(event, orgID string, props map[string]any)
	// Close flushes any buffered events. Safe to call multiple times.
	Close()
}

Tracker captures product-analytics events. Implementations must be safe for concurrent use and non-blocking: the query path calls Capture on every query, so an implementation must never block on network I/O in Capture.

func Default

func Default() Tracker

Default returns the installed Tracker, or a no-op tracker if none is set.

func NewPostHogTracker

func NewPostHogTracker(apiKey, host string) (Tracker, error)

NewPostHogTracker constructs a Tracker backed by a real PostHog client. host may be a bare host (e.g. "us.i.posthog.com") or a full URL; a bare host is upgraded to https. Returns an error if the client cannot be created.