RUM Receiver
Plugin: dem.plugin Module: receiver
Overview
Monitor the endpoint that receives browser reports for Real User Monitoring: whether it serves and how its requests end.
The RUM receiver is the HTTP listener that websites load the RUM script from and send their visitors' reports to. One receiver serves every RUM site on the Agent, and its charts show:
- Whether the receiver is serving.
- Requests per second that succeed, are refused (client errors, such as a refused origin, a rate limit or an unknown site) or fail on the server side.
The receiver starts with the DEM plugin and listens on 127.0.0.1:19938 by default, so only this host can
reach it. To accept reports from visitors, put an HTTPS reverse proxy in front of it, or give it a TLS
certificate and a public address. It serves the RUM script and the Grafana Faro
Web SDK under /rum/, accepts each site's reports at /rum/ followed by the site key and /collect, and
contacts no external service.
The visitor's IP address is taken from the connection, or from the X-Forwarded-For or X-Real-IP header
when the connection comes from a trusted proxy. It is used for the rate limits and to look up the visitor's
location in a local database, and is not stored.
This collector is only supported on the following platforms:
- Linux
This collector only supports collecting metrics from a single instance of this integration.
| Permission | Needed when |
|---|---|
The Netdata service account (usually netdata) can read tls_cert and tls_key. | The receiver serves HTTPS itself. |
| The Netdata service account can read the location database. | geoip_db is set, or the Agent provides a database. |
RUM Receiver can be monitored further using the following other integrations:
Default Behavior
Auto-Detection
The receiver starts with the stock dem/receiver.conf, listening on 127.0.0.1:19938. It receives nothing
until a RUM site is configured and its script is on a website.
Limits
- One receiver serves every RUM site on the Agent, and its settings apply to all of them.
- Each visitor IP address can send 120 requests per minute and each site 500 per second (
rate_limit); requests beyond that get HTTP 429. - Reports larger than 256 KiB get HTTP 413 (
max_body_bytes). - Visitors arriving from loopback or private addresses get no location.
Performance Impact
The receiver parses and decodes every report, so its CPU use grows with the number of reports per second. In
Netdata's tests, receiving 1,000 reports per second took about a quarter of a CPU core. On busy websites,
lower measure_sample_rate in the RUM site jobs to receive fewer reports.
Setup
Prerequisites
Make the receiver reachable over HTTPS
Visitors' browsers must reach the receiver at a public HTTPS address; browsers do not let HTTPS pages send
reports to plain HTTP. The usual setup keeps the default listen and adds the /rum/ path to an HTTPS
reverse proxy on the same host. For NGINX:
location /rum/ {
proxy_pass http://127.0.0.1:19938;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
Forward every path under /rum/, not only the script. Then set public_url to the proxy's public
address and trusted_proxies to the address the proxy connects from (see the first example).
If several Agents answer for the same public address, run the same Agent version on all of them: a page loads its SDK files from whichever server answers, and each must serve the files its script refers to.
To check the route, open https://rum.example.org/rum/ping in a browser; it only shows that this browser
reaches the receiver. /rum/demo?key=SITE serves a test page with a site's script. Neither proves that
your website loads the script.
Optional - provide a location database
Countries and cities come from a local MMDB database. The receiver reads the file in geoip_db when it is
set, and otherwise the database the Agent provides, if there is one. Without a database, reports are still
collected, without location.
Supported types are Netdata-Topology-GEO, GeoLite2-City, GeoLite2-Country, GeoIP2-City,
GeoIP2-Country, DBIP-City-Lite and DBIP-Country-Lite; a country database gives no cities.
The collector.geoip object in the response of the rum-sites Function shows whether a database is
loaded.
Configuration
Options
The receiver is a single job named receiver; there is one per Agent.
Configuration options
| Group | Option | Description | Default | Required |
|---|---|---|---|---|
| Connection | listen | Address and port to listen on. The default accepts connections from this host only. | 127.0.0.1:19938 | no |
| public_url | Public base URL of the receiver, such as https://rum.example.org, used in the sites' script tags. Leave empty and no script tag is offered unless a site sets its own. | no | ||
| tls_cert | Certificate file for serving HTTPS directly. Set together with tls_key; leave both empty to serve plain HTTP. | no | ||
| tls_key | Private key file of the certificate. Set together with tls_cert. | no | ||
| trusted_proxies | IP addresses or CIDR ranges of reverse proxies whose X-Forwarded-For and X-Real-IP headers are trusted for the visitor's address. Leave empty to use the connection's address. | no | ||
| Limits | max_body_bytes | Largest report accepted, in bytes. Larger reports are refused with HTTP 413. | 262144 | no |
| rate_limit | Request limits that protect the Agent from floods of reports. | no | ||
| rate_limit.per_ip_per_min | Requests accepted per visitor IP address per minute. More are refused with HTTP 429. | 120 | no | |
| rate_limit.per_site_per_sec | Requests accepted per site per second, from all visitors together. More are refused with HTTP 429. | 500 | no | |
| Collection | update_every | Data collection interval, in seconds. | 10 | no |
| geoip_db | Location database (MMDB file) for looking up visitors' countries and cities. Leave empty to use the database the Agent provides, if there is one. | no |
listen
Keep the default behind a reverse proxy on the same host. To accept connections from other hosts
directly, listen on this host's external address or on 0.0.0.0:19938, and set tls_cert and
tls_key. The address
is opened when the receiver starts; the job editor's Test does not check that the port is free.
public_url
Use the address that visitors' browsers reach, including any path prefix of your reverse proxy, such as
https://www.example.org/edge. The receiver never derives it from the listen address or from request
headers.
trusted_proxies
Behind a proxy, set this to the address the proxy connects from, such as 127.0.0.1/32 for a proxy on
the same host. Without it, every visitor appears to come from the proxy, so they all share one rate
limit and get no location. List only the proxies that actually connect to the receiver, because a
trusted address can claim any visitor IP.
geoip_db
With an empty path, the receiver tries topology-ip-intel/topology-ip-geo.mmdb in the Agent's cache
directory, then in its stock data directory (NETDATA_CACHE_DIR and NETDATA_STOCK_DATA_DIR override
the built-in directories). A path uses only that file. The database is checked when the receiver starts
and every minute after. To update it, write a new file and rename it over the old one; never edit or
truncate the file in use.
DEM never downloads a database. Agent packaging, the topology IP intelligence downloader or you provide and update it, and not every installation has one. Give the Netdata service account read access to the file and its directories.
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
Behind a reverse proxy on the same host
The usual setup. The proxy serves https://rum.example.org and forwards /rum/ to the receiver.
Config
jobs:
- name: receiver
listen: 127.0.0.1:19938
public_url: https://rum.example.org
trusted_proxies:
- 127.0.0.1/32
Serve HTTPS directly
Accepts reports from other hosts on port 19938 with the receiver's own certificate.
Config
jobs:
- name: receiver
listen: 0.0.0.0:19938
public_url: https://rum.example.org:19938
tls_cert: /etc/netdata/ssl/rum.crt
tls_key: /etc/netdata/ssl/rum.key
Use your own location database
Reads visitor locations from a GeoLite2 City database that you keep up to date.
Config
jobs:
- name: receiver
public_url: https://rum.example.org
trusted_proxies:
- 127.0.0.1/32
geoip_db: /var/lib/geoip/GeoLite2-City.mmdb
Allow more requests per visitor
Raises the per-IP limit for websites whose visitors share an address, such as offices behind one gateway.
Config
jobs:
- name: receiver
public_url: https://rum.example.org
trusted_proxies:
- 127.0.0.1/32
rate_limit:
per_ip_per_min: 600
per_site_per_sec: 500
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 receiver's charts are on this Agent's host. Requests count every HTTP response of the receiver: success is a status below 400, including the 204 sent for reports that are excluded on purpose; client errors are 4xx, such as refused origins, rate limits, oversized reports and unknown sites; server errors are 5xx.
Per RUM Receiver instance
The Agent's RUM receiver.
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
opening DEM history: load journal identity: journalhost: machine id: no machine id found
When
The Agent's log shows this when dem.plugin starts on Linux. The plugin then exits, so no DEM job runs,
whichever modules are enabled.
Cause
DEM keeps its history in journal files, which need the host's machine ID, and none was found. Neither
/etc/machine-id nor /var/lib/dbus/machine-id holds a valid ID, and neither file exists under the
Netdata host prefix (/host in the official Docker image). This is common in minimal containers.
Fix
On a host, create the machine ID with sudo systemd-machine-id-setup (or
sudo dbus-uuidgen --ensure=/etc/machine-id without systemd), then restart the Agent.
In the official Docker image, mount the host's machine ID under the Netdata host prefix: add
-v /etc/machine-id:/host/etc/machine-id:ro to docker run, or the same mount under volumes: in Docker
Compose, then recreate the container. Check first that the host has /etc/machine-id: Docker creates a
missing source path as an empty directory, which DEM rejects.
listen tcp 127.0.0.1:19938: bind: address already in use
Cause
Another process, or another Netdata Agent, already listens on that address and port.
Fix
Find the process with sudo ss -ltnp | grep 19938, then stop it or change listen to a free port, and
update the reverse proxy to match.
listen tcp 0.0.0.0:443: bind: permission denied
Cause
listen uses a port below 1024, which the Netdata service account is not allowed to bind.
Fix
Use a port above 1024, such as the default 19938, and serve port 443 from a reverse proxy.
listen: address 19938: missing port in address
Cause
listen has no host part.
Fix
Use 127.0.0.1:19938, or :19938 to listen on all addresses.
tls_cert and tls_key must be set together
Cause
Only one of tls_cert and tls_key is set.
Fix
Set both to serve HTTPS, or neither to serve plain HTTP.
listener TLS: could not read certificate "/etc/netdata/ssl/rum.crt": open "/etc/netdata/ssl/rum.crt": permission denied
Cause
The certificate or key file does not exist or the Netdata service account cannot read it. A similar message names the key file.
Fix
Check the path, and make the files readable by the Netdata service account (usually netdata).
body and rate limits must be positive
Cause
max_body_bytes, rate_limit.per_ip_per_min or rate_limit.per_site_per_sec is zero or negative.
Fix
Set them to positive values, or remove them to use the defaults.
trusted proxy "10.0.0.0/33": <parse error>
Cause
A trusted_proxies entry is not a valid IP address or CIDR range.
Fix
Use addresses such as 127.0.0.1 or ranges such as 10.0.0.0/8.
public_url must be an http(s) base URL without credentials, query or fragment
Cause
public_url is not an absolute http:// or https:// URL, or it has a username, a query string or a fragment. A RUM site's own public_url reports the same message.
Fix
Use a URL such as https://rum.example.org, with an optional path prefix.
GeoIP refresh: <error>; provision a supported database using atomic file replacement
When
The message is a warning in the Agent's log; collection continues without location or with the previous database.
Cause
The location database could not be loaded - it is missing, unreadable, of an unsupported type, or was changed while in use.
Fix
Make a supported database readable by the Netdata service account, and update it by writing a new file and renaming it over the old one. collector.geoip in the rum-sites Function shows the state and a reason code.
RUM charts have no country breakdown
Cause
There is no usable location database (collector.geoip.state is unavailable in rum-sites), the site
sets capture.geolocation: 'off', or visitors arrive from loopback or private addresses - which is what a
reverse proxy looks like when trusted_proxies is not set.
Fix
Provide a location database (see Prerequisites), and set trusted_proxies to the reverse proxy's address.
Every visitor gets HTTP 429 behind a reverse proxy
Cause
Without trusted_proxies, all requests appear to come from the proxy's address and share the per-IP limit.
Fix
Set trusted_proxies to the address the proxy connects from.
Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.