Real User Monitoring

Real User Monitoring

Plugin: dem.plugin Module: rum

Overview

Monitor browser Web Vitals, document and application-view traffic, JavaScript errors and resource timing.

The Faro browser SDK sends measurements to the configured RUM receiver. Netdata aggregates accepted observations over a sliding window, retains sampled investigation history locally, and optionally exports event logs and browser traces through OTLP/gRPC. Native charts, session timelines and errors need no OTLP receiver. Country-only geolocation is the default; approximate city markers require explicit opt-in and remain live-only. Frustration heuristics are disabled by default and do not establish intent or causality. Application-provided user IDs remain original application-controlled identifiers, not anonymous values. URL/path and targeted text normalization are limited transformations, not general anonymization or consent handling. Event logs add searchable custom-event attributes and optional console messages; tracing adds sampled browser request spans. Both are disabled by default and have independent destinations.

This collector is only supported on the following platforms:

• Linux
• macOS

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

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

Sites are explicitly configured; websites are not discovered automatically.

Limits

Breakdown charts show current-window top groups. Missing browser observations cannot be reconstructed, and capacity loss suppresses affected percentiles and window counts. Duplicate detection is best effort across a bounded 30-minute retention period; capacity pressure or restart can shorten it. Quality alerts require at least 30 observations for that metric and complete local measurement state. Quiet traffic alone does not trigger an alert.

History uses one plugin-wide journal file-age and committed-byte retention target in dem.conf, including disabled sites. Whole archives expire; the active file is protected, so the size target is not a hard disk ceiling. Export/history queues count records dropped under backpressure. Detail sampling applies to native history and enabled event logs and traces. Problem overrides retain available recent native context with its original attribution, then current and future detail while the session remains tracked. Earlier logs and spans are not exported retrospectively; complete sessions or traces are not guaranteed. Export acceptance does not guarantee durable storage.

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.

Configure the receiver and site

Configure the canonical receiver in dem/receiver.conf, then add one job per website in dem/rum.conf. The native configuration UI exposes the receiver as a single object and sites as independently managed jobs.

Install the browser snippet

Add <script async src="https://rum.example.org/rum/shop.js"></script> to the website, replacing the public receiver URL and site key. Allow this collector and the pinned Faro SDK CDN in the website Content Security Policy.

Optional searchable event logs

Event logs and tracing are optional and disabled by default. Enable an OTLP/gRPC receiver separately. In the receiving Netdata node’s Logs tab, select otel-logs and the netdata-rum service. Filter the time range, resource.attributes.rum.site and attributes.session.id; inspect attributes.event.attr.<key> for custom-event attributes and attributes.console.level with the message body for console messages. Netdata log access requires Cloud sign-in. Console errors are logs; uncaught exceptions and unhandled rejections remain native RUM errors. Event data is sampled and independently retained by the destination.

Optional browser tracing

To follow a request into backend services, instrument those services, accept browser trace context, allow trace headers in cross-origin CORS, coordinate sampling and send both sides to the same tracing system. Browser spans alone show browser requests, not a complete backend trace. For an external receiver, look up a copied trace ID in that system. Netdata receiver selection and direct UI navigation are part of the later frontend integration.

Customize alerts

Stock health templates evaluate complete LCP, INP and CLS populations with at least 30 observations. Quiet traffic alone has no stock alert. Customize thresholds or disable alerts through normal Netdata health configuration; use the _collect_plugin=dem and _collect_job chart labels for site-specific policies.

Configuration

Options

Options apply independently to each site job. Native job name is the beacon and history identity; display_name is human metadata. Event logs and browser tracing each have a complete destination with no inheritance. Saved inactive settings are retained without endpoint or TLS validation, but all native secret references must resolve for the job to start.

via File

The configuration file name for this integration is dem/rum.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/rum.conf

Examples

Website

Native charts, session timelines and errors, with country-only location and frustration heuristics disabled. No OTLP receiver is required.

jobs:
  - name: shop
    allowed_origins: [https://shop.example.org]

Problems-only detail

Keep measurements and live views for all received traffic, with detail selected only for errors or poor vitals by the default problem overrides.

jobs:
  - name: shop
    allowed_origins: [https://shop.example.org]
    investigate:
      sample_rate: 0

Measurements and live views only

Keep measurements and live views without retained native detail or event-log and trace exports, even when those exports are enabled.

jobs:
  - name: shop
    allowed_origins: [https://shop.example.org]
    investigate:
      sample_rate: 0
      always_keep: []

Searchable event logs

Search sampled events and optional console messages with a local OTLP/gRPC receiver at http://127.0.0.1:4317. Enable that receiver separately.

jobs:
  - name: shop
    allowed_origins: [https://shop.example.org]
    event_logs:
      enabled: true
      include_console_logs: true

Browser tracing

Send browser spans to your backend tracing receiver without enabling event logs. Provide the secret and configure backend instrumentation, context propagation, CORS and compatible sampling separately.

jobs:
  - name: shop
    allowed_origins: [https://shop.example.org]
    tracing:
      enabled: true
      propagate_to: [https://api.example.org]
      destination:
        endpoint: https://traces.example.org:4317
        auth_token: ${env:TRACE_EXPORT_TOKEN}

Live Data

Use these process-wide Functions through the Netdata Agent or Cloud to inspect RUM setup, live activity and retained investigation history. Invoke their public rum-* names; filter by site where supported.

RUM Sites

Inspect site setup, sampling, receiver availability and recent activity to diagnose missing browser data.

Prerequisites

No additional configuration is required.

Parameters

This function has no parameters.

Returns

One admitted site job. The response also includes collector public URL and ingress availability.

RUM Pages

Compare document-entry pages using recent observed traffic, Web Vital populations and attributed elements.

Prerequisites

No additional configuration is required.

Parameters

Returns

All retained document-entry groups, independent of chart top groups. Null values indicate absent or incomplete measurements; loss fields identify retained capacity-loss evidence.

RUM Live

Read recent browser events for live activity views, optionally continuing from a previous response.

Prerequisites

No additional configuration is required.

Parameters

Returns

Recent observation rows. Vital revisions update the same document metric; rows are not independent document views.

RUM Sessions

Investigate retained sampled sessions that overlap a time range, including pages, errors and optional interaction heuristics.

Prerequisites

No additional configuration is required.

Parameters

Returns

One session with retained activity saved in the selected range. Counts and activity span cover retained events, not lifetime totals. Results can include disabled sites until their history expires.

RUM Errors

Group errors saved in the selected range by fingerprint; select a fingerprint to investigate affected sessions, pages and browsers.

Prerequisites

No additional configuration is required.

Parameters

Returns

One error fingerprint per site with events saved in the selected range. Affected-session, page and browser statistics are null until a fingerprint is selected; first and last seen use original event time. Results can include disabled sites until their history expires.

RUM Session Events

Read the retained event timeline for a session to follow navigation, errors and traced requests.

Prerequisites

No additional configuration is required.

Parameters

Returns

One retained or pending session event, with original observation time in Unix microseconds and an optional trace identifier. The available session timeline is returned without range filtering. Unknown sessions return an error.

Troubleshooting

Other Problems

No browser measurements

Check receiver availability, the installed snippet URL and the site allowed origins. Open the rum-sites Function for reachability and rejected-origin diagnostics. Missing vital samples produce gaps, including when the receiver is unavailable.

Missing exported events or spans

Check that the required signal is enabled and its receiver accepts OTLP/gRPC at the configured explicit http or https URL and port. Verify Bearer authentication, TLS trust and paired client certificate/key files. The event and span charts distinguish receiver-accepted records, failed or rejected delivery, and local queue/shutdown loss. A timeout may have an unknown delivery outcome; zero traffic proves neither failure nor success. Receiver failures do not stop native history.