analytics

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Overview

Package analytics contains the modules that record tile usage events, selected by the "name" parameter

Index

Constants

View Source
const (
	// The default, since delaying tile responses is worse than losing usage data
	OnFullDrop = "drop"
	// Applies backpressure to the request goroutine
	OnFullBlock = "block"
)
View Source
const (
	FieldLayerName   = "layername"
	FieldLayerParams = "layerparams"
	FieldTenantID    = "tenantid"
	FieldIP          = "ip"
	FieldUserAgent   = "useragent"
	FieldReferer     = "referer"
	FieldHost        = "host"
	FieldMethod      = "method"
	FieldPath        = "path"
	FieldQuery       = "query"
	FieldDuration    = "duration"
	FieldBytes       = "bytes"
	FieldContentType = "contenttype"
	FieldCached      = "cached"
)

Anything outside this set is rejected at startup so a typo doesn't silently produce a column of nulls

View Source
const (
	ColumnTime      = "time"
	ColumnLayer     = "layer"
	ColumnZ         = "z"
	ColumnX         = "x"
	ColumnY         = "y"
	ColumnUser      = "user_id"
	ColumnExtra     = "extra"
	ColumnLayerName = "layer_name"
)

Default names for columns holding the always-present event members. Each can be overridden to match an existing table

Variables

Functions

This section is empty.

Types

type AnalyticsWrapper added in v0.13.0

type AnalyticsWrapper struct {
	Name      string
	ID        string // Identifies this destination in logs. Defaults to the module name
	Analytics analytics.Analytics
	// contains filtered or unexported fields
}

Unlike the cache and provider wrappers, also absorbs errors since a broken analytics destination must never degrade tile serving

func ConstructAnalytics added in v0.13.0

func ConstructAnalytics(ctx context.Context, rawConfig map[string]interface{}, secreter secret.Secreter, deps analytics.AnalyticsDeps) (*AnalyticsWrapper, error)

secreter is separate from deps because it resolves the raw config before the module is constructed

func (*AnalyticsWrapper) Close added in v0.13.0

func (w *AnalyticsWrapper) Close(ctx context.Context) error

Lets batched events flush on shutdown and hot reload

func (*AnalyticsWrapper) Empty added in v0.13.0

func (w *AnalyticsWrapper) Empty() bool

Lets the handler skip building an Event. True for the nil wrapper and the noop module

func (*AnalyticsWrapper) Record added in v0.13.0

func (w *AnalyticsWrapper) Record(ctx context.Context, event analytics.Event) error

func (*AnalyticsWrapper) RecordEvent added in v0.13.0

func (w *AnalyticsWrapper) RecordEvent(ctx context.Context, event analytics.Event, src FieldSource)

Separate from Record so callers don't need to know how fields are sourced

type BatchConfig added in v0.13.0

type BatchConfig struct {
	// Flush once this many events have accumulated
	MaxSize uint
	// Seconds before a partial batch flushes, so low-traffic layers still report promptly
	MaxAge uint
	// Capacity of the queue between the request path and the flush workers
	QueueSize uint
	// Concurrent flushes
	Workers uint
	// "drop" or "block"
	OnFull string
}

func ApplyBatchDefaults added in v0.13.0

func ApplyBatchDefaults(cfg BatchConfig, errorMessages config.ErrorMessages) (BatchConfig, error)

Fills in unset values and validates, so every module reports the same defaults and errors

type Batcher added in v0.13.0

type Batcher struct {
	// contains filtered or unexported fields
}

Decouples recording an event from writing it. Add runs on the request path while a worker pool does the I/O

func NewBatcher added in v0.13.0

func NewBatcher(id string, cfg BatchConfig, flush FlushFunc) (*Batcher, error)

func (*Batcher) Add added in v0.13.0

func (b *Batcher) Add(ctx context.Context, event analytics.Event) error

Never blocks under OnFullDrop. Under OnFullBlock, waits for space or context cancellation

func (*Batcher) Close added in v0.13.0

func (b *Batcher) Close(ctx context.Context) error

Stops accepting events, drains the queue and does a final flush. Returns when workers finish or ctx is cancelled

type Clickhouse

type Clickhouse struct {
	ClickhouseConfig
	// contains filtered or unexported fields
}

func (*Clickhouse) Close

func (c *Clickhouse) Close(ctx context.Context) error

func (*Clickhouse) Record

func (c *Clickhouse) Record(ctx context.Context, event analytics.Event) error

type ClickhouseConfig

type ClickhouseConfig struct {
	CommonConfig `mapstructure:",squash"`
	// ID of a datastore named "clickhouse"
	Datastore string
	// Never created by tilegroxy. See the docs for the recommended DDL
	Table string
	// Column name overrides keyed by logical field name
	Columns map[string]string
}

type ClickhouseRegistration

type ClickhouseRegistration struct {
}

func (ClickhouseRegistration) Initialize

func (ClickhouseRegistration) InitializeConfig

func (s ClickhouseRegistration) InitializeConfig() any

func (ClickhouseRegistration) Name

func (s ClickhouseRegistration) Name() string

type CommonConfig added in v0.13.0

type CommonConfig struct {
	// Attributes analytics log messages. Defaults to the module name
	ID string
	// From the set in event_fields.go. Unknown names fail at startup so `tilegroxy config check` catches them
	Fields []string
	// Keys are attribute names. Values select a source via a `ctx.` or `hdr.` prefix, otherwise they're literal
	ExtraFields map[string]string
	Batch       BatchConfig
}

Accepted by every module. Embedded with `mapstructure:",squash"` so these keys sit at the top of the module config

type Custom

type Custom struct {
	CustomConfig
	// contains filtered or unexported fields
}

func (*Custom) Close

func (c *Custom) Close(ctx context.Context) error

The script's close function is optional so older scripts keep working

func (*Custom) Record

func (c *Custom) Record(ctx context.Context, event analytics.Event) error

type CustomConfig

type CustomConfig struct {
	CommonConfig `mapstructure:",squash"`
	// Path to a file with the go code that records events
	File string
	// Inline go code that records events
	Script string
	// Passed through to the script
	Params map[string]interface{} `mapstructure:",remain"`
}

type CustomRegistration

type CustomRegistration struct {
}

func (CustomRegistration) Initialize

func (s CustomRegistration) Initialize(cfgAny any, deps analytics.AnalyticsDeps) (analytics.Analytics, error)

func (CustomRegistration) InitializeConfig

func (s CustomRegistration) InitializeConfig() any

func (CustomRegistration) Name

func (s CustomRegistration) Name() string

type FieldSource added in v0.13.0

type FieldSource struct {
	// Exactly as it appeared in the URL
	LayerName   string
	Bytes       int
	ContentType string
}

Request-scoped values unavailable from the context alone. Populated by the tile handler on success

type FlushFunc added in v0.13.0

type FlushFunc func(ctx context.Context, events []analytics.Event) error

Called from a worker goroutine, one call at a time per worker, and may block

type GoogleAnalytics

type GoogleAnalytics struct {
	GoogleAnalyticsConfig
	// contains filtered or unexported fields
}

func (*GoogleAnalytics) Close

func (g *GoogleAnalytics) Close(ctx context.Context) error

func (*GoogleAnalytics) Record

func (g *GoogleAnalytics) Record(ctx context.Context, event analytics.Event) error

type GoogleAnalyticsConfig

type GoogleAnalyticsConfig struct {
	CommonConfig `mapstructure:",squash"`
	// In the form G-XXXXXXX
	MeasurementID string
	// Expected to be supplied via env. or secret.
	APISecret string
	EventName string
	// Point this at /debug/mp/collect to validate payloads
	Endpoint string
	// Seconds
	Timeout   uint
	UserAgent string
}

type GoogleAnalyticsRegistration

type GoogleAnalyticsRegistration struct {
}

func (GoogleAnalyticsRegistration) Initialize

func (GoogleAnalyticsRegistration) InitializeConfig

func (s GoogleAnalyticsRegistration) InitializeConfig() any

func (GoogleAnalyticsRegistration) Name

type Noop

type Noop struct {
	NoopConfig
}

func (Noop) Record

func (c Noop) Record(_ context.Context, _ analytics.Event) error

type NoopConfig

type NoopConfig struct {
	CommonConfig `mapstructure:",squash"`
}

type NoopRegistration

type NoopRegistration struct {
}

func (NoopRegistration) Initialize

func (NoopRegistration) InitializeConfig

func (s NoopRegistration) InitializeConfig() any

func (NoopRegistration) Name

func (s NoopRegistration) Name() string

type Postgres

type Postgres struct {
	PostgresConfig
	// contains filtered or unexported fields
}

func (*Postgres) Close

func (p *Postgres) Close(ctx context.Context) error

func (*Postgres) Record

func (p *Postgres) Record(ctx context.Context, event analytics.Event) error

type PostgresConfig

type PostgresConfig struct {
	CommonConfig `mapstructure:",squash"`
	// ID of a datastore named "postgresql"
	Datastore string
	// Never created by tilegroxy. See the docs for the recommended DDL
	Table string
	// Column name overrides keyed by logical field name
	Columns map[string]string
}

type PostgresLegacyRegistration added in v0.11.0

type PostgresLegacyRegistration struct {
	PostgresRegistration
}

Deprecated "postgres" alias for PostgresRegistration

func (PostgresLegacyRegistration) Initialize added in v0.13.0

func (PostgresLegacyRegistration) Name added in v0.11.0

type PostgresRegistration

type PostgresRegistration struct {
}

func (PostgresRegistration) Initialize

func (PostgresRegistration) InitializeConfig

func (s PostgresRegistration) InitializeConfig() any

func (PostgresRegistration) Name

func (s PostgresRegistration) Name() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL