analytics

Documentation

Index

• Constants
• func Capture(ctx context.Context, event string, properties map[string]any)
• func CaptureError(ctx context.Context, operation string, err error, properties map[string]any)
• func CaptureWithDistinctID(ctx context.Context, distinctID string, event string, ...)
• func Configured() bool
• func Enabled() bool
• func ErrorCode(err error) string
• func HashIdentifier(value string) string
• func IdentifyGroup(ctx context.Context, group GroupIdentity)
• func IdentifyWithDistinctID(ctx context.Context, distinctID string, traits map[string]any)
• func Initialize(config Config) error
• func SetDistinctIDResolver(resolver func(ctx context.Context) string)
• func SetEnabled(state bool)
• func Shutdown()
• func StartHeartbeat(opts datadir.Options)
• func TrackMutation(ctx context.Context, name string, props map[string]any)
• func WithMetadata(ctx context.Context, metadata Metadata) context.Context
• type CodedError
• type Config
• type GroupIdentity
• type Metadata
  • func BuildMetadata(r *http.Request) Metadata
  • func MetadataFromContext(ctx context.Context) Metadata

Constants

const (

	// HeartbeatDisabledEnv disables the anonymous install heartbeat when set
	// to "true". It does not affect the consent-gated product analytics.
	HeartbeatDisabledEnv = "WHODB_HEARTBEAT_DISABLED"
)

Functions

func Capture

func Capture(ctx context.Context, event string, properties map[string]any)

Capture emits a generic analytics event using the distinct id derived from the context.

func CaptureError

func CaptureError(ctx context.Context, operation string, err error, properties map[string]any)

CaptureError emits a structured error event. The raw error message is never sent; it is mapped to a low-cardinality code via ErrorCode to avoid leaking hostnames, table names, or SQL fragments.

func CaptureWithDistinctID

func CaptureWithDistinctID(ctx context.Context, distinctID string, event string, properties map[string]any)

CaptureWithDistinctID emits an analytics event using an explicit distinct id.

func Configured

func Configured() bool

Configured reports whether a PostHog client has been configured successfully.

func Enabled

func Enabled() bool

Enabled reports whether analytics are currently active.

func ErrorCode

func ErrorCode(err error) string

ErrorCode maps raw errors into a stable low-cardinality taxonomy.

func HashIdentifier

func HashIdentifier(value string) string

HashIdentifier hashes a potentially sensitive identifier before emission.

func IdentifyGroup

func IdentifyGroup(ctx context.Context, group GroupIdentity)

IdentifyGroup creates or updates a PostHog group with safe group properties.

func IdentifyWithDistinctID

func IdentifyWithDistinctID(ctx context.Context, distinctID string, traits map[string]any)

IdentifyWithDistinctID associates user traits with a specific distinct id.

func Initialize

func Initialize(config Config) error

Initialize prepares the global PostHog client. It is safe to invoke multiple times.

func SetDistinctIDResolver

func SetDistinctIDResolver(resolver func(ctx context.Context) string)

SetDistinctIDResolver registers a resolver consulted before request metadata when deriving the analytics distinct id. Call during startup, before the server begins handling requests.

func SetEnabled

func SetEnabled(state bool)

SetEnabled toggles whether analytics events should be emitted.

func Shutdown

func Shutdown()

Shutdown flushes events and disposes the PostHog client.

func StartHeartbeat

func StartHeartbeat(opts datadir.Options)

StartHeartbeat emits one anonymous install heartbeat immediately and then every 24 hours for the lifetime of the process. It is a no-op when WHODB_HEARTBEAT_DISABLED=true or when the PostHog client is not configured. Call once after Initialize.

func TrackMutation

func TrackMutation(ctx context.Context, name string, props map[string]any)

TrackMutation is a helper for recording GraphQL mutations executed by the user.

func WithMetadata

func WithMetadata(ctx context.Context, metadata Metadata) context.Context

WithMetadata stores metadata inside the supplied context.

Types

type CodedError

type CodedError interface {
	error
	Code() string
}

CodedError lets an error attach a stable, low-cardinality analytics code at its construction site, bypassing ErrorCode's substring heuristics. Keeps this package free of edition-specific imports — EE (or CE) code that owns a typed/sentinel error can implement this to classify precisely.

type Config

type Config struct {
	APIKey      string
	Host        string
	Environment string
	AppVersion  string
	Deployment  string
	// Edition is the build edition ("ce" or "ee"). Callers must set it so
	// every event carries a non-null build_edition property.
	Edition string
	// Source identifies the emitting process ("backend", "cli", or "desktop")
	// and is stamped on every event as the source property.
	Source string
	// SuppressClientLogs disables PostHog background logger output. Useful for
	// short-lived CLIs where network failures should stay silent.
	SuppressClientLogs bool
}

Config contains runtime configuration for the PostHog client.

type GroupIdentity

type GroupIdentity struct {
	Type       string
	Key        string
	Properties map[string]any
}

GroupIdentity describes a PostHog group and its safe group properties.

type Metadata

type Metadata struct {
	DistinctID string
	Domain     string
	Path       string
	Method     string
	UserAgent  string
	Referer    string
	RequestID  string
}

Metadata stores request-scoped attributes that are useful for analytics enrichment.

func BuildMetadata

func BuildMetadata(r *http.Request) Metadata

BuildMetadata constructs request metadata from an HTTP request.

func MetadataFromContext

func MetadataFromContext(ctx context.Context) Metadata

MetadataFromContext extracts analytics metadata from the context.