Analytics

Analytics (event stream)

Beyond Prometheus counters, Goma Gateway can emit a per-request analytics event stream to Redis. Where /metrics gives you aggregate numbers, the stream carries one compact, privacy-safe event per request — enough to build full HTTP traffic, performance and web-analytics dashboards downstream.

Miabi consumes this stream to power its Workspace Analytics (traffic by country, latency percentiles, unique visitors, top pages, …). You can also consume it yourself with any Redis Streams client.

How it works

• On each proxied request Goma builds a small AnalyticsEvent and appends it to a Redis Stream (default goma:analytics) with a batched, pipelined XADD.
• Delivery is non-blocking: it never adds latency to the request path — a full in-memory buffer drops the event rather than waiting. An approximate MAXLEN cap bounds the stream so a lagging consumer can't grow Redis unbounded.
• Requires Redis to be configured (the transport). It reuses the same Redis the gateway already uses for caching / distributed rate limiting.

⚠️ Same Redis, same database. The consumer must read from the exact Redis and database index Goma writes to. If nothing appears downstream, check that GOMA_REDIS_DB matches the consumer's Redis DB — a mismatch silently breaks the pipeline.

Privacy

The stream is designed to carry no PII:

• The client IP never leaves the gateway. It is used only to (a) derive a daily-salted visitor hash (vid) for counting unique visitors and (b) look up a country via GeoIP — then it is dropped.
• No cookies are set or required.

Enabling it

Analytics is configured in goma.yml alongside the rest of the gateway:

version: 2
gateway:
  redis:
    addr: redis:6379          # required — Redis is the transport
    password: "${REDIS_PASSWORD}"
  analytics:
    enabled: true             # off by default
    stream: goma:analytics    # Redis stream key
    sample: 1                 # 0..1; 1 = every request
    maxLen: 1000000           # approximate stream length cap
    gatewayId: ""             # stamped on each event, for multi-gateway installs
  geoip:
    database: /etc/goma/country.mmdb   # optional; see GeoIP below

geoip sits beside analytics rather than inside it because three features read the same database: the country field on events, the gateway_requests_by_country_total metric, and the geoBlock middleware. It loads whether or not analytics is enabled.

Or entirely from the environment, which is equivalent:

GOMA_ANALYTICS_ENABLED=true          # off by default
GOMA_ANALYTICS_STREAM=goma:analytics # Redis stream key
GOMA_REDIS_DB=0                      # must match the consumer's Redis DB
# Optional country enrichment (see GeoIP below):
GOMA_GEOIP_DB=/etc/goma/country.mmdb

Configuration

Each setting can come from the config file or the environment. The environment wins, field by field — so a container can override what the file ships with, and an existing GOMA_ANALYTICS_* deployment keeps working unchanged after adding the analytics: block.

gateway.analytics	Environment	Default	Description
enabled	GOMA_ANALYTICS_ENABLED	false	Emit the event stream.
stream	GOMA_ANALYTICS_STREAM	goma:analytics	Redis stream key events are appended to.
sample	GOMA_ANALYTICS_SAMPLE	1	Sampling rate 0..1; e.g. 0.25 records ~25% of requests. 1 = every request.
maxLen	GOMA_ANALYTICS_MAXLEN	1000000	Approximate stream length cap (XADD MAXLEN ~).
gatewayId	GOMA_GATEWAY_ID	""	Identifier stamped on each event (gw); useful with multiple gateways.

Alongside it, at gateway level:

gateway	Environment	Default	Description
geoip.database	GOMA_GEOIP_DB	(well-known paths)	Path to the GeoIP .mmdb for the country field.
—	GOMA_REDIS_DB	0	Redis database index (must match the consumer).

A malformed GOMA_ANALYTICS_SAMPLE or GOMA_ANALYTICS_MAXLEN is logged and ignored, falling back to the configured value — a typo must not silently drop your sampling rate or uncap the stream.

Event schema

Each stream entry has a single field e whose value is the JSON below.

Field	Type	Description
ts	int	Event time, unix milliseconds.
gw	string	Gateway id (GOMA_GATEWAY_ID).
name	string	Matched route name.
host	string	Request Host.
method	string	HTTP method.
status	int	Response status code.
path	string	Request path.
path_template	string	Matched route path pattern.
req_bytes	int	Request body bytes received.
resp_bytes	int	Response body bytes sent.
duration_ms	int	Total request duration.
upstream_ms	int	Upstream/backend duration (overhead = duration_ms − upstream_ms).
vid	string	Daily-salted visitor hash (not the IP).
country	string	ISO country code from GeoIP (empty when no database).
ua	string	Raw User-Agent (parsed into browser/OS/device downstream).
referer_host	string	Host of the Referer, if any.

GeoIP (country enrichment)

Save a country-level .mmdb database at /etc/goma/country.mmdb and Goma loads it at startup with no configuration; geoip.database (or GOMA_GEOIP_DB) overrides the path. MaxMind, DB-IP and IP2Location all publish a suitable database — any of them works, since all three expose a country ISO code.

An explicitly configured path is used exactly as given: Goma will not quietly fall back to a well-known location, because enriching events from a database nobody chose is worse than no country data at all.

It enriches the country field on events, the gateway_requests_by_country_total metric, and powers the geoBlock middleware. Everything keeps working without it — you just lose the country dimension.

Goma ships no database: the ones worth having carry licenses that bind whoever uses or displays the data, which is a choice only you can make for your deployment.