RUM Receiver

Plugin: dem.plugin Module: receiver

Overview

Monitor the availability and HTTP request outcomes of the browser telemetry receiver.

Netdata accepts browser telemetry over HTTP or HTTPS and routes each request to its configured site. One receiver serves all sites; a receiver outage creates measurement gaps while site jobs remain available.

This collector is only supported on the following platforms:

• Linux
• macOS

This collector only supports collecting metrics from a single instance of this integration.

The Netdata service needs write access to its DEM state directory. Configured TLS and GeoIP files must be readable by the Netdata service account.

Default Behavior

Auto-Detection

The stock receiver starts on loopback. Sites require explicit configuration.

Limits

Browser payloads and request rates are limited by receiver settings.

Performance Impact

Resource usage depends on accepted browser traffic and the configured measurement window. Optional OTLP export and investigation history add network and local disk work.

Setup

Prerequisites

Install the DEM plugin

DEM is experimental and opt-in. Build Netdata with -DENABLE_PLUGIN_DEM=ON, or use --enable-plugin-dem with the source installer. Install the resulting DEM plugin package.

Expose the receiver

Expose the listener through an HTTPS reverse proxy before sending traffic from remote websites. Set public_url and restrict trusted_proxies to that proxy. The default listener is local to this host.

Provision optional geography data

Geography is optional. Provision an MMDB readable by the Netdata service account through Agent packaging, the topology IP intelligence downloader, or your own database update process. Some installations package these files with NetFlow; they are not present in every installation, and DEM does not require a running NetFlow plugin or download databases itself.

Supported database types are Netdata-Topology-GEO, GeoLite2-City, GeoLite2-Country, GeoIP2-City, GeoIP2-Country, DBIP-City-Lite and DBIP-Country-Lite. ASN and other database types are rejected. A country database supplies countries without city coordinates; an accepted type does not guarantee coverage for an address.

Publish updates by writing a separate complete file and atomically renaming it over the destination. Do not truncate or overwrite the active file: atomic replacement is required for consistent lookups. Check collector.geoip in rum-sites after provisioning.

Configuration

Options

Options apply to the canonical receiver.

Configuration options

Group	Option	Description	Default	Required
Connection	listen	Address and port that accept browser telemetry. The default accepts connections from this host only.	127.0.0.1:19938	no
	public_url	Public receiver base URL used to generate installation snippets. If neither receiver nor site sets a public URL, no snippet is offered.		no
	tls_cert	Server certificate file. Leave empty with TLS key to serve HTTP.		no
	tls_key	Server private key file. Set together with TLS certificate to serve HTTPS.		no
	trusted_proxies	Proxy IP addresses or CIDR ranges allowed to supply forwarded client addresses. Leave empty to distrust forwarded headers.		no
Limits	max_body_bytes	Maximum accepted browser payload size, in bytes. Larger requests are rejected.	262144	no
	rate_limit	Limits for browser telemetry requests.		no
	rate_limit.per_ip_per_min	Maximum requests per client IP per minute.	120	no
	rate_limit.per_site_per_sec	Maximum requests per site per second.	500	no
Collection	update_every	Data collection interval, in seconds.	10	no
	geoip_db	Geographic MMDB file; an explicit path uses only that file. Leave empty to try the Agent cache and then stock IP intelligence database; unavailable geography does not stop collection.		no

geoip_db

With an empty path, DEM tries topology-ip-intel/topology-ip-geo.mmdb under the Agent cache directory, then under its stock data directory. A rejected cache file does not hide an accepted stock file. An explicit path disables this automatic fallback. Sources are checked when the receiver starts and every 60 seconds, so a later provision or atomic replacement is adopted without restarting the receiver.

via File

The configuration file name for this integration is dem/receiver.conf.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config dem/receiver.conf

Examples

Local receiver

Minimal native configuration.

Examples

jobs:
  - name: receiver
    listen: 127.0.0.1:19938

Alerts

There are no alerts configured by default for this integration.

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

The availability state distinguishes an unavailable receiver from measured request outcomes.

Per receiver

One configured receiver; breakdowns appear when matching observations are available.

This scope has no labels.

Metrics:

Metric	Description	Dimensions	Unit
dem_receiver.state	RUM receiver availability	serving, unavailable	state
dem_receiver.requests	RUM HTTP requests	success, client_errors, server_errors	requests/s

Troubleshooting

Known Errors

Missing or unexpected geography

Cause

A site's capture policy can disable geography or limit it to country. The selected database may be unavailable, lack a matching address or field, or contain a record that cannot be decoded.

Fix

Check the site's capture.geolocation and collector.geoip in rum-sites. loaded means a supported declared database type and available reader, not full record validation, freshness, accuracy or coverage. using_previous means current candidates failed and a previous usable snapshot remains; confirmed source removal revokes it. unavailable does not stop browser collection.

Use reason and the local Agent logs to identify source failures. Make a supported MMDB readable by the Netdata service account, then publish it by atomic rename. A snapshot with a detected mapped-memory fault is never reused. lookup_errors counts errors for the active source generation, not unmatched addresses or missing fields. Refresh and fault changes are published by the receiver worker; lookup counts update at the receiver collection interval.

Other Problems

No browser measurements

Check the serving state in rum-sites, the configured public URL and the site allowed origins. In the website browser, follow the script and SDK requests through the collect POST. Last accepted payload and rejected-origin timestamps are observations; silence alone does not prove failure.