Documentation
¶
Overview ¶
Package multisource fans analytics events out to one reporter per named source.
It is not itself a vendor integration, and it is not an analytics.EventReporter: every method takes a source name first — TrackEvent, AddUser, TrackAnonymousEvent — and dispatches to the reporter configured for it. A mobile app, a web front end, and a server-side job can therefore report through one object while each lands in its own destination.
What choosing it commits a caller to ¶
The map is fixed at construction and never mutated, so sources are a deployment decision rather than a runtime one, and a source that was not configured is ErrUnknownSource — carrying the sorted list of sources that were, because the next question is always "then what did I configure?". The alternative, substituting a noop, lasts the life of the process: every event for that source goes nowhere and every call returns nil.
For the same reason NewMultiSourceEventReporterFromConfig fails the whole call when any one source fails to build. Partial success here is a service that runs with a hole in its analytics and no way to notice.
Every event gets a "source" property, so a destination that cannot separate sources by credential can separate them by property. That is not incidental: PostHog reporters are deduplicated by API key, so two sources naming the same key share one client, one buffer, and one circuit breaker, and the property is the only thing that tells their events apart downstream. Sources naming different keys get their own client, and with it their own credentials and breaker.
Close flushes every distinct reporter exactly once — the deduplication means two sources can be the same reporter — closes the rest even after one fails, and joins the errors. Shutdown is the same call under do.Shutdowner, so a container teardown flushes buffered events rather than dropping them.
Index ¶
- Constants
- Variables
- func RegisterMultiSourceEventReporter(i do.Injector)
- type MultiSourceEventReporter
- func (m *MultiSourceEventReporter) AddUser(ctx context.Context, source, userID string, properties map[string]any) error
- func (m *MultiSourceEventReporter) Close(ctx context.Context) error
- func (m *MultiSourceEventReporter) Shutdown(ctx context.Context) error
- func (m *MultiSourceEventReporter) TrackAnonymousEvent(ctx context.Context, source, event, anonymousID string, ...) error
- func (m *MultiSourceEventReporter) TrackEvent(ctx context.Context, source, event, userID string, properties map[string]any) error
- type Option
Constants ¶
const ( // SourcePropertyKey is the event property used to identify the analytics source (e.g. ios, web). // For PostHog, where a single API key is shared across sources, this property distinguishes events. SourcePropertyKey = "source" )
Variables ¶
var ErrUnknownSource = errors.New("no analytics reporter configured for source")
ErrUnknownSource is returned when an event names a source this reporter was not built with.
It is an error rather than a noop substitution. The substitution was permanent — every event for that source was dropped for the life of the process, and every call returned nil — which is exactly what NewMultiSourceEventReporterFromConfig refuses at construction. Nothing about dispatch makes the same mistake more forgivable.
Functions ¶
func RegisterMultiSourceEventReporter ¶
RegisterMultiSourceEventReporter registers a *MultiSourceEventReporter with the injector. Prerequisite: map[string]*analyticscfg.SourceConfig must be registered in the injector.
Types ¶
type MultiSourceEventReporter ¶
type MultiSourceEventReporter struct {
// contains filtered or unexported fields
}
MultiSourceEventReporter delegates events to per-source EventReporters. The reporters map is populated at construction and never mutated afterwards, so reads need no synchronization.
func NewMultiSourceEventReporter ¶
func NewMultiSourceEventReporter(reporters map[string]analytics.EventReporter, opts ...Option) *MultiSourceEventReporter
NewMultiSourceEventReporter returns a new MultiSourceEventReporter.
func NewMultiSourceEventReporterFromConfig ¶
func NewMultiSourceEventReporterFromConfig( ctx context.Context, proxySources map[string]*analyticscfg.SourceConfig, opts ...Option, ) (*MultiSourceEventReporter, error)
NewMultiSourceEventReporterFromConfig builds a MultiSourceEventReporter from proxy sources config. For each source, it creates an EventReporter via NewCollector. A source that fails to construct — missing credentials, an unset provider — fails the whole call rather than getting a noop of its own: that substitution outlived the mistake by the life of the process, and every event for the source went nowhere while every call returned nil.
For PostHog: reporters are deduplicated by API key. Sources sharing the same PostHog API key reuse a single client (the source name is set as a property on each event), while sources with distinct API keys each get their own client so their credentials and circuit breaker are honored.
func (*MultiSourceEventReporter) AddUser ¶
func (m *MultiSourceEventReporter) AddUser(ctx context.Context, source, userID string, properties map[string]any) error
AddUser identifies a user against the reporter for the given source, forwarding the user's traits. Every underlying reporter supports identify via analytics.EventReporter.AddUser.
func (*MultiSourceEventReporter) Close ¶
func (m *MultiSourceEventReporter) Close(ctx context.Context) error
Close flushes and closes every underlying reporter. Reporters shared across multiple sources (e.g. PostHog sources with the same API key) are closed exactly once.
func (*MultiSourceEventReporter) Shutdown ¶
func (m *MultiSourceEventReporter) Shutdown(ctx context.Context) error
Shutdown implements do.Shutdowner so the DI container flushes buffered events on shutdown, and reports a failed final flush rather than swallowing it.
func (*MultiSourceEventReporter) TrackAnonymousEvent ¶
func (m *MultiSourceEventReporter) TrackAnonymousEvent(ctx context.Context, source, event, anonymousID string, properties map[string]any) error
TrackAnonymousEvent records an event for an anonymous user.
func (*MultiSourceEventReporter) TrackEvent ¶
func (m *MultiSourceEventReporter) TrackEvent(ctx context.Context, source, event, userID string, properties map[string]any) error
TrackEvent records an event for an identified user.
type Option ¶
type Option func(*options)
Option configures the reporters 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 WithMetricsProvider ¶
WithMetricsProvider attaches a metrics provider, passed through to the per-source reporters built from config.
func WithPillars ¶
func WithPillars(p *observability.Pillars) Option
WithPillars attaches a logger, tracer provider, and metrics provider in one go, for the common case where a caller has already built them together. A nil Pillars attaches nothing.
It is applied in order with the individual options, so a caller can hand over its pillars and then override one of them.
func WithTracerProvider ¶
WithTracerProvider attaches a tracer provider, enabling spans on every event.
Source Files