diff --git a/docs/Collecting Metrics/Collectors/Applications/RUM Receiver.mdx b/docs/Collecting Metrics/Collectors/Applications/RUM Receiver.mdx index 183ddf1fdd..90a740af3c 100644 --- a/docs/Collecting Metrics/Collectors/Applications/RUM Receiver.mdx +++ b/docs/Collecting Metrics/Collectors/Applications/RUM Receiver.mdx @@ -5,8 +5,8 @@ learn_status: "Published" toc_max_heading_level: "6" toc_collapsible: "true" learn_rel_path: "Collecting Metrics/Collectors/Applications" -keywords: [rum, browser, web-vitals, dem] -description: "Monitor the availability and HTTP request outcomes of the browser telemetry receiver." +keywords: [rum receiver, rum, real user monitoring, beacon, faro, browser telemetry, dem] +description: "Monitor the endpoint that receives browser reports for Real User Monitoring: whether it serves and how its requests end." message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE" sidebar_position: "690" learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/applications/rum-receiver" @@ -27,53 +27,107 @@ Module: receiver ## Overview -Monitor the availability and HTTP request outcomes of the browser telemetry receiver. +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](https://grafana.com/oss/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. -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. +| 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: + +- [Real User Monitoring](/docs/collecting-metrics/collectors/applications/real-user-monitoring) ### Default Behavior #### Auto-Detection -The stock receiver starts on loopback. Sites require explicit configuration. +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 -Browser payloads and request rates are limited by receiver settings. +- 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 -Resource usage depends on accepted browser traffic and the configured measurement window. Optional OTLP export and investigation history add network and local disk work. +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 -#### Install the DEM plugin +#### 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: + +```nginx +location /rum/ { + proxy_pass http://127.0.0.1:19938; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +} +``` -Linux builds include DEM by default. Native installations include the `netdata-plugin-dem` package. RUM does not require the optional browser runtime. +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). -#### Expose the receiver +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. -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. +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. -#### 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. +#### Optional - provide a location database -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. +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. -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. +The `collector.geoip` object in the response of the `rum-sites` Function shows whether a database is +loaded. @@ -81,7 +135,7 @@ Publish updates by writing a separate complete file and atomically renaming it o #### Options -Options apply to the canonical receiver. +The receiver is a single job named `receiver`; there is one per Agent.
Configuration options @@ -90,22 +144,56 @@ Options apply to the canonical receiver. | 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 | +| **Connection** | [listen](#option-connection-listen) | Address and port to listen on. The default accepts connections from this host only. | 127.0.0.1:19938 | no | +| | [public_url](#option-connection-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](#option-connection-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](#option-collection-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](#option-collection-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, 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. +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. @@ -128,17 +216,76 @@ sudo ./edit-config dem/receiver.conf ##### Examples -###### Local receiver +###### Behind a reverse proxy on the same host -Minimal native configuration. +The usual setup. The proxy serves `https://rum.example.org` and forwards `/rum/` to the receiver.
-Examples +Config ```yaml 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 + +```yaml +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 + +```yaml +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 + +```yaml +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 ```
@@ -157,12 +304,15 @@ 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. +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 receiver +### Per RUM Receiver instance -One configured receiver; breakdowns appear when matching observations are available. +The Agent's RUM receiver. This scope has no labels. @@ -179,21 +329,147 @@ Metrics: ### Known Errors -#### Missing or unexpected geography +#### 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"`: `` **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. +A `trusted_proxies` entry is not a valid IP address or CIDR range. **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 addresses such as `127.0.0.1` or ranges such as `10.0.0.0/8`. -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. +#### 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. -### Other Problems +#### GeoIP refresh: ``; 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** -#### No browser measurements +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** -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. +Set `trusted_proxies` to the address the proxy connects from. diff --git a/docs/Collecting Metrics/Collectors/Applications/Real User Monitoring.mdx b/docs/Collecting Metrics/Collectors/Applications/Real User Monitoring.mdx index 82dd8b50a2..c854934d73 100644 --- a/docs/Collecting Metrics/Collectors/Applications/Real User Monitoring.mdx +++ b/docs/Collecting Metrics/Collectors/Applications/Real User Monitoring.mdx @@ -5,8 +5,8 @@ learn_status: "Published" toc_max_heading_level: "6" toc_collapsible: "true" learn_rel_path: "Collecting Metrics/Collectors/Applications" -keywords: [rum, browser, web-vitals, dem] -description: "Monitor browser Web Vitals, document and application-view traffic, JavaScript errors and resource timing." +keywords: [real user monitoring, rum, web vitals, core web vitals, faro, javascript errors, frontend, browser, dem] +description: "Measure what real visitors experience on your website (Core Web Vitals, load times, JavaScript errors and traffic), straight from their browsers." message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE" sidebar_position: "670" learn_link: "https://learn.netdata.cloud/docs/collecting-metrics/collectors/applications/real-user-monitoring" @@ -27,84 +27,160 @@ Module: rum ## Overview -Monitor browser Web Vitals, document and application-view traffic, JavaScript errors and resource timing. +Measure what real visitors experience on your website (Core Web Vitals, load times, JavaScript errors and traffic), +straight from their browsers. + +Add one script tag to the website, and each site job gives you: + +- Web Vitals (LCP, INP, CLS, FCP and TTFB) as p50, p75 and p95, with how many experiences were good, needed + improvement or were poor, and alerts when more than a quarter of LCP, INP or CLS experiences miss the good + threshold. +- Document load and DOMContentLoaded times, same-site API (fetch and XHR) durations, and resource timings by host. +- Page views, application views, sessions and JavaScript errors, with errors grouped by fingerprint. +- The same measurements broken down by page, country, browser, device type and application version. +- A live feed of recent events and a history of sampled sessions, each with its timeline of pages, errors and events. +- Optionally, rage, dead and error clicks, and browser events and request traces sent to an OpenTelemetry receiver. + + +The website loads a small script from the Agent's [RUM Receiver](/docs/collecting-metrics/collectors/applications/rum-receiver), +which loads the [Grafana Faro](https://grafana.com/oss/faro/) Web SDK from the same receiver. The SDK reports from each +visitor's browser back to the receiver; visitors never contact a third-party service. The receiver accepts reports only +from the site's allowed origins and hands them to the site job, which keeps the last few minutes of measurements in +memory for the charts and saves the details of sampled sessions to local history on the Agent. + +Before anything is charted, saved or exported, URLs lose their query strings, fragments and credentials, and path +segments that look like email addresses, IDs or tokens are replaced. Client IP addresses are used to enforce rate +limits and look up the visitor's location, and are not stored. This is not full anonymization: error messages, page +paths, user IDs that your application sets and exported event attributes can still identify people. Credentials +from the site's configuration, such as an export `auth_token`, are masked in saved and exported text when they are +at least 4 bytes long; a shorter value is masked only when it looks like a credential (`token=...` or `Bearer ...`). -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. -The Netdata service needs write access to its DEM state directory. Configured TLS and GeoIP files must be readable by the Netdata service account. +| Permission | Needed when | +|:--|:--| +| The Netdata service account (usually `netdata`) can read the `tls_ca`, `tls_cert` and `tls_key` files of an export destination. | Event logs or tracing send to an HTTPS receiver with a custom CA or a client certificate. | + + +Real User Monitoring can be monitored further using the following other integrations: + +- [RUM Receiver](/docs/collecting-metrics/collectors/applications/rum-receiver) +- [Browser Journey](/docs/collecting-metrics/collectors/synthetic-testing/browser-journey) +- [Lighthouse Desktop Audit](/docs/collecting-metrics/collectors/synthetic-testing/lighthouse-desktop-audit) ### Default Behavior #### Auto-Detection -Sites are explicitly configured; websites are not discovered automatically. +This integration doesn't support auto-detection. #### 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. +- The charts summarize the reports received in the last `window` (5 minutes by default), counted by when the receiver + got them. +- Breakdown charts show the busiest values in that window and combine the rest as `other`: up to `page_groups` pages + and application views and `countries` countries (20 each by default), 20 browsers, 10 application versions, + 10 error fingerprints and 10 resource hosts. The `rum-pages` Function lists every page. +- The Web Vital alerts need at least 30 observations of that vital in the window, so a quiet site never triggers them. + No stock alert fires when traffic stops. +- Session history is shared with the synthetic monitors and kept for about 30 days, or less once it would exceed + 1 GiB (`history` in `dem.conf`). Files of up to a day expire together, so records can stay about a day longer; when the + size limit is reached, the oldest records go first. Only sessions selected by `investigate` are saved. +- Up to 2,000 sessions per site are tracked in memory. A session that goes quiet or is pushed out loses the details + held for it, so a later error can no longer save them. +- City locations appear only in the live feed. History and exports keep the country at most. -RUM and synthetic history share the 30-day and 1-GiB defaults in `dem.conf`, including disabled sites and retained -machine identities. The byte target counts full journal file sizes including preallocation, with an 8-MiB minimum. -Whole files expire by their newest saved record. With normal clocks and timely successful cleanup, some older -records can remain roughly one extra day plus an hour; size pressure can remove younger history. This is not an -exact record TTL or a hard disk ceiling. `dem-history-status` reports the effective policy, sampled file bytes, -and storage errors; it cannot establish complete history or explain why a particular event is absent. -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 +The site job runs inside the DEM plugin on the Agent. Decoding reports costs CPU, and memory grows with the number of +distinct page views and sessions received recently: their measurements are kept for `window`, and the identities used +to recognize repeated reports for 30 minutes. In Netdata's tests, one site that received 450,000 page views in +29 minutes held about 630 MB of Go heap, and the DEM plugin used about two-thirds of a CPU core while it received +1,000 reports per second across 100 sites and scheduled 400 browser jobs (not counting the browsers themselves). -#### Performance Impact +- `measure_sample_rate` measures a share of sessions instead of all of them, and a shorter `window` keeps less in + memory. +- Each site has about 30 charts plus its breakdown charts. At the default limits a busy site can have about 700 + breakdown charts; lower `page_groups` and `countries` to reduce them. +- Saving sessions writes to local disk; lower `investigate.sample_rate` to save fewer. +- Event logs and tracing send data over the network to their destinations. -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 +#### Expose the RUM receiver to your visitors + +Browsers send reports to the [RUM Receiver](/docs/collecting-metrics/collectors/applications/rum-receiver), which +listens only on `127.0.0.1:19938` by default. Put an HTTPS reverse proxy in front of it that forwards the whole `/rum/` +path, then set the receiver's `public_url` to the public address and `trusted_proxies` to the proxy's address, in +`dem/receiver.conf`. The receiver page has the details. + + +#### Add a site job -Linux builds include DEM by default. Native installations include the `netdata-plugin-dem` package. RUM does not require the optional browser runtime. +Add one job per website to `dem/rum.conf`, with the site key (`name`) and the origins the website is served from +(`allowed_origins`). See the examples below. -#### 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. +#### Add the script to your website + +Once the receiver has a public URL, the `rum-sites` Function shows the script tag for each site. It looks like this, +with your receiver address and site key: + +```html + +``` + +- Add it to every page as a classic external script tag, with the address exactly as shown. The SDK and the reports + use addresses relative to the tag's `src`, so a redirect of only the script does not carry over to them. A tag + manager must insert the tag itself; pasting the script's contents inline, loading it as a module or evaluating it + does not work. +- If the website has a Content Security Policy, allow the receiver's script address in `script-src-elem` (or + `script-src`) and its `/rum/` address in `connect-src`. A `nonce` on the tag is passed on to the SDK scripts, and + `strict-dynamic` works as usual. A policy that requires Trusted Types for script URLs needs your own integration: + the script creates no permissive policy. HTTPS pages need an HTTPS receiver address. +- Optionally, set `data-version="1.4.2"` on the tag to compare application releases, call + `window.netdataRum.setUser({ id: '...' })` to find a user's sessions later, and, once the SDK has loaded, report + single-page application routes with `GrafanaFaroWebSdk.faro.api.setView({ name: '/checkout' })`. Use an internal, + non-personal user ID of at most 128 bytes, and clear it when the user logs out: it is stored without hashing. It + appears in session history only, not in the live feed, the charts or the exports. -#### Install the browser snippet -Add `` to the website, replacing the configured public receiver URL and site key. The receiver serves the pinned SDK too; allow its script and connection URLs in the website Content Security Policy. Proxy the entire RUM path, including SDK assets and collect requests. A script-only redirect is insufficient. +#### Check that reports arrive -#### Optional searchable event logs +Open the website in a regular browser (automated and headless browsers are excluded by default) and look at the +browser's Network panel: the script and SDK load from the receiver, and a `POST` to `/rum/shop/collect` returns `202`. +`rum-sites` then shows a recent last accepted report for the site. Charts appear within the next `update_every`. +A `202` means the report reached the live measurements; it does not prove that it was saved or exported. -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.` 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 +#### Optional - send event logs and traces to OpenTelemetry -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. +Event logs (browser events, custom event attributes and optionally console messages) and browser request traces are +off by default and are exported separately, over OTLP/gRPC. The default destination, `http://127.0.0.1:4317`, is where +the Agent's [OpenTelemetry](https://github.com/netdata/netdata/blob/master/src/crates/otel-plugin/integrations/opentelemetry.md) plugin listens; there, event logs +appear in the Logs tab under the `netdata-rum` service, and spans in the Traces tab. -#### Customize alerts +To follow a request from the browser into your backend, also instrument the backend services, list their origins in +`tracing.propagate_to`, allow the `traceparent` header in their CORS settings, and send their spans to the same tracing +system. -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. +Each job is one website. All options apply per job; event logs and tracing each have their own destination.
Configuration options @@ -113,43 +189,196 @@ Options apply independently to each site job. Native job name is the beacon and | Group | Option | Description | Default | Required | |:------|:-----|:------------|:--------|:---------:| -| **Site** | name | Stable site identifier used in beacon URLs and history. Renaming creates a new history identity. | | yes | -| | display_name | Human-readable site name. Leave empty to use the site key. | | no | -| | allowed_origins | Web origins allowed to send telemetry, such as https://example.org. A leading *. allows subdomains only. | | yes | -| | public_url | Public receiver base URL used for this site's installation snippet. Leave empty to use the receiver public URL. | | no | +| **Site** | [name](#option-site-name) | Site key, made of letters, digits, underscores and hyphens. It is part of the script URL and identifies the site in charts and history, so renaming starts a separate history. | | yes | +| | display_name | Human-readable site name for charts and Functions. Leave empty to use the site key. | | no | +| | [allowed_origins](#option-site-allowed-origins) | Origins the website is served from, such as `https://shop.example.org`; reports from other origins are refused. A leading `*.` matches any subdomain. | | yes | +| | public_url | Public base URL of the receiver for this site's script tag, such as `https://rum.example.org`. Leave empty to use the receiver's public URL. | | no | | **Collection** | update_every | Data collection interval, in seconds. | 10 | no | -| | window | Receiver-arrival window for recent browser measurements and distinct observed sessions. Accepts durations between 1m and 30m. | 5m | no | -| | page_groups | Maximum individual page groups shown in breakdown charts. Remaining groups are combined as other. | 20 | no | -| | countries | Maximum individual countries shown in breakdown charts. Remaining countries are combined as other. | 20 | no | -| | bots | Exclude crawlers and browser automation by default, or include them as bot traffic. | exclude | no | -| **Capture** | capture | Choose optional location and interaction evidence independently of sampling. Defaults retain country comparisons and disable frustration heuristics. | | no | -| | capture.geolocation | IP-derived location detail: off disables lookup, country retains country comparisons, and city adds approximate live map markers. Omitted or null means country; coordinates are never retained in history or exported. | country | no | -| | capture.frustration_signals | Enable rage, dead and error click heuristics and their browser instrumentation. Disabled by default; these signals do not establish user intent or causality. | no | no | -| **Sampling** | measure_sample_rate | Share of browser sessions collected, from 0 to 1. Omitted or null means all; zero disables collection. Browser measurement charts are absent while collection is disabled; receiver diagnostics remain available. | 1 | no | -| | investigate | Select native investigation history and enabled event-log and trace exports from received sessions. Leave empty to select all received sessions. | | no | -| | investigate.sample_rate | Baseline share of received sessions selected for detail, from 0 to 1. Omitted or null means all; zero selects only the problem overrides below. | 1 | no | -| | investigate.always_keep | Conditions that select detail beyond the baseline sample. Omitted or null keeps errors and poor vitals; an empty list disables overrides. | ["errors","poor_vitals"] | no | -| **Event logs** | event_logs | Export sampled browser events for search, including custom-event attributes. Native RUM history works independently. | | no | -| | event_logs.enabled | Send event logs to the configured destination. Disabled by default; native charts, sessions and errors remain available. | no | no | -| | event_logs.include_console_logs | Capture console info, warn and error messages for investigated sessions. Effective only when event logs are enabled. | no | no | -| | event_logs.destination | Receiver for this signal only. Leave unset to use the local OTLP/gRPC receiver. | | no | -| | event_logs.destination.endpoint | OTLP/gRPC receiver URL with an explicit port. Use http for plaintext or https for TLS; paths, credentials, query strings and fragments are not allowed. | http://127.0.0.1:4317 | no | -| | event_logs.destination.auth_token | Bearer token accepted by the receiver. Use a native secret reference; leave empty for no authentication. | | no | -| | event_logs.destination.tls_ca | CA certificate file for verifying an HTTPS receiver. Leave empty to use system roots. | | no | -| | event_logs.destination.tls_cert | Client certificate file for an HTTPS receiver. Set together with TLS key; leave both empty to omit client authentication. | | no | -| | event_logs.destination.tls_key | Client private key file for an HTTPS receiver. Set together with TLS client certificate. | | no | -| **Browser tracing** | tracing | Capture browser request spans and propagate trace context. Backend spans require separately instrumented services. | | no | -| | tracing.enabled | Capture and export browser spans independently of event logs. Disabled by default. | no | no | -| | tracing.propagate_to | Additional literal API origins receiving trace headers. Same-origin requests receive them automatically; cross-origin APIs must allow the trace headers in CORS. | | no | -| | tracing.destination | Receiver for this signal only. Leave unset to use the local OTLP/gRPC receiver. | | no | -| | tracing.destination.endpoint | OTLP/gRPC receiver URL with an explicit port. Use http for plaintext or https for TLS; paths, credentials, query strings and fragments are not allowed. | http://127.0.0.1:4317 | no | -| | tracing.destination.auth_token | Bearer token accepted by the receiver. Use a native secret reference; leave empty for no authentication. | | no | -| | tracing.destination.tls_ca | CA certificate file for verifying an HTTPS receiver. Leave empty to use system roots. | | no | -| | tracing.destination.tls_cert | Client certificate file for an HTTPS receiver. Set together with TLS key; leave both empty to omit client authentication. | | no | -| | tracing.destination.tls_key | Client private key file for an HTTPS receiver. Set together with TLS client certificate. | | no | -| **Normalization** | redact_paths | Apply site-specific URL-path replacements before built-in normalization. These rules do not anonymize user IDs or provide general data-loss prevention. | | no | -| | redact_paths[].pattern | Go regular expression matching private path identifiers. Empty patterns are ignored. | | no | -| | redact_paths[].replace | Replacement text for matching path segments. Leave empty to remove them. | | no | +| | [window](#option-collection-window) | Time span of recent reports that the charts, alerts and Pages view summarize, from 1m to 30m. | 5m | no | +| | page_groups | How many of the busiest pages and application views get their own breakdown charts, from 1 to 100. The rest are combined as `other`. | 20 | no | +| | countries | How many of the busiest countries get their own breakdown charts, from 1 to 100. The rest are combined as `other`. | 20 | no | +| | bots | Whether to drop reports from crawlers, headless browsers and other automation (`exclude`) or keep them as device `bot` (`include`). | exclude | no | +| **Capture** | capture | Optional location and interaction data to collect. By default only the visitor's country is looked up and click signals are off. | | no | +| | [capture.geolocation](#option-capture-capture-geolocation) | Location looked up from the visitor's IP address - `off`, `country`, or `city`, which adds approximate city markers to the live feed. Coordinates are never stored or exported. | country | no | +| | [capture.frustration_signals](#option-capture-capture-frustration-signals) | Detect rage clicks, dead clicks and clicks followed by an error. These are heuristics, not proof of user frustration. | no | no | +| **Sampling** | [measure_sample_rate](#option-sampling-measure-sample-rate) | Share of browser sessions that send reports, from 0 to 1. 1 measures every session; 0 stops collection for the site. | 1 | no | +| | investigate | Which measured sessions are saved to history with their details, and exported when event logs or tracing are on. Leave empty to save every session. | | no | +| | [investigate.sample_rate](#option-sampling-investigate-sample-rate) | Share of measured sessions saved with their details, from 0 to 1. 0 saves only the sessions that `always_keep` selects. | 1 | no | +| | [investigate.always_keep](#option-sampling-investigate-always-keep) | Sessions to save whatever the sample rate - `errors` (a JavaScript error) and `poor_vitals` (a poor Web Vital). An empty list adds none. | ["errors","poor_vitals"] | no | +| **Event logs** | [event_logs](#option-event-logs-event-logs) | Export browser events, including custom event attributes, as OpenTelemetry logs. Session history in Netdata works without it. | | no | +| | [event_logs.enabled](#option-event-logs-event-logs-enabled) | Send event logs to their destination. | no | no | +| | [event_logs.include_console_logs](#option-event-logs-event-logs-include-console-logs) | Also export the console info, warning and error messages of saved sessions. Requires event logs. | no | no | +| | event_logs.destination | OTLP/gRPC receiver for this signal. Leave empty to use `http://127.0.0.1:4317`, where the Netdata OpenTelemetry plugin listens by default. | | no | +| | [event_logs.destination.endpoint](#option-event-logs-event-logs-destination-endpoint) | Receiver address with a port, `http://host:port` for plaintext or `https://host:port` for TLS, without a path or credentials. | http://127.0.0.1:4317 | no | +| | [event_logs.destination.auth_token](#option-event-logs-event-logs-destination-auth-token) | Bearer token for the receiver. Use a secret reference such as `${env:OTLP_TOKEN}`. Leave empty for no authentication. | | no | +| | event_logs.destination.tls_ca | CA certificate file to verify an HTTPS receiver. Leave empty to use the system's trusted CAs. | | no | +| | event_logs.destination.tls_cert | Client certificate file for an HTTPS receiver that requires one. Set together with the client key. | | no | +| | event_logs.destination.tls_key | Client private key file. Set together with the client certificate. | | no | +| **Browser tracing** | [tracing](#option-browser-tracing-tracing) | Record spans for the browser's requests and pass trace context to your APIs, exported as OpenTelemetry traces. | | no | +| | [tracing.enabled](#option-browser-tracing-tracing-enabled) | Send browser spans to their destination. Independent of event logs. | no | no | +| | tracing.propagate_to | Origins of other APIs, such as `https://api.example.org`, whose requests also get the `traceparent` header. Requests to the page's own origin always get it. | | no | +| | tracing.destination | OTLP/gRPC receiver for this signal. Leave empty to use `http://127.0.0.1:4317`, where the Netdata OpenTelemetry plugin listens by default. | | no | +| | [tracing.destination.endpoint](#option-browser-tracing-tracing-destination-endpoint) | Receiver address with a port, `http://host:port` for plaintext or `https://host:port` for TLS, without a path or credentials. | http://127.0.0.1:4317 | no | +| | [tracing.destination.auth_token](#option-browser-tracing-tracing-destination-auth-token) | Bearer token for the receiver. Use a secret reference such as `${env:OTLP_TOKEN}`. Leave empty for no authentication. | | no | +| | tracing.destination.tls_ca | CA certificate file to verify an HTTPS receiver. Leave empty to use the system's trusted CAs. | | no | +| | tracing.destination.tls_cert | Client certificate file for an HTTPS receiver that requires one. Set together with the client key. | | no | +| | tracing.destination.tls_key | Client private key file. Set together with the client certificate. | | no | +| **Normalization** | [redact_paths](#option-normalization-redact-paths) | Your own replacements for private identifiers in URL paths, applied before the built-in ones. | | no | +| | redact_paths[].pattern | Regular expression, in Go syntax, matching the part of a URL path to replace. Empty patterns are ignored. | | no | +| | redact_paths[].replace | Replacement text, such as `:account`. Leave empty to remove the match. | | no | +| **Virtual Node** | [vnode](#option-virtual-node-vnode) | Associates this job with a [Virtual Node](https://learn.netdata.cloud/docs/netdata-agent/configuration/organize-systems-metrics-and-alerts#virtual-nodes). | | no | + + +##### name + +Browsers load the site's script from `/rum/` followed by the site key and `.js`, and send reports to `/rum/` followed +by the site key and `/collect`. After a rename, update the script tag on the website. + + + +##### allowed_origins + +An origin is the scheme, host and port of the page, such as `https://shop.example.org` or `http://localhost:8080`, +without a path. Scheme and port must match exactly. `https://*.example.org` matches `https://www.example.org` and +`https://app.example.org`, but not `https://example.org`; list that separately. The `rum-sites` Function shows the last +refused origin, which helps when reports from your own pages are refused. + + + +##### window + +A longer window smooths percentiles on quiet sites and gives the alerts more observations, and keeps more in memory. +Changing it restarts the measurements. + + + +##### capture.geolocation + +City markers need a database with city data on the receiver (see the RUM Receiver page). In YAML, quote `'off'`; +unquoted, `off` is read as a boolean and the job does not start. + + + +##### capture.frustration_signals + +A rage click is three clicks on one spot within a second, a dead click is a click on a link or button that changes +nothing within a second, and an error click is followed by a JavaScript error within a second. Only a short CSS +selector of the clicked element is sent, never its text. Enabling them adds click listeners to every page. They are counted on the frustration chart and, for +saved sessions, appear in the session timeline. + + + +##### measure_sample_rate + +The decision is made once per browser session: a session that is not sampled sends nothing, so it cannot be saved or +investigated later. A browser session keeps its decision until it ends, even across page reloads, so a new rate +reaches a visitor in their next session. At 0 the script stops loading the SDK at the next page load, the receiver +discards reports from pages that are still open, and the measurement charts stop. + + + +##### investigate.sample_rate + +Reports that carry no session ID still count in the measurements. They are saved and exported only when +`sample_rate` is 1 or they match `always_keep`; their JavaScript errors are then saved as standalone errors, +outside any session. + + + +##### investigate.always_keep + +To save details only for problem sessions, set `sample_rate` to 0 and keep the default list. When a session starts to +match, the details already held for it (up to 100 entries) are saved, and so is everything after, while the Agent +still tracks the session (up to 2,000 per site; quiet sessions expire). +Event logs and spans sent before the session matched are not exported afterwards. + + + +##### event_logs + +With the default destination, open the Logs tab of the receiving node, select the `otel-logs` source and the +`netdata-rum` service (`resource.attributes.service.name`), then filter by `resource.attributes.rum.site` (the +site key) and `attributes.session.id`. Each record's `attributes.rum.type` is `console`, `event`, `error`, +`pageview` or `vital`; look at `attributes.console.level`, `attributes.event.name`, `attributes.event.attr.KEY`, +and for errors `attributes.error.type` and `attributes.error.stack`. Viewing logs needs Netdata Cloud sign-in. + + + +##### event_logs.enabled + +Export never blocks measurements or history. On the `rum.otlp` chart, `sent` counts records the receiver accepted +(not proof that it stored them), `errors` counts records whose delivery failed or was refused (a timeout can +leave the outcome unknown), and `dropped` counts records lost locally because the queue was full or the job +stopped first. Failed records are not retried. Turning the export off keeps its saved settings without checking +them. + + + +##### event_logs.include_console_logs + +Console errors are exported as logs. Uncaught exceptions and unhandled promise rejections are always collected as +JavaScript errors, with or without this option. + + + +##### event_logs.destination.endpoint + +Omit the key to use the default; an explicitly empty value is rejected while the export is on. Write IPv6 +addresses in brackets, such as `https://[2001:db8::1]:4317`. + + + +##### event_logs.destination.auth_token + +A secret reference must resolve even while the export is disabled, or the job does not start. + + + +##### tracing + +Browser spans show the browser's side of each request; they do not prove what the backend did. A session can +contain several traces, and event logs are not linked to traces automatically: look up a trace ID from the +browser in your tracing system. + + + +##### tracing.enabled + +The `rum.spans` chart counts spans with the same `sent`, `errors` and `dropped` meaning as the event log chart +(see `event_logs.enabled`). Turning tracing off keeps its saved settings without checking them. + + + +##### tracing.destination.endpoint + +Omit the key to use the default; an explicitly empty value is rejected while tracing is on. Write IPv6 +addresses in brackets, such as `https://[2001:db8::1]:4317`. + + + +##### tracing.destination.auth_token + +A secret reference must resolve even while the export is disabled, or the job does not start. + + + +##### redact_paths + +The built-in rules already replace path segments that look like an email address (`:email`), a UUID or a number of +six or more digits (`:id`), or a long token (`:token`). Add a rule for identifiers they miss, for example +`pattern: '/accounts/[^/]+'` with `replace: '/accounts/:account'`. These rules apply to URL paths only; they do not +change user IDs, error messages or event attributes. + + + +##### vnode + +The site's charts and alerts appear under the virtual node instead of this Agent's host, which lets you group the +real-user and synthetic monitoring of one website under one node. Define the virtual node first, as the `dem:vnode` +dynamic configuration or as a YAML file in the `vnodes/` directory of the Netdata configuration directory, then enter +its name, not its GUID. Changing it restarts the measurements; saved sessions keep the virtual node they were +recorded under. +
@@ -171,49 +400,52 @@ sudo ./edit-config dem/rum.conf ##### Examples -###### Website +###### Measure a website -Native charts, session timelines and errors, with country-only location and frustration heuristics disabled. No OTLP receiver is required. +The minimal site. It measures every session and saves every session to history.
-Examples +Config ```yaml jobs: - name: shop - allowed_origins: [https://shop.example.org] + allowed_origins: + - https://shop.example.org ```
-###### Problems-only detail +###### Save details only for problem sessions -Keep measurements and live views for all received traffic, with detail selected only for errors or poor vitals by the default problem overrides. +Measures every session but saves to history only sessions with a JavaScript error or a poor Web Vital.
-Examples +Config ```yaml jobs: - name: shop - allowed_origins: [https://shop.example.org] + allowed_origins: + - https://shop.example.org investigate: sample_rate: 0 ```
-###### Measurements and live views only +###### Measure without saving sessions -Keep measurements and live views without retained native detail or event-log and trace exports, even when those exports are enabled. +Keeps the charts and the live feed, and saves and exports no session details.
-Examples +Config ```yaml jobs: - name: shop - allowed_origins: [https://shop.example.org] + allowed_origins: + - https://shop.example.org investigate: sample_rate: 0 always_keep: [] @@ -221,17 +453,55 @@ jobs: ```
-###### Searchable event logs +###### Measure a share of a busy site -Search sampled events and optional console messages with a local OTLP/gRPC receiver at http://127.0.0.1:4317. Enable that receiver separately. +Measures one browser session in ten, to cut the traffic and the Agent's work on a high-traffic site.
-Examples +Config ```yaml jobs: - name: shop - allowed_origins: [https://shop.example.org] + allowed_origins: + - https://shop.example.org + - https://*.shop.example.org + measure_sample_rate: 0.1 + +``` +
+ +###### Hide account IDs in URLs + +Replaces account names in paths such as `/accounts/acme/settings` before anything is stored. + +
+Config + +```yaml +jobs: + - name: shop + allowed_origins: + - https://shop.example.org + redact_paths: + - pattern: '/accounts/[^/]+' + replace: '/accounts/:account' + +``` +
+ +###### Send event logs to the local OpenTelemetry plugin + +Exports browser events and console messages to the Agent's OpenTelemetry plugin, where they appear in the Logs tab. + +
+Config + +```yaml +jobs: + - name: shop + allowed_origins: + - https://shop.example.org event_logs: enabled: true include_console_logs: true @@ -239,20 +509,22 @@ jobs: ```
-###### Browser tracing +###### Send browser traces to a tracing backend -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. +Exports browser request spans to a remote OTLP/gRPC receiver with a token, and adds trace context to API requests.
-Examples +Config ```yaml jobs: - name: shop - allowed_origins: [https://shop.example.org] + allowed_origins: + - https://shop.example.org tracing: enabled: true - propagate_to: [https://api.example.org] + propagate_to: + - https://api.example.org destination: endpoint: https://traces.example.org:4317 auth_token: ${env:TRACE_EXPORT_TOKEN} @@ -260,6 +532,23 @@ jobs: ```
+###### Group a site under a virtual node + +Shows the site's charts and alerts under the `shop` virtual node, which must be defined first. + +
+Config + +```yaml +jobs: + - name: shop + vnode: shop + allowed_origins: + - https://shop.example.org + +``` +
+ ## Alerts @@ -283,82 +572,80 @@ Metrics grouped by *scope*. The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels. -All charts remain on this Agent. Native job identity scopes site charts; display_name is optional metadata. -The window uses receiver arrival time. Each Web Vital contributes its latest report per document experience; -percentiles cannot be averaged across times or groups. Population charts show retained observations and ratings. -No observations means no percentile. Capacity loss makes affected percentiles and counts unavailable; lost_reports -is retained loss evidence, not a denominator or an exact count of missing observations in the window. +Each site has its own charts, under its virtual node when `vnode` is set and under this Agent's host otherwise. -Document views count initial activations and back-forward cache restores. Application views count explicit route -occurrences separately. Observed sessions are distinct browser session identities seen in the window, not concurrent -users. JavaScript errors are events; errors divided by document views is not a failure percentage. Breakdowns use -current-window top groups plus a pooled other bucket; page Functions expose all retained document-entry groups. +- Percentile and count charts describe the reports received in the last `window`. Each page view counts once per Web + Vital, with its latest value; percentiles cannot be averaged across sites or breakdown values. +- A vital with no observations in the window leaves a gap in its percentile chart; a measured zero is a real value. +- A page view is a document load or a return from the browser's back-forward cache. Single-page application route + changes are application views, and Web Vitals stay with the page view even when reported after a route change. +- Same-site fetch timing covers the fetch and XHR requests the browser reports for the page's own site, not every + backend request; the RUM script's own requests are excluded. JavaScript errors are events, so errors per page view + is not a failure rate. +- Breakdown charts exist for the busiest values in the window, plus `other` for the rest (the `bucket` label). +- While the receiver is not serving, or `measure_sample_rate` is 0, the measurement charts stop; the receiver + availability, history and export charts continue. +- The event log and span charts exist only while that export is enabled, and the frustration chart only while + `capture.frustration_signals` is on. -The event-log (rum.otlp) and browser-span (rum.spans) charts and their loss alerts exist only while their respective -feature is enabled. sent counts records accepted by the receiver; errors counts records whose attempted delivery -failed or was rejected; dropped counts local queue or shutdown loss. Acceptance does not guarantee queryability -or durable storage. A timeout can have an unknown delivery outcome. Disablement and sampling do not count as loss. +### Per website -### Per site - -One configured site. +One configured website. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | +| display_name | The site's `display_name`, when it differs from the site key. | Metrics: | Metric | Description | Dimensions | Unit | |:------|:------------|:----------|:----| | rum.lcp | Largest Contentful Paint among recent observed document experiences | p50, p75, p95 | milliseconds | -| rum.lcp_population | Largest Contentful Paint observed population | observed, good, needs_improvement, poor, lost_reports | observations | +| rum.lcp_population | Largest Contentful Paint observed population | observed, good, needs_improvement, poor | observations | | rum.fcp | First Contentful Paint among recent observed document experiences | p50, p75, p95 | milliseconds | -| rum.fcp_population | First Contentful Paint observed population | observed, good, needs_improvement, poor, lost_reports | observations | +| rum.fcp_population | First Contentful Paint observed population | observed, good, needs_improvement, poor | observations | | rum.ttfb | Time to First Byte among recent observed document experiences | p50, p75, p95 | milliseconds | -| rum.ttfb_population | Time to First Byte observed population | observed, good, needs_improvement, poor, lost_reports | observations | +| rum.ttfb_population | Time to First Byte observed population | observed, good, needs_improvement, poor | observations | | rum.inp | Interaction to Next Paint among recent observed document experiences | p50, p75, p95 | milliseconds | -| rum.inp_population | Interaction to Next Paint observed population | observed, good, needs_improvement, poor, lost_reports | observations | +| rum.inp_population | Interaction to Next Paint observed population | observed, good, needs_improvement, poor | observations | | rum.cls | Cumulative Layout Shift among recent observed document experiences | p50, p75, p95 | score | -| rum.cls_population | Cumulative Layout Shift observed population | observed, good, needs_improvement, poor, lost_reports | observations | +| rum.cls_population | Cumulative Layout Shift observed population | observed, good, needs_improvement, poor | observations | | rum.load | Document load time | p50, p75, p95 | milliseconds | | rum.dom_content_loaded_handler | DOMContentLoaded handler duration | p50, p75, p95 | milliseconds | | rum.same_site_fetch | Same-site fetch and XHR duration | p50, p75, p95 | milliseconds | -| rum.load_population | Document load time observation population | observed, lost_reports | observations | -| rum.dom_content_loaded_handler_population | DOMContentLoaded handler duration observation population | observed, lost_reports | observations | -| rum.same_site_fetch_population | Same-site fetch and XHR duration observation population | observed, lost_reports | observations | +| rum.load_population | Document load time observation population | observed | observations | +| rum.dom_content_loaded_handler_population | DOMContentLoaded handler duration observation population | observed | observations | +| rum.same_site_fetch_population | Same-site fetch and XHR duration observation population | observed | observations | | rum.document_views | Document views | views | views/s | | rum.js_errors | JavaScript errors | errors | errors/s | | rum.observed_sessions | Sessions observed in the window | observed | sessions | | rum.window_totals | Document views, application views and JavaScript errors in the window | document_views, application_views, js_errors | events | | rum.frustration | Frustration heuristics | rage_clicks, dead_clicks, error_clicks | signals/s | | rum.application_views | Explicit application views | views | views/s | -| rum.measurement_loss | Retained capacity-loss evidence for window summaries | activity, sessions | reports | | rum.resources | Reported application resource entries | same_site, cross_site, unknown | entries/s | | rum.beacons | RUM beacons | accepted, rejected_origin, rejected_rate, rejected_size, invalid, bots | beacons/s | | rum.otlp | Event log export outcomes | sent, dropped, errors | records/s | | rum.history | RUM history writes | written, dropped | records/s | | rum.spans | Browser span export outcomes | sent, dropped, errors | spans/s | -| rum.samples_dropped | Reports lost from bounded measurement state | dropped | reports/s | | rum.ingress_state | RUM ingress availability | available, unavailable | state | | rum.invalid_measurements | Measurements without valid identity or revision | invalid | reports/s | -### Per site host +### Per website resource host -One configured site grouped by host. +One host that served resources to a website's pages, such as a CDN or API domain, among the busiest in the window. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | -| host | Resource host. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| display_name | The site's `display_name`, when it differs from the site key. | +| host | Host that served the resources. | +| bucket | `value` for a host charted on its own, `other` for the combined rest, `unknown` when the browser did not report the host. | Metrics: @@ -366,41 +653,40 @@ Metrics: |:------|:------------|:----------|:----| | rum.resource_host_p75 | Resource duration by host in the window | p75 | milliseconds | | rum.resource_host_count | Reported resource entries by host in the window | count | entries | -| rum.resource_host_population | Resource duration population by host | observed, lost_reports | observations | -| rum.resource_host_loss | Retained capacity-loss evidence for resource counts by host | lost_reports | reports | +| rum.resource_host_population | Resource duration population by host | observed | observations | -### Per site fingerprint +### Per website error group -One configured site grouped by fingerprint. +One group of identical JavaScript errors on a website, among the most frequent in the window. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | -| fingerprint | Error fingerprint. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| display_name | The site's `display_name`, when it differs from the site key. | +| fingerprint | Identifier of the error group. | +| message | Error message, cut to 80 characters. | +| bucket | `value` for a value charted on its own, `other` for the combined rest. | Metrics: | Metric | Description | Dimensions | Unit | |:------|:------------|:----------|:----| | rum.error_groups | JavaScript error reports by fingerprint in the window | errors | reports | -| rum.error_group_loss | Retained capacity-loss evidence for error fingerprints | lost_reports | reports | -### Per site browser +### Per website browser -One configured site grouped by browser. +One browser used by a website's visitors, among the busiest in the window. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | -| browser | Browser name. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| display_name | The site's `display_name`, when it differs from the site key. | +| browser | Browser name, such as Chrome. | +| bucket | `value` for a value charted on its own, `other` for the combined rest. | Metrics: @@ -414,20 +700,19 @@ Metrics: | rum.browser_document_views | Document views by browser in the window | views | views | | rum.browser_js_errors | JavaScript error reports by browser in the window | errors | reports | | rum.browser_vital_population | Web Vital observation populations by browser | lcp, fcp, ttfb, inp, cls | observations | -| rum.browser_loss | Retained capacity-loss evidence by browser | activity, lcp, fcp, ttfb, inp, cls | reports | -### Per site device +### Per website device type -One configured site grouped by device. +One device type of a website's visitors. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | -| device | Device class. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| display_name | The site's `display_name`, when it differs from the site key. | +| device | Device type - desktop, mobile, tablet or bot. | +| bucket | `value` for a value charted on its own, `other` for the combined rest. | Metrics: @@ -441,20 +726,19 @@ Metrics: | rum.device_document_views | Document views by device in the window | views | views | | rum.device_js_errors | JavaScript error reports by device in the window | errors | reports | | rum.device_vital_population | Web Vital observation populations by device | lcp, fcp, ttfb, inp, cls | observations | -| rum.device_loss | Retained capacity-loss evidence by device | activity, lcp, fcp, ttfb, inp, cls | reports | -### Per site country +### Per website country -One configured site grouped by country. +One country of a website's visitors, among the busiest in the window. Requires geolocation. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | -| country | Country code. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| display_name | The site's `display_name`, when it differs from the site key. | +| country | Two-letter country code. | +| bucket | `value` for a value charted on its own, `other` for the combined rest. | Metrics: @@ -468,20 +752,19 @@ Metrics: | rum.country_document_views | Document views by country in the window | views | views | | rum.country_js_errors | JavaScript error reports by country in the window | errors | reports | | rum.country_vital_population | Web Vital observation populations by country | lcp, fcp, ttfb, inp, cls | observations | -| rum.country_loss | Retained capacity-loss evidence by country | activity, lcp, fcp, ttfb, inp, cls | reports | -### Per site page +### Per website page -One configured site grouped by page. +One page of a website, as its path with IDs replaced, among the busiest in the window. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | -| page | Normalized document-entry path. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| display_name | The site's `display_name`, when it differs from the site key. | +| page | Page path, with IDs replaced. | +| bucket | `value` for a value charted on its own, `other` for the combined rest. | Metrics: @@ -495,20 +778,19 @@ Metrics: | rum.page_document_views | Document views by page in the window | views | views | | rum.page_js_errors | JavaScript error reports by page in the window | errors | reports | | rum.page_vital_population | Web Vital observation populations by page | lcp, fcp, ttfb, inp, cls | observations | -| rum.page_loss | Retained capacity-loss evidence by page | activity, lcp, fcp, ttfb, inp, cls | reports | -### Per site version +### Per website application version -One configured site grouped by version. +One application version of a website, as set by `data-version` on the script tag, among the busiest in the window. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | +| display_name | The site's `display_name`, when it differs from the site key. | | version | Application version. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| bucket | `value` for a value charted on its own, `other` for the combined rest. | Metrics: @@ -522,45 +804,57 @@ Metrics: | rum.version_document_views | Document views by version in the window | views | views | | rum.version_js_errors | JavaScript error reports by version in the window | errors | reports | | rum.version_vital_population | Web Vital observation populations by version | lcp, fcp, ttfb, inp, cls | observations | -| rum.version_loss | Retained capacity-loss evidence by version | activity, lcp, fcp, ttfb, inp, cls | reports | -### Per site view +### Per website application view -One configured site grouped by view. +One application view (route) of a website, among the busiest in the window. Labels: | Label | Description | |:-----------|:----------------| -| display_name | Optional human-readable site name, present when display_name differs from the native site job name. | -| view | Normalized application-view label. | -| bucket | value for a reported label; other for the pooled complement; unknown for unavailable resource hosts. | +| display_name | The site's `display_name`, when it differs from the site key. | +| view | Application view name. | +| bucket | `value` for a value charted on its own, `other` for the combined rest. | Metrics: | Metric | Description | Dimensions | Unit | |:------|:------------|:----------|:----| | rum.view_activity | Explicit application views and error reports in the window | views, errors | events | -| rum.view_loss | Retained capacity-loss evidence by application view | lost_reports | reports | ## 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. +These Functions show each site's setup and status, its recent activity, and the saved session history. They serve +every site on the Agent and are available while it has an active site or saved RUM history, so history stays readable +after a site is removed. + +Viewing them requires a signed-in member of the node's Netdata Cloud Space with permission to view sensitive data, on a +paid plan or an active trial. Reports are received and history is kept on every plan. + +To narrow the results to one virtual node, pass `vnode` with its configured name, or `vnode_guid` with its GUID for a +virtual node that was renamed or removed. Pass `site` for one site. + +The plugin-wide `dem-history-status` Function covers the history that RUM and synthetic monitoring share. It is +available whenever the plugin runs, needs the same access and takes no parameters. It shows the retention in +effect (`history` in `dem.conf`), how much disk the history files use, and the latest cleanup, write or +configuration reload error. + ### RUM Sites -Inspect site setup, sampling, receiver availability and recent activity to diagnose missing browser data. +The setup and status of each site - the script tag to install, the allowed origins, the sampling and capture settings, and recent traffic, including the last accepted report and the last refused origin. Start here when a site shows no data. | Aspect | Description | |:-------|:------------| | Name | `Rum-sites` | -| Require Cloud | no | -| Performance | Reads bounded local activity snapshots without contacting the monitored website. | -| Security | Results can include page paths, browser metadata, user identifiers, error messages and stack traces. Restrict access to authorized operators. | -| Availability | Available while dem.plugin is running; activity comes from admitted site jobs. | +| Require Cloud | yes | +| Performance | Reads the sites' current state in memory. Contacts no website. | +| Security | Shows site settings, origins and traffic counts. | +| Availability | While the Agent has an active site or saved RUM history. | #### Prerequisites @@ -568,52 +862,62 @@ No additional configuration is required. #### Parameters -This function has no parameters. +| Parameter | Type | Description | Required | Default | Options | +|:---------|:-----|:------------|:--------:|:--------|:--------| +| Virtual node name (`vnode`) | string | Only sites of the configured virtual node with this name. An empty or unknown name is an error. Do not combine with `vnode_guid`. | no | | | +| Virtual node GUID (`vnode_guid`) | string | Only data recorded under the virtual node with this GUID. Do not combine with `vnode`. | no | | | +| Site (`site`) | string | Only this site, by its site key. | no | | | #### Returns -One admitted site job. The response also includes collector public URL and ingress availability. +One row per active site. The response also shows whether the receiver is serving, its public URL and the state +of its location database (`collector.geoip`). In that object, `selection` is `auto` (empty `geoip_db`) or +`explicit`, `state` is `loaded`, `unavailable` or `using_previous`, `source` is `cache`, `stock` or +`explicit`, `database_type` is the database's declared type, and `reason` explains a missing database +without paths (the Agent log has the details). `lookup_errors` counts failed lookups, not unmatched addresses, and +`loaded` does not mean the database is current or complete. Its times (`build_at`, `loaded_at`, +`last_checked_at`) are Unix microseconds. + | Column | Type | Unit | Visibility | Description | |:-------|:-----|:-----|:-----------|:------------| -| site | string | | | Site. | -| name | string | | | Name. | -| generation | string | | | Receiving runtime identity; does not identify the browser policy revision. | -| collection_enabled | boolean | | | Whether current site policy permits measurement collection. | -| script_url | string | | | External script URL from explicit configuration; null when no public URL is configured. | -| snippet | string | | | Copyable external script tag; null when no public URL is configured. | -| allowed_origins | string | | | Allowed Origins. | -| beacons_per_min | integer | | | Accepted payloads in the last minute; not visitors or durable history records. | -| last_beacon_at | timestamp | | | Last accepted payload time in Unix microseconds; null when none has been accepted by this runtime. | -| last_beacon_age_s | integer | | | Seconds since the last accepted payload; null when none has been accepted by this runtime. | -| observed_sessions | integer | | | Distinct browser session identities observed within the measurement window; not concurrent users. | -| pageviews_window | integer | | | Explicit document activations in the window. | -| js_errors_window | integer | | | JS Errors (window). | -| rejected_per_min | integer | | | Origin, rate and size rejections in the last minute; excludes invalid payloads and bot exclusions. | -| measured | string | | | Measured. | -| investigated | string | | | Investigated. | -| investigated_sessions | integer | | | Sessions currently tracked for investigation; separate from observed measurement-window sessions. | -| bots_per_min | integer | | | Bots Filtered / min. | -| last_rejected_origin | string | | | Last observed rejected origin, including preflight requests; not a recommendation to allow it. | -| last_rejected_at | timestamp | | | Last rejected-origin observation time in Unix microseconds; null when none was observed. | -| last_rejected_age_s | integer | | | Seconds since the last rejected-origin observation; null when none was observed. | -| capture_geolocation | string | | | Current Geolocation Capture. | -| capture_frustration_signals | boolean | | | Current Frustration Capture. | -| application_views_window | integer | | | Explicit application-view occurrences in the window. | -| window_lost | integer | | | Retained capacity-loss evidence; affected measurements are unavailable. | -| sessions_lost | integer | | | Retained capacity-loss evidence; affected measurements are unavailable. | +| site | string | | | Site key. | +| name | string | | | Display name, or the site key. | +| generation | string | | | Identifier of the running site job. It changes when the job restarts. | +| collection_enabled | boolean | | | Whether `measure_sample_rate` is above 0, whatever the receiver's state. | +| script_url | string | | | URL of the site's script. Null until the receiver or the site has a `public_url`. | +| snippet | string | | | Script tag to add to the website. Null until the receiver or the site has a `public_url`. | +| allowed_origins | string | | | Origins the site accepts reports from. | +| beacons_per_min | integer | | | Reports accepted in the last minute. | +| last_beacon_at | timestamp | | | When the last report was accepted. Null when none since the job started. | +| last_beacon_age_s | integer | | | Seconds since the last accepted report. | +| observed_sessions | integer | | | Browser sessions seen in the window, not people or concurrent visitors. Null while collection is off or the receiver is not serving. | +| pageviews_window | integer | | | Page views in the window. | +| js_errors_window | integer | | | JavaScript errors in the window. | +| rejected_per_min | integer | | | Reports refused in the last minute for origin, rate or size. | +| measured | string | | | Current collection rate, from `measure_sample_rate`. | +| investigated | string | | | Current share of sessions saved with details, from `investigate`. | +| investigated_sessions | integer | | | Sessions currently tracked for saving. | +| bots_per_min | integer | | | Reports from automated browsers dropped in the last minute. | +| last_rejected_origin | string | | | Last origin whose reports were refused. Check it before adding it to `allowed_origins`. | +| last_rejected_at | timestamp | | | When that origin was refused. | +| last_rejected_age_s | integer | | | Seconds since that origin was refused. | +| capture_geolocation | string | | | Current `capture.geolocation` setting. | +| capture_frustration_signals | boolean | | | Current `capture.frustration_signals` setting. | +| application_views_window | integer | | | Application views in the window. | +| vnode_guid | string | | | GUID of the virtual node the data was recorded under. Empty when it had none. | ### RUM Pages -Compare document-entry pages using recent observed traffic, Web Vital populations and attributed elements. +Every page of each site seen in the window, with its traffic, Web Vital p75 values and the page elements most often involved in poor LCP, INP and CLS. It lists all pages, not only the busiest ones that get breakdown charts. | Aspect | Description | |:-------|:------------| | Name | `Rum-pages` | -| Require Cloud | no | -| Performance | Reads bounded local activity snapshots without contacting the monitored website. | -| Security | Results can include page paths, browser metadata, user identifiers, error messages and stack traces. Restrict access to authorized operators. | -| Availability | Available while dem.plugin is running; activity comes from admitted site jobs. | +| Require Cloud | yes | +| Performance | Reads the sites' current measurements in memory. Contacts no website. | +| Security | Shows page paths and page element selectors. | +| Availability | While the Agent has an active site or saved RUM history. | #### Prerequisites @@ -623,47 +927,45 @@ No additional configuration is required. | Parameter | Type | Description | Required | Default | Options | |:---------|:-----|:------------|:--------:|:--------|:--------| -| site | string | Filter by native site job name. Leave empty to include all sites. | no | | | +| Virtual node name (`vnode`) | string | Only sites of the configured virtual node with this name. An empty or unknown name is an error. Do not combine with `vnode_guid`. | no | | | +| Virtual node GUID (`vnode_guid`) | string | Only data recorded under the virtual node with this GUID. Do not combine with `vnode`. | no | | | +| Site (`site`) | string | Only this site, by its site key. | no | | | #### 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. +One row per site and page. A vital without observations is null. | Column | Type | Unit | Visibility | Description | |:-------|:-----|:-----|:-----------|:------------| -| site | string | | | Site. | -| page | string | | | Page. | -| pageviews_window | integer | | | Explicit document activations in the window. | -| sessions | integer | | | Distinct browser session identities observed within the window. | -| lcp_p75_ms | integer | | | LCP p75 (ms). | -| inp_p75_ms | integer | | | INP p75 (ms). | -| cls_p75 | float | | | CLS p75. | -| errors_window | integer | | | JS Errors (window). | -| lcp_element | string | | | LCP Element. | -| inp_element | string | | | INP Element. | -| cls_element | string | | | CLS Element. | -| frustration_window | integer | | | Frustration Signals (window). | -| row_id | string | | hidden | Stable row identity scoped to the site; the visible values remain available for filtering. | -| lcp_samples | integer | | | Retained observations for LCP. | -| inp_samples | integer | | | Retained observations for INP. | -| cls_samples | integer | | | Retained observations for CLS. | -| lcp_lost | integer | | | Retained capacity-loss evidence; affected measurements are unavailable. | -| inp_lost | integer | | | Retained capacity-loss evidence; affected measurements are unavailable. | -| cls_lost | integer | | | Retained capacity-loss evidence; affected measurements are unavailable. | -| window_lost | integer | | | Retained capacity-loss evidence; affected measurements are unavailable. | -| sessions_lost | integer | | | Retained capacity-loss evidence; affected measurements are unavailable. | +| site | string | | | Site key. | +| page | string | | | Page path, with IDs replaced. | +| pageviews_window | integer | | | Page views in the window. | +| sessions | integer | | | Browser sessions that viewed the page in the window. | +| lcp_p75_ms | integer | | | Largest Contentful Paint, p75, in milliseconds. | +| inp_p75_ms | integer | | | Interaction to Next Paint, p75, in milliseconds. | +| cls_p75 | float | | | Cumulative Layout Shift, p75. | +| errors_window | integer | | | JavaScript errors in the window. | +| lcp_element | string | | | Page element most often involved in poor LCP, or in any LCP when none was poor. | +| inp_element | string | | | Page element most often involved in poor INP, or in any INP when none was poor. | +| cls_element | string | | | Page element most often involved in poor CLS, or in any CLS when none was poor. | +| frustration_window | integer | | | Frustration signals in the window. Null when they are not collected. | +| row_id | string | | hidden | Stable row identifier. | +| lcp_samples | integer | | | LCP observations behind the p75. | +| inp_samples | integer | | | INP observations behind the p75. | +| cls_samples | integer | | | CLS observations behind the p75. | +| vnode_guid | string | | | GUID of the virtual node the data was recorded under. Empty when it had none. | ### RUM Live -Read recent browser events for live activity views, optionally continuing from a previous response. +The most recent events of each site as they arrive - page views, application views, Web Vital reports and errors, with page, browser, device and location. Pass the `next` value of a response as `cursor` to get only newer events. | Aspect | Description | |:-------|:------------| | Name | `Rum-live` | -| Require Cloud | no | -| Performance | Reads bounded local activity snapshots without contacting the monitored website. | -| Security | Results can include page paths, browser metadata, user identifiers, error messages and stack traces. Restrict access to authorized operators. | -| Availability | Available while dem.plugin is running; activity comes from admitted site jobs. | +| Require Cloud | yes | +| Performance | Reads recent events from memory, up to 2000 per request. Contacts no website. | +| Security | Shows page paths, browsers, devices, locations and error messages of visitors. | +| Availability | While the Agent has an active site or saved RUM history. | #### Prerequisites @@ -673,51 +975,54 @@ No additional configuration is required. | Parameter | Type | Description | Required | Default | Options | |:---------|:-----|:------------|:--------:|:--------|:--------| -| site | string | Filter by native site job name. Leave empty to include all sites. | no | | | -| after | string | Opaque next cursor from the previous rum-live response. Pass it unchanged; leave empty for recent events. | no | | | +| Virtual node name (`vnode`) | string | Only sites of the configured virtual node with this name. An empty or unknown name is an error. Do not combine with `vnode_guid`. | no | | | +| Virtual node GUID (`vnode_guid`) | string | Only data recorded under the virtual node with this GUID. Do not combine with `vnode`. | no | | | +| Site (`site`) | string | Only this site, by its site key. | no | | | +| Cursor (`cursor`) | string | The `next` value of the previous response, unchanged. Empty returns the most recent events. The cursor keeps a position for each site, so a busy site never skips a quiet site's events; a site whose job restarted or was replaced starts a new stream, from that job's first events. | no | | | #### Returns -Recent observation rows. Vital revisions update the same document metric; rows are not independent document views. +One row per event, up to 2000 per request. Each site keeps its last 5,000 events in memory. A Web Vital can be reported more than once for the same page view; later reports update it. | Column | Type | Unit | Visibility | Description | |:-------|:-----|:-----|:-----------|:------------| -| seq | string | | | Event. | -| ts | timestamp | | | Time. | -| site | string | | | Site. | -| country | string | | | Country. | -| city | string | | | City. | -| lat | float | | | Latitude. | -| lon | float | | | Longitude. | -| page | string | | | Page. | -| browser | string | | | Browser. | -| device | string | | | Device. | -| pageview | integer | | | Explicit document activation. | -| lcp_ms | float | | | LCP (ms). | -| inp_ms | float | | | INP (ms). | -| fcp_ms | float | | | FCP (ms). | -| ttfb_ms | float | | | TTFB (ms). | -| cls | float | | | CLS. | -| errors | integer | | | JS Errors. | -| kind | string | | | Observation kind; one vital row represents one metric report. | -| experience_id | string | | | Document activation identity, independent of session and application view. | -| view | string | | | Application view when this report was created. | -| view_id | string | | | Application-view occurrence identity. | -| vital | string | | | Web Vital reported by this row. | -| metric_id | string | | | Browser SDK metric identity. | -| revision | integer | | | Increasing report revision within this metric or event identity. | +| seq | string | | | Event ID. | +| ts | timestamp | | | When the receiver got the event. | +| site | string | | | Site key. | +| country | string | | | Visitor's country. | +| city | string | | | Visitor's approximate city, with `capture.geolocation: city`. | +| lat | float | | | Approximate latitude, with `capture.geolocation: city`. | +| lon | float | | | Approximate longitude, with `capture.geolocation: city`. | +| page | string | | | Page path, with IDs replaced. | +| browser | string | | | Browser name. | +| device | string | | | Device type. | +| pageview | integer | | | 1 for a page view. | +| lcp_ms | float | | | Largest Contentful Paint, in milliseconds. | +| inp_ms | float | | | Interaction to Next Paint, in milliseconds. | +| fcp_ms | float | | | First Contentful Paint, in milliseconds. | +| ttfb_ms | float | | | Time to First Byte, in milliseconds. | +| cls | float | | | Cumulative Layout Shift. | +| errors | integer | | | JavaScript errors. | +| kind | string | | | Event type, such as a page view, application view, Web Vital or error. | +| experience_id | string | | | Page view the event belongs to. | +| view | string | | | Application view at the time of the event. | +| view_id | string | | | Application view occurrence the event belongs to. | +| vital | string | | | Web Vital that a vital event reports. | +| metric_id | string | | | Identifier of the reported Web Vital measurement. | +| revision | integer | | | Report number of that measurement; a higher number replaces a lower one. | +| vnode_guid | string | | | GUID of the virtual node the data was recorded under. Empty when it had none. | ### RUM Sessions -Investigate sampled sessions with retained observations received within a time range, including pages, errors and optional interaction heuristics. +The saved sessions with activity in a time range (the last 15 minutes by default), with their pages, errors, browser, device, country and application version. Find a user's sessions with `user_id`, then open a session's timeline. | Aspect | Description | |:-------|:------------| | Name | `Rum-sessions` | -| Require Cloud | no | -| Performance | Reads local retained history; work grows with the selected range and retained records. | -| Security | Results can include page paths, browser metadata, user identifiers, error messages and stack traces. Restrict access to authorized operators. | -| Availability | Available while dem.plugin is running. History results require retained investigation data. | +| Require Cloud | yes | +| Performance | Reads the saved history from disk; wider time ranges and busier sites take longer. Contacts no website. | +| Security | Shows user IDs, page paths, browsers, devices and countries of visitors. | +| Availability | While the Agent has an active site or saved RUM history. | #### Prerequisites @@ -727,46 +1032,49 @@ No additional configuration is required. | Parameter | Type | Description | Required | Default | Options | |:---------|:-----|:------------|:--------:|:--------|:--------| -| site | string | Filter by native site job name. Leave empty to include all sites. | no | | | -| user_id | string | Exact application user ID observed in retained events in the selected range. Leave empty to include all sessions. | no | | | -| after | integer | Inclusive Agent receipt-time lower bound in Unix seconds; zero is epoch and negative values are offsets from now. | no | 15 minutes before before, clamped to epoch | | -| before | integer | Inclusive Agent receipt-time upper bound in Unix seconds; zero is epoch and negative values are offsets from now. | no | now | | +| Virtual node name (`vnode`) | string | Only sites of the configured virtual node with this name. An empty or unknown name is an error. Do not combine with `vnode_guid`. | no | | | +| Virtual node GUID (`vnode_guid`) | string | Only data recorded under the virtual node with this GUID. Do not combine with `vnode`. | no | | | +| Site (`site`) | string | Only this site, by its site key. | no | | | +| User ID (`user_id`) | string | Only sessions in which the application set this user ID during the time range. The match is exact, on the ID as stored after DEM shortens or masks it, so a displayed `[REDACTED]` value cannot be used to look a user up. | no | | | +| Received after (`after`) | integer | Start of the time range, in Unix seconds, or seconds before now when negative (`-3600` for the last hour). | no | 15 minutes before `before` | | +| Received before (`before`) | integer | End of the time range, in Unix seconds, or seconds before now when negative. | no | now | | #### Returns -One session with retained observations originally received by the Agent in the selected range. Counts and activity span cover selected observations, not lifetime totals. Sessions are ordered by last selected observation at microsecond precision. Late-saved context can change an earlier range. Results can include disabled sites until their history expires. +One row per session, most recently active first, up to 2000; the response sets `truncated` when more match. Counts and times cover the session's activity inside the time range, not its whole life. | Column | Type | Unit | Visibility | Description | |:-------|:-----|:-----|:-----------|:------------| -| site | string | | | Site. | -| session_id | string | | | Session. | -| started_age_s | integer | | | First Selected Observation (s ago). | -| duration_s | integer | | | Selected Observation Span (s). | -| pageviews | integer | | | Retained document activations. | -| errors | integer | | | JS Errors. | -| browser | string | | | Browser. | -| device | string | | | Device. | -| country | string | | | Country. | -| version | string | | | Version. | -| entry_page | string | | | Entry Page. | -| last_page | string | | | Last Page. | -| user_ids | array | | | Observed User IDs. | -| frustrations | integer | | | Retained Frustration Signals. | -| row_id | string | | hidden | Stable row identity scoped to the site; the visible values remain available for filtering. | -| application_views | integer | | | Retained application-view occurrences. | -| last_observed_us | timestamp | | | Last Selected Observation in Unix microseconds; default descending sort. | +| site | string | | | Site key. | +| session_id | string | | | Session ID. | +| started_age_s | integer | | | Seconds since the session's first activity in the range. | +| duration_s | integer | | | Seconds between the session's first and last activity in the range. | +| pageviews | integer | | | Page views. | +| errors | integer | | | JavaScript errors. | +| browser | string | | | Browser name. | +| device | string | | | Device type. | +| country | string | | | Visitor's country. | +| version | string | | | Application version. | +| entry_page | string | | | First page in the range. | +| last_page | string | | | Last page in the range. | +| user_ids | array | | | User IDs the application set. | +| frustrations | integer | | | Frustration signals. | +| row_id | string | | hidden | Stable row identifier. | +| application_views | integer | | | Application views. | +| last_observed_us | timestamp | | | When the session was last active in the range. | +| vnode_guid | string | | | GUID of the virtual node the data was recorded under. Empty when it had none. | ### RUM Errors -Group errors originally received by the Agent in the selected range by fingerprint; select a fingerprint to investigate affected sessions, pages and browsers. +JavaScript errors of saved sessions in a time range (the last 15 minutes by default), grouped by fingerprint, with counts and a sample stack. Select a `fingerprint` to see how many sessions it affected, its top page and the browsers it occurs in. | Aspect | Description | |:-------|:------------| | Name | `Rum-errors` | -| Require Cloud | no | -| Performance | Reads local retained history; work grows with the selected range and retained records. | -| Security | Results can include page paths, browser metadata, user identifiers, error messages and stack traces. Restrict access to authorized operators. | -| Availability | Available while dem.plugin is running. History results require retained investigation data. | +| Require Cloud | yes | +| Performance | Reads the saved history from disk; wider time ranges and busier sites take longer. Contacts no website. | +| Security | Shows error messages, stack traces and page paths, which can contain sensitive text. | +| Availability | While the Agent has an active site or saved RUM history. | #### Prerequisites @@ -776,41 +1084,44 @@ No additional configuration is required. | Parameter | Type | Description | Required | Default | Options | |:---------|:-----|:------------|:--------:|:--------|:--------| -| site | string | Filter by native site job name. Leave empty to include all sites. | no | | | -| fingerprint | string | Select an error fingerprint to compute affected-session, top-page and browser statistics. Leave empty for the count overview. | no | | | -| after | integer | Inclusive Agent receipt-time lower bound in Unix seconds; zero is epoch and negative values are offsets from now. | no | 15 minutes before before, clamped to epoch | | -| before | integer | Inclusive Agent receipt-time upper bound in Unix seconds; zero is epoch and negative values are offsets from now. | no | now | | +| Virtual node name (`vnode`) | string | Only sites of the configured virtual node with this name. An empty or unknown name is an error. Do not combine with `vnode_guid`. | no | | | +| Virtual node GUID (`vnode_guid`) | string | Only data recorded under the virtual node with this GUID. Do not combine with `vnode`. | no | | | +| Site (`site`) | string | Only this site, by its site key. | no | | | +| Fingerprint (`fingerprint`) | string | Error group to analyze in detail. Empty lists all groups. | no | | | +| Received after (`after`) | integer | Start of the time range, in Unix seconds, or seconds before now when negative (`-3600` for the last hour). | no | 15 minutes before `before` | | +| Received before (`before`) | integer | End of the time range, in Unix seconds, or seconds before now when negative. | no | now | | #### Returns -One error fingerprint per site with observations originally received by the Agent in the selected range. Affected-session, page and browser statistics are null until a fingerprint is selected; first and last observations use Agent receipt time. Results can include disabled sites until their history expires. +One row per site and error group. The affected sessions, top page and browsers are filled in only for the selected `fingerprint`. | Column | Type | Unit | Visibility | Description | |:-------|:-----|:-----|:-----------|:------------| -| site | string | | | Site. | -| fingerprint | string | | | Fingerprint. | -| type | string | | | Type. | -| message | string | | | Message. | -| count_window | integer | | | Count (window). | -| sessions_affected | integer | | | Sessions Affected (selected fingerprint). | -| first_seen_age_s | integer | | | First Selected Observation (s ago). | -| last_seen_age_s | integer | | | Last Selected Observation (s ago). | -| top_page | string | | | Top Page (selected fingerprint). | -| browsers | string | | | Browsers (selected fingerprint). | -| sample_stack | string | | | Sample Stack. | -| row_id | string | | hidden | Stable row identity scoped to the site; the visible values remain available for filtering. | +| site | string | | | Site key. | +| fingerprint | string | | | Error group identifier. | +| type | string | | | Error type. | +| message | string | | | Error message. | +| count_window | integer | | | Occurrences in the time range. | +| sessions_affected | integer | | | Sessions with the error, for the selected fingerprint. | +| first_seen_age_s | integer | | | Seconds since the first occurrence in the range. | +| last_seen_age_s | integer | | | Seconds since the last occurrence in the range. | +| top_page | string | | | Page where the error occurs most, for the selected fingerprint. | +| browsers | string | | | Browsers the error occurs in, for the selected fingerprint. | +| sample_stack | string | | | Stack trace of one occurrence. | +| row_id | string | | hidden | Stable row identifier. | +| vnode_guid | string | | | GUID of the virtual node the data was recorded under. Empty when it had none. | ### RUM Session Events -Read the retained event timeline for a session to follow navigation, errors and traced requests. +The timeline of one session - its page views, application views, errors and other events in order, including events not yet saved, with the trace ID of traced requests. | Aspect | Description | |:-------|:------------| | Name | `Rum-session-events` | -| Require Cloud | no | -| Performance | Reads local retained history; work grows with the selected range and retained records. | -| Security | Results can include page paths, browser metadata, user identifiers, error messages and stack traces. Restrict access to authorized operators. | -| Availability | Available while dem.plugin is running. History results require retained investigation data. | +| Require Cloud | yes | +| Performance | Reads one session from disk and memory. Contacts no website. | +| Security | Shows user IDs, page paths and error messages of one visitor's session. | +| Availability | While the Agent has an active site or saved RUM history. | #### Prerequisites @@ -820,37 +1131,336 @@ No additional configuration is required. | Parameter | Type | Description | Required | Default | Options | |:---------|:-----|:------------|:--------:|:--------|:--------| -| site | string | Filter by native site job name. Leave empty to include all sites. | no | | | -| session_id | string | Session identifier returned by rum-sessions. Specify site when the same session identifier exists on multiple sites. | yes | | | +| Virtual node name (`vnode`) | string | Only sites of the configured virtual node with this name. An empty or unknown name is an error. Do not combine with `vnode_guid`. | no | | | +| Virtual node GUID (`vnode_guid`) | string | Only data recorded under the virtual node with this GUID. Do not combine with `vnode`. | no | | | +| Site (`site`) | string | The session's site key. Needed when the same session ID exists on several sites. | no | | | +| Session (`session_id`) | string | Session ID, from `rum-sessions`. | yes | | | #### Returns -One retained or pending session event, with Agent receipt time in Unix microseconds and an optional trace identifier. The available session timeline is returned without range filtering. Activity-only observations contribute to summaries, not this timeline. Unknown sessions return an error. +One row per event, oldest first, for the whole saved session regardless of time range. An unknown session returns an error. | Column | Type | Unit | Visibility | Description | |:-------|:-----|:-----|:-----------|:------------| -| ts | timestamp | | | Time. | -| type | string | | | Event. | -| page | string | | | Page. | -| text | string | | | Details. | -| trace_id | string | | | Trace. | -| user_id | string | | | User ID at Event. | -| experience_id | string | | | Document activation identity, independent of session and application view. | -| view | string | | | Application view when this report was created. | -| view_id | string | | | Application-view occurrence identity. | -| metric_id | string | | | Browser SDK metric identity. | -| revision | integer | | | Increasing report revision within this metric or event identity. | +| ts | timestamp | | | When the receiver got the event. | +| type | string | | | Event type. | +| page | string | | | Page path, with IDs replaced. | +| text | string | | | Event details, such as the error message. | +| trace_id | string | | | Trace ID of a traced request. | +| user_id | string | | | User ID the application had set at the time. | +| experience_id | string | | | Page view the event belongs to. | +| view | string | | | Application view at the time of the event. | +| view_id | string | | | Application view occurrence the event belongs to. | +| metric_id | string | | | Identifier of the reported Web Vital measurement. | +| revision | integer | | | Report number of that measurement. | +| vnode_guid | string | | | GUID of the virtual node the data was recorded under. Empty when it had none. | ## Troubleshooting -### Other Problems +### 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. + + +#### Netdata RUM: cannot load the core SDK. Check the browser Network and CSP errors for the RUM script requests. + +**Cause** + +The browser console shows this when the page cannot load the SDK from the receiver: the reverse proxy does not forward the whole `/rum/` path, or the page's Content Security Policy blocks the receiver's address. + +**Fix** + +Check the failing request in the browser's Network panel. Forward every path under `/rum/` to the receiver, and allow the receiver's address in `script-src` and `connect-src`. If several Agents answer for the same public address, run the same Agent version on all of them, so each serves the SDK files the script refers to. + +#### Netdata RUM: cannot load the tracing SDK. Check the browser Network and CSP errors for the RUM script requests. + +**When** + +`tracing` is enabled for the site. + +**Cause** + +The page could not load the tracing bundle from the receiver, for the same reasons as the core SDK. RUM keeps working without browser spans. + +**Fix** + +Check the failing request in the browser's Network panel. Forward every path under `/rum/` to the receiver, and allow the receiver's address in the page's Content Security Policy. + +#### Netdata RUM: cannot determine receiver URL. Use the external script tag from RUM setup. + +**Cause** + +The script's contents were pasted into the page, or a tag manager runs them as code, instead of loading them with an external script tag. + +**Fix** + +Add the `