Analytics :: tilegroxy Docs

Overview

This is useful for seeing which layers are actually consumed, attributing usage to tenants or users, or tracking consumption of a metered upstream provider. This differs from telemetry, which aggregates counters for operating the service rather than recording individual events.

An event is produced only when a tile is successfully served over HTTP. Failed requests and requests generated by the seed command, test command, or health checks produce no events. A layer rendered indirectly through the ref provider isn’t recorded separately, only the layer that was requested.

A cache hit does produce an event.

Individual layers can be excluded using the skipAnalytics parameter, see Layer.

Events are recorded asynchronously in batches, so analytics won’t add latency. If the write buffer clogs and gets full, events are dropped by default. There’s a batch.onFull config you can set to block if you would rather tile requests start hanging to try to avoid losing events. Buffered events are flushed on shutdown and upon hot reload. A regular shutdown shouldn’t lose any events, but a kill or server crash will certainly (there’s no WAL). Consider crosschecking your access logs if you detect a crash and exact tile count is important.

Every module accepts the same batch parameters. A batch is written when either maxSize events have accumulated or the oldest event in the buffer reaches maxAge. Note the age of a partial batch is only checked periodically so these rules are best-effort, not exact.

Event Contents

Every event always includes the following:

Fields on every event
Field	Description
`time`	When the tile was served
`layer`	The ID of the layer as configured. When a layer uses a pattern this is the configured ID, not the name from the URL, matching how per-layer telemetry metrics are recorded
`z, x, y`	The tile coordinates
`user`	The authenticated user, or empty when the request was anonymous

The following can be included via fields:

Optional fields
Name	Description
`layername`	The layer name exactly as it appeared in the URL, which differs from the layer ID when the layer uses a pattern
`layerparams`	The placeholder values extracted from a patterned layer name, as a map
`tenantid`	The tenant identifier established during authentication, if any
`ip`	The client IP address
`useragent`	The User-Agent header
`referer`	The Referer header
`host`	The Host header
`method`	The HTTP method
`path`	The request path
`query`	The raw query string
`duration`	How long the request took, in milliseconds
`bytes`	The size of the served tile in bytes
`contenttype`	The MIME type of the served tile
`cached`	Whether the tile was served from cache rather than freshly rendered

Custom Attributes

The extraFields parameter lets you get very fancy with what info you record. You can pick an env var, request var, or header and record it under whatever name you want.

Extra field values
Value form	Description
`ctx.<key>`	A value from the request context. Includes `ip`, `path`, `method`, `host`, `query`, `query-string`, `proto` and `uri`
`hdr.<name>`	A request header. The name is canonicalized to Header-Case before lookup
`env.<name>`	An environment variable - be cautious you don’t do something stupid like record your AWS keys
anything else	Used as a literal constant, useful for tagging events with an environment or region name

For example, to track which server handled the request in question, the following gives your analytics destination a server field with your server’s hostname:

YAML
JSON

analytics:
  extraFields:
    server: env.HOSTNAME

{
  "analytics": {
    "extraFields": {
      "server": "env.HOSTNAME"
    }
  }
}

Metrics

When telemetry is enabled, analytics reports three counters:

Analytics metrics
Metric	Description
`tilegroxy.analytics.recorded`	Events successfully written to a destination
`tilegroxy.analytics.dropped`	Events discarded because a queue was full
`tilegroxy.analytics.error`	Events in batches that failed to write

A rising dropped or error count means analytics is losing data even while tiles are served normally, so it’s recommended you alert on these separately from tile metrics.