Documentation
¶
Overview ¶
Package posthog reports analytics events to PostHog.
Choosing it commits a deployment to a PostHog project API key and, unless Config.Endpoint names EU Cloud or a self-hosted instance, to PostHog US Cloud.
A nil error means buffered, not delivered ¶
AddUser, EventOccurred, and EventOccurredAnonymous hand the event to the PostHog client's in-memory buffer and return. Nothing about the return value describes what happened on the network, because at that point nothing has: a background flush delivers later, and the only report of a delivery that failed is the error counter and the log line this package records from the client's Failure callback. That line names the event and its UUID and deliberately omits its properties, which are the caller's data rather than this service's.
Two things follow. Close is the final flush and its error is the last chance anyone has to learn that buffered events did not arrive, so a process that exits without calling it drops whatever was still in the buffer, silently. And the circuit breaker is driven from those delivery callbacks rather than from the enqueue, so it tracks whether PostHog is accepting events rather than whether the buffer accepted them.
The breaker is a required constructor argument rather than an option: while it is open, every call returns circuitbreaking.ErrCircuitBroken without enqueueing. Nothing here retries.
Compared with the segment sibling ¶
WithConfigModifiers reaches the underlying posthog.Config before the client is built, which is how a caller changes anything this package's own Config does not name — including the delivery callback, in which case the breaker is no longer wired to delivery outcomes. The segment implementation has no such escape hatch and no endpoint setting at all.
Index ¶
- Variables
- type Config
- type EventReporter
- func (c *EventReporter) AddUser(ctx context.Context, userID string, properties map[string]any) error
- func (c *EventReporter) Close(ctx context.Context) error
- func (c *EventReporter) EventOccurred(ctx context.Context, event, userID string, properties map[string]any) error
- func (c *EventReporter) EventOccurredAnonymous(ctx context.Context, event, anonymousID string, properties map[string]any) error
- type Option
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmptyAPIToken indicates an empty API token was provided. ErrEmptyAPIToken = platformerrors.New("empty Posthog API token") )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
APIKey string `env:"API_KEY" json:"apiKey,omitempty" yaml:"apiKey,omitempty"`
// Endpoint is the PostHog ingestion host. Leave empty for PostHog US Cloud
// (the default); set it for EU Cloud (https://eu.posthog.com) or a self-hosted
// instance.
Endpoint string `env:"ENDPOINT" json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
}
type EventReporter ¶
type EventReporter struct {
// contains filtered or unexported fields
}
EventReporter is the PostHog analytics.EventReporter implementation. It is exported, and returned by NewEventReporter, so a caller who has chosen PostHog can depend on that choice rather than on the interface every reporter shares.
func NewEventReporter ¶
func NewEventReporter(apiKey string, circuitBreaker circuitbreaking.CircuitBreaker, opts ...Option) (*EventReporter, error)
NewEventReporter returns a new PostHog-backed EventReporter.
func (*EventReporter) AddUser ¶
func (c *EventReporter) AddUser(ctx context.Context, userID string, properties map[string]any) error
AddUser upsert's a user's identity.
func (*EventReporter) Close ¶
func (c *EventReporter) Close(ctx context.Context) error
Close wraps the internal client's Close method.
func (*EventReporter) EventOccurred ¶
func (c *EventReporter) EventOccurred(ctx context.Context, event, userID string, properties map[string]any) error
EventOccurred associates events with a user.
func (*EventReporter) EventOccurredAnonymous ¶
func (c *EventReporter) EventOccurredAnonymous(ctx context.Context, event, anonymousID string, properties map[string]any) error
EventOccurredAnonymous records an event for an anonymous user.
type Option ¶
type Option func(*options)
Option configures the EventReporter this package constructs. The zero configuration works: an absent logger logs nowhere, an absent tracer provider traces nowhere, and an absent metrics provider records nothing.
func WithConfigModifiers ¶
WithConfigModifiers appends functions that mutate the PostHog client config before the client is built. Modifiers accumulate across repeated uses of this option and run in the order provided.
func WithMetricsProvider ¶
WithMetricsProvider attaches a metrics provider.
func WithTracerProvider ¶
WithTracerProvider attaches a tracer provider, enabling spans on every event.
Source Files