Browser Journey
Plugin: dem.plugin Module: journey
Overview
Run scripted browser journeys against your website on a schedule and get alerted when a critical workflow, such as logging in or checking out, breaks.
Each job runs one Playwright Test file in a real Chromium browser and gives you:
- The outcome of every run, with the number of tests that passed, failed, timed out, were skipped or did not run.
- How long each run took and how old the latest result is.
- An alert when the latest run fails or times out.
- A run history with the first failing test, the step it failed in, its source line and error message.
- Optionally, a screenshot and a Playwright trace of each failure, and a count of the browser errors (uncaught exceptions, console errors, failed requests and HTTP error responses) seen during every run.
Every check_every seconds (15 minutes by default), the Agent starts a fresh, sandboxed Chromium browser on
this host and runs the job's Playwright Test file in it, with one worker and no retries. The browser reaches
your website over the network, like a visitor would.
Everything the script does is real: form submissions, orders and account changes happen on the website and
are not rolled back. Point write actions at test accounts or a staging site. The Test action in the job
editor also runs the journey once, for real, without recording the result: a pass reports success, and a failure
shows the same failure summary that run history would, with browser error counts when browser_error_summary is
on. Test shares the browser with the running jobs, so it can wait for them and delay their checks.
Credentials reach the script as DEM_SECRET_* environment variables. The script and the secret values are
not stored in run history, and secret values are masked in recorded error text. Screenshots and traces are
kept as captured and can contain them.
This collector is only supported on the following platforms:
- Linux
This collector supports collecting metrics from multiple instances of this integration.
| Permission | Needed when |
|---|---|
The Netdata service account (usually netdata) can read the script_path file and every file it imports. | The job uses script_path. |
| The host lets an unprivileged process create the user namespaces Chromium's sandbox needs. | Always. Installing the browser runtime prepares this on hosts that restrict it, such as Ubuntu 24.04 (see Prerequisites). |
Browser jobs never run as root, and Chromium's sandbox stays enabled.
Browser Journey can be monitored further using the following other integrations:
Default Behavior
Auto-Detection
This integration doesn't support auto-detection.
Limits
- All journey and Lighthouse jobs on the Agent share
browser.concurrencyindem.conf, which runs one browser at a time by default. A check that comes due while the browser is busy waits; if it is still waiting when the job's next check comes due, it is skipped and counted as coalesced. - A result is fresh for two check intervals. After that the state chart shows
staleand the duration and test charts leave a gap until a new run completes. - Run history is shared with RUM and kept for about 30 days, or less once it would exceed 1 GiB, and captures
for 7 days, or less once they would exceed 2 GiB (
historyandartifactsindem.conf). History files of up to a day expire together, so runs can stay about a day longer. When the size limit is reached, the oldest entries go first. - Run diagnostics keep up to 500 test, step, error and output events per run and 2,000 characters per text, and count what they drop. HAR files, videos and filmstrips are not captured.
- A screenshot or trace larger than 5 MiB is not kept.
Performance Impact
Each run starts a new Chromium browser and Node.js process on the Agent host, which use CPU and memory for as long as the run lasts; heavier pages and longer scripts cost more. The website receives every request the script makes.
- Raise
check_everyto run less often.update_everyonly refreshes the charts and starts no browser. browser.concurrencyindem.conflimits how many browsers run at once; size it for the host's CPU and memory, and restart the Agent to apply it.trace_on_failurerecords a trace during every run, including runs that pass, which adds CPU, memory and temporary disk use.browser_error_summarycan add over a CPU-second and about 150 MiB of memory to a run on a page that logs thousands of console errors.
Setup
Prerequisites
Install the browser runtime
Journeys and Lighthouse audits run in a separately installed browser runtime (Node.js, Chromium, Playwright and Lighthouse). Netdata never installs it on its own, and a job waits until it is installed. It needs Linux on amd64 or arm64.
| Netdata installation | Install the runtime with |
|---|---|
| Native DEB or RPM packages | The optional netdata-dem-runtime package, installed with your package manager. It requires a running systemd host, stops the Agent during installation and restores its previous service state. |
| Static or source installation | kickstart.sh --install-dem-runtime during an install or update, or the installed helper: sudo /opt/netdata/usr/libexec/netdata/netdata-dem-runtime.sh install --agent /opt/netdata/usr/sbin/netdata --allow-download (static paths). |
| Docker (local, rootful) | kickstart.sh --install-dem-runtime --docker-container NAME, run on the Docker host. |
Static, source and Docker release builds default to the signed runtime matching the Agent version,
channel and architecture. runtime.release_url in dem.conf can override that URL. Setup also prepares
the host for Chromium's sandbox (an AppArmor allowance on Ubuntu 24.04). Installation verifies integrity
and version compatibility. Local runtime qualify is optional.
The browser runtime host setup guide covers offline installation, Docker requirements, updates and removal.
Restart Netdata to activate the runtime
A running Agent keeps the runtime it found when it started. After the first installation, restart the
Agent (sudo systemctl restart netdata) or the container (docker restart NAME). The native package
restores the previous service state for you. Later updates replace Agent and runtime as a matching
pair. Source/static installers coordinate that transition; Docker deployments must switch the pinned
image and runtime selection together. There is no separate daily runtime update.
To check the runtime, run as the Netdata service account:
sudo -u netdata /usr/libexec/netdata/plugins.d/dem.plugin runtime status
sudo -u netdata /usr/libexec/netdata/plugins.d/dem.plugin runtime qualify
qualify runs a test journey and a Lighthouse audit. Static installations keep the plugin under
/opt/netdata/usr/libexec/netdata/plugins.d/.
Configuration
Options
Each job is one journey. All options apply per job.
Configuration options
| Group | Option | Description | Default | Required |
|---|---|---|---|---|
| Journey | name | Job name. It identifies the journey in charts, alerts and run history, so renaming starts a separate history. | yes | |
| script | Playwright Test source code, in JavaScript or TypeScript. Set either this or script_path. | no | ||
| script_path | Absolute path to a Playwright Test file (.js, .ts, .mjs, .cjs, .mts or .cts) readable by the Netdata service account. Set either this or script. | no | ||
| Secrets | secrets[].name | Environment variable name for the script, starting with DEM_SECRET_ and followed by letters, digits or underscores. Names must be unique within the job. | no | |
| secrets[].value | Secret value. Prefer a secret reference, such as ${env:WORKFLOW_PASSWORD}, over a literal value. | no | ||
| Diagnosis | screenshot_on_failure | Save a screenshot when a test fails. Screenshots can show sensitive page content. | no | no |
| trace_on_failure | Save a Playwright trace when a test fails; requires failure screenshots. Traces can contain passwords, cookies and request and response bodies. | no | no | |
| browser_error_summary | Count uncaught exceptions, console errors, failed requests and HTTP error responses during every run, with a few samples of each. Adds CPU and memory use on pages that log heavily. | no | no | |
| Collection | check_every | How often to run the journey, in seconds. | 900 | no |
| update_every | How often to refresh the charts from the latest result, in seconds. Refreshing never starts a browser. | 10 | no | |
| timeout | Time limit for one run of the journey, in seconds. Time spent waiting for a free browser does not count. | 120 | no | |
| Virtual Node | vnode | Associates this job with a Virtual Node. | no |
script
The script can import @playwright/test, which the browser runtime provides. Every test in it runs
on each check, in declaration order. A run succeeds only when every declared test passes. When no test
fails but some are skipped (test.skip), marked as expected to fail (test.fail) or missing, the run
ends as inconclusive.
script_path
Use a file when the journey imports helpers or page objects from other files next to it. The file and its imports are read on every run, so edits take effect at the next check.
secrets[].name
The script reads the value with process.env, for example process.env.DEM_SECRET_PASSWORD.
trace_on_failure
The trace records DOM snapshots, network activity and a visual timeline of the failing test. Recording runs during every run, including runs that pass, and adds CPU, memory and temporary disk use. Traces larger than 5 MiB are not kept.
Download a trace with the synthetics-artifact Function (administrator access), save the decoded bytes
as a .zip file and open it with the Playwright Trace Viewer.
Secrets are not masked inside traces, and a script can change what is recorded, for example with
test.use({ trace: 'on' }).
When a run times out, saving the trace can use up the time kept for recording the timeout, and the run can then lose its final report and screenshots. Traces never extend the time limit or cause a retry.
browser_error_summary
The counts and up to four samples per kind (at most three from each test) appear in the journey run history,
for runs that pass as well as runs that fail. Only pages opened through the test's page or context fixtures are observed; a
browser context the script creates itself is not. Samples can contain text from the page.
check_every
A new job runs its first check right away. The second comes one to two intervals later, at a point that
depends on the job name, so jobs created together do not all run at once. After that, checks follow
every check_every seconds.
timeout
The limit applies to the whole file and to each test in it. The last 5 seconds of it (one fifth of a
limit under 25 seconds) are kept for recording the timeout, so the tests have slightly less time. A run
that exceeds it ends as timeout. After the browser and its processes exit, saving captures and history
has up to 10 more seconds, and the run keeps its browser slot until then.
vnode
The job's charts and alerts appear under the virtual node instead of this Agent's host, which lets you
group the checks 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 clears the latest-result charts until the
next run; earlier runs keep the virtual node they ran under.
via File
The configuration file name for this integration is dem/journey.conf.
You can edit the configuration file using the edit-config script from the
Netdata config directory.
cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config dem/journey.conf
Examples
Check that a page loads
The minimal journey. It opens a page and checks its title every 15 minutes.
Config
jobs:
- name: home
script: |
import { test, expect } from '@playwright/test';
test('home page loads', async ({ page }) => {
await page.goto('https://example.org/');
await expect(page).toHaveTitle(/Example Domain/);
});
Log in with a stored password
Passes the password to the script as an environment variable, read from the Agent's environment.
Config
jobs:
- name: login
secrets:
- name: DEM_SECRET_PASSWORD
value: ${env:SHOP_TEST_PASSWORD}
script: |
import { test, expect } from '@playwright/test';
test('user can log in', async ({ page }) => {
await page.goto('https://shop.example.org/login');
await page.getByLabel('Email').fill('monitor@example.org');
await page.getByLabel('Password').fill(process.env.DEM_SECRET_PASSWORD);
await page.getByRole('button', { name: 'Log in' }).click();
await expect(page.getByRole('heading', { name: 'My account' })).toBeVisible();
});
Run a test file from disk
Runs a Playwright Test file that imports helpers from its own directory.
Config
jobs:
- name: checkout
script_path: /etc/netdata/dem/journeys/checkout.spec.ts
Keep evidence of failures
Saves a screenshot and a Playwright trace whenever a test fails, and checks every 5 minutes.
Config
jobs:
- name: checkout
script_path: /etc/netdata/dem/journeys/checkout.spec.ts
check_every: 300
screenshot_on_failure: true
trace_on_failure: true
Group checks under a virtual node
Shows the journey's charts and alerts under the shop virtual node, which must be defined first.
Config
jobs:
- name: checkout
vnode: shop
script_path: /etc/netdata/dem/journeys/checkout.spec.ts
Alerts
The following alerts are available:
| Alert name | On metric | Description |
|---|---|---|
| dem_journey_failed | dem_synthetic.execution_state | Latest fresh journey attempt failed or timed out for ${label:_collect_job} |
Metrics
Metrics grouped by scope.
The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
Each job has its own charts, under its virtual node when vnode is set and under this Agent's host otherwise.
The charts show the latest completed run until the next one finishes. When that result is older than two check
intervals, the state chart shows stale and the duration, test and Lighthouse charts leave a gap instead of
repeating it.
Changing a job's vnode clears the latest result until the first run under the new virtual node completes.
Per journey job
One configured journey.
This scope has no labels.
Metrics:
| Metric | Description | Dimensions | Unit |
|---|---|---|---|
| dem_synthetic.execution_state | Latest synthetic observation state | unknown, success, failed, timeout, inconclusive, error, cancelled, stale | state |
| dem_synthetic.duration | Latest synthetic attempt duration | duration | milliseconds |
| dem_synthetic.observation_age | Age of latest synthetic observation | age | seconds |
| dem_synthetic.attempts | Completed synthetic attempts | success, failed, timeout, inconclusive, error, cancelled, unknown | attempts/s |
| dem_synthetic.occurrences | Synthetic scheduled occurrences | scheduled, admitted, coalesced | occurrences/s |
| dem_synthetic.scheduler_state | Synthetic active and pending attempts | active, pending | attempts |
| dem_synthetic.queue_age | Oldest synthetic admission wait | age | seconds |
| dem_synthetic.scheduling_delay | Latest synthetic admission delay from selected due time | delay | seconds |
| dem_synthetic.journey.declared_tests | Latest declared journey tests | declared | tests |
| dem_synthetic.journey.test_outcomes | Latest journey test outcomes | passed, failed, timed_out, skipped, expected_failure, not_run | tests |
Live Data
These Functions show the state of every journey and Lighthouse job on the Agent, their run history and their saved screenshots, traces and reports. They are available while the Agent has at least one active job, saved run or saved capture, so history stays readable after a job is removed. Run history has one Function per kind; the others serve both kinds.
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. Jobs run and their 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. Without either, every job is included, with or without a
virtual node.
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.
Synthetic monitors
The current status of every active journey and Lighthouse job - its latest result and whether it is still fresh, when it last succeeded and failed, and whether its checks are waiting for a free browser. Disabled jobs and jobs that failed to start are not listed; their status is in the job configuration.
| Aspect | Description |
|---|---|
| Name | Synthetics-checks |
| Require Cloud | yes |
| Performance | Reads the jobs' current state in memory. Starts no browser and contacts no website. |
| Security | Shows job names, audited URLs and error messages, which can contain sensitive text. |
| Availability | While the Agent has at least one active synthetic job, saved run or saved capture. |
Prerequisites
No additional configuration is required.
Parameters
| Parameter | Type | Description | Required | Default | Options |
|---|---|---|---|---|---|
Virtual node name (vnode) | string | Only jobs 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 jobs recorded under the virtual node with this GUID. Do not combine with vnode. | no | ||
Job (job_id) | string | Only this job, written as module and job name, such as journey:checkout or lighthouse:home. | no | ||
Kind (kind) | string | Only journey or only lighthouse jobs. | no | ||
Maximum rows (limit) | string | The maximum number of rows to return, from 1 to 2000. The response sets truncated when more rows match. | no | 2000 |
Returns
One row per active job.
| Column | Type | Unit | Visibility | Description |
|---|---|---|---|---|
| job_id | string | Module and job name, such as journey:checkout. | ||
| kind | string | journey or lighthouse. | ||
| name | string | Job name. | ||
| target | string | Audited URL of a Lighthouse job, without credentials. Empty for journeys. | ||
| state | string | The latest outcome; waiting or running while a check is in progress; stale when the latest result is older than two check intervals; unknown before the first result. | ||
| fresh | boolean | Whether the latest result is less than two check intervals old. | ||
| run_id | string | ID of the latest run. | ||
| outcome | string | Outcome of the latest run. | ||
| completed_us | timestamp | When the latest run finished. | ||
| duration_ms | float | ms | How long the latest run took. | |
| last_success_us | timestamp | When a run last succeeded, since the job started or moved to another virtual node. | ||
| last_failure_us | timestamp | When a run last failed or timed out, since the job started or moved to another virtual node. | ||
| error | string | Error message of the latest run. | ||
| history_error | string | Problem saving the latest run to the run history. | ||
| vnode_guid | string | GUID of the job's virtual node. Empty when it has none. | ||
| check_every | integer | s | Configured check interval. | |
| scheduled | integer | Checks that came due since the job started. | ||
| admitted | integer | Checks that got a browser and ran. | ||
| coalesced | integer | Checks skipped because the job's previous check was still waiting for a browser. | ||
| pending | boolean | Whether a check is waiting for a browser. | ||
| queue_age | float | s | How long the waiting check has waited. | |
| scheduling_delay | float | s | How long after its due time the latest check got a browser. |
Journey runs
The history of journey runs, newest first, with test counts, the first failure and its step, and the browser error counts. Use it to see when a journey started failing and why. Runs are selected by start time.
| Aspect | Description |
|---|---|
| Name | Synthetics-journey-runs |
| Require Cloud | yes |
| Performance | Reads the run history from disk, up to 2000 rows per request. Starts no browser and contacts no website. |
| Security | Rows can contain URLs, test and step titles, and error messages from the website, which can include sensitive text. |
| Availability | While the Agent has at least one active synthetic job, saved run or saved capture. |
Prerequisites
No additional configuration is required.
Parameters
| Parameter | Type | Description | Required | Default | Options |
|---|---|---|---|---|---|
Virtual node name (vnode) | string | Only jobs 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 jobs recorded under the virtual node with this GUID. Do not combine with vnode. | no | ||
Job (job_id) | string | Only runs of this journey, such as journey:checkout. | no | ||
Outcome (outcome) | string | Only runs with this outcome - success, failed, timeout, inconclusive, error, cancelled or unknown. | no | ||
Started after (after) | string | Only runs started at or after this time, in Unix seconds, or seconds before now when negative (-3600 for the last hour). Empty includes the whole history. | no | ||
Started before (before) | string | Only runs started at or before this time, in Unix seconds, or seconds before now when negative. Empty means now. | no | ||
Maximum rows (limit) | string | The maximum number of rows to return, from 1 to 2000. The response sets truncated when more rows match. | no | 2000 |
Returns
One row per run. The response reports the time range it used and sets truncated when more runs match than limit. Values a run did not report, such as test counts of a run that failed to start, are null.
| Column | Type | Unit | Visibility | Description |
|---|---|---|---|---|
| run_id | string | Run ID. | ||
| job_id | string | Module and job name. | ||
| name | string | Job name. | ||
| target | string | Audited URL, without credentials. Empty for journeys. | ||
| started_us | timestamp | When the run started. | ||
| completed_us | timestamp | When the run finished. Null when it did not finish, for example because the Agent stopped. | ||
| outcome | string | Outcome of the run. | ||
| duration_ms | float | ms | How long the run took, excluding the wait for a browser. | |
| capture_state | string | Whether captures were saved - available, not_needed, unavailable or disabled. | ||
| error | string | First error reported by the run. | ||
| history_error | string | Problem saving the run to the history. | ||
| vnode_guid | string | GUID of the virtual node the run belonged to. Empty when it had none. | ||
| scheduled_us | timestamp | When the check was due. | ||
| queued_us | timestamp | When the check started waiting for a browser. | ||
| termination_reason | string | Why the run stopped early, such as test_timeout, suite_timeout, execution_budget or cancelled. Empty when it ran to the end. | ||
| tests_declared | integer | Tests declared in the file. | ||
| tests_passed | integer | Tests that passed. | ||
| tests_failed | integer | Tests that failed. | ||
| tests_timed_out | integer | Tests that timed out. | ||
| tests_skipped | integer | Tests that were skipped. | ||
| tests_expected_failure | integer | Tests that failed as expected (test.fail). | ||
| tests_not_run | integer | Tests that did not run. | ||
| failure_evidence_status | string | Whether failure details were recorded - complete, partial, unavailable, unsupported, invalid or not_recorded. | ||
| first_failure | string | The first unexpected test failure, with its step, source location and error message. | ||
| last_observed_step | string | The last step seen running. It does not mean the browser is still on it. | ||
| stop_context | string | What a timed-out or interrupted test was waiting for when it was stopped. It shows what was pending, not necessarily the cause. | ||
| browser_summary_status | string | Whether browser error counts were recorded, with the same values as failure_evidence_status. Requires browser_error_summary. | ||
| browser_errors | string | Browser error counts by kind. Missing counts mean nothing was recorded, not zero errors. |
Synthetic run detail
Everything recorded about one run, journey or Lighthouse, including a run that is still in progress - its outcome, error, test counts or Lighthouse measurements, failure details, captures and the timeline of test and step events. Open it from the monitor overview or the run history.
| Aspect | Description |
|---|---|
| Name | Synthetics-run |
| Require Cloud | yes |
| Performance | Reads one run from memory or disk. Starts no browser and contacts no website. |
| Security | Shows URLs, titles and error messages from the website, which can contain sensitive text. |
| Availability | While the Agent has at least one active synthetic job, saved run or saved capture. |
Prerequisites
No additional configuration is required.
Parameters
| Parameter | Type | Description | Required | Default | Options |
|---|---|---|---|---|---|
Job (job_id) | string | Module and job name of the run, such as journey:checkout. | yes | ||
Run (run_id) | string | Run ID, from the monitor overview or the run history. | yes |
Returns
One row per recorded test, step or audit event. The response also carries the full run record, including
what was captured; a missing completion time means the run has not finished or its end was not recorded.
For a journey, the record's failure_evidence holds the first failure's test and step path, source
locations and error excerpts, plus what was still pending when a timed-out test was stopped, and
browser_summary holds the browser error counts and samples when browser_error_summary is on.
A capture the run reported but Netdata did not save is listed in the record's captures.unpublished with a
reason: too_large (over the 5 MiB download limit), publication_failed (saving failed; the run's error
says why), not_eligible (taken while the run was being stopped; such captures are kept only when it
stopped with execution_budget) or not_in_final_report (listed in captures.associations but missing
from the run's final report).
| Column | Type | Unit | Visibility | Description |
|---|---|---|---|---|
| at_ms | timestamp | When the event happened. | ||
| kind | string | Event type, such as a test, step or error. | ||
| test_id | string | Test the event belongs to. | ||
| title | string | Test or step title. | ||
| phase | string | Phase of the run, such as start or end. | ||
| status | string | Status the test or step ended with. | ||
| expected_status | string | Status the test was expected to end with. | ||
| duration_ms | float | ms | How long the test or step took. | |
| message | string | Error or status message. |
Retained synthetic captures
The saved failure screenshots, traces and Lighthouse reports, one set per run, newest first. Captures are kept separately from the run history (7 days or 2 GiB by default), so they can remain after their run's history or their job is gone, until they expire. The response also shows how much disk the captures use and the retention policy.
| Aspect | Description |
|---|---|
| Name | Synthetics-artifacts |
| Require Cloud | yes |
| Performance | Reads capture file sizes and metadata from disk, not their contents. Starts no browser. |
| Security | Shows job names and capture metadata, not capture contents. |
| Availability | While the Agent has at least one active synthetic job, saved run or saved capture. |
Prerequisites
No additional configuration is required.
Parameters
| Parameter | Type | Description | Required | Default | Options |
|---|---|---|---|---|---|
Virtual node name (vnode) | string | Only jobs 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 jobs recorded under the virtual node with this GUID. Do not combine with vnode. | no | ||
Job (job_id) | string | Only captures of this job, such as journey:checkout. The storage totals always cover all jobs. | no | ||
Page cursor (cursor) | string | The next value of the previous response, to read the next page. Empty starts from the newest captures. | no | ||
Maximum rows (limit) | string | The maximum number of capture sets to return, from 1 to 2000. When truncated is true, pass next as cursor for more. | no | 2000 |
Returns
One row per saved capture set. The storage object reports the retention policy, the disk space used and any cleanup error.
| Column | Type | Unit | Visibility | Description |
|---|---|---|---|---|
| run_id | string | Run the captures belong to. | ||
| job_id | string | Module and job name. | ||
| published_us | timestamp | When the captures were saved. | ||
| bytes | integer | bytes | Size of the capture set. | |
| artifact_count | integer | Number of files in the set. | ||
| vnode_guid | string | GUID of the run's virtual node. Empty when it had none. |
Synthetic capture detail
The captures of one run, and the download of one of them - a screenshot, a Playwright trace ZIP or a Lighthouse HTML report. Downloading requires administrator access to the node.
| Aspect | Description |
|---|---|
| Name | Synthetics-artifact |
| Require Cloud | yes |
| Performance | Reads metadata from disk, and one file of up to 5 MiB when downloading. Starts no browser. |
| Security | Listing requires member access; downloading requires administrator access. Screenshots, traces and reports can contain passwords, cookies, personal data and other page content. |
| Availability | While the Agent has at least one active synthetic job, saved run or saved capture. |
Prerequisites
No additional configuration is required.
Parameters
| Parameter | Type | Description | Required | Default | Options |
|---|---|---|---|---|---|
Job (job_id) | string | Module and job name of the run, such as journey:checkout. | yes | ||
Run (run_id) | string | Run ID, from the capture list, the monitor overview or the run history. | yes | ||
Capture (artifact_id) | string | Capture to download. The response returns its content base64-encoded. Empty lists the run's captures. | no |
Returns
One row per capture of the run. A capture that has expired is reported as expired_or_unavailable. A downloaded file is checked against its recorded SHA-256 and returned as base64 in data_base64, up to 5 MiB.
| Column | Type | Unit | Visibility | Description |
|---|---|---|---|---|
| artifact_id | string | Capture ID, for download. | ||
| kind | string | Capture type. | ||
| mime | string | Content type. | ||
| bytes | integer | bytes | File size. | |
| sha256 | string | SHA-256 of the file. | ||
| availability | string | Whether the file is still kept. | ||
| test | string | Title of the test a screenshot or trace belongs to, or Test not recorded when the run did not report it. Empty for Lighthouse reports. | ||
| label | string | Screenshot, Trace or Lighthouse report. |
Troubleshooting
Known Errors
opening DEM history: load journal identity: journalhost: machine id: no machine id found
When
The Agent's log shows this when dem.plugin starts on Linux. The plugin then exits, so no DEM job runs,
whichever modules are enabled.
Cause
DEM keeps its history in journal files, which need the host's machine ID, and none was found. Neither
/etc/machine-id nor /var/lib/dbus/machine-id holds a valid ID, and neither file exists under the
Netdata host prefix (/host in the official Docker image). This is common in minimal containers.
Fix
On a host, create the machine ID with sudo systemd-machine-id-setup (or
sudo dbus-uuidgen --ensure=/etc/machine-id without systemd), then restart the Agent.
In the official Docker image, mount the host's machine ID under the Netdata host prefix: add
-v /etc/machine-id:/host/etc/machine-id:ro to docker run, or the same mount under volumes: in Docker
Compose, then recreate the container. Check first that the host has /etc/machine-id: Docker creates a
missing source path as an empty directory, which DEM rejects.
install a browser runtime and restart dem.plugin: matching browser runtime is not prepared
When
Static, source or Docker installation. The job stays waiting and never runs.
Cause
No browser runtime is installed, or it was installed after the Agent started.
Fix
Install the runtime (see Prerequisites), then restart the Agent or the container.
install the optional netdata-dem-runtime package and restart dem.plugin: matching browser runtime is not prepared
When
Native DEB or RPM installation. The job stays waiting and never runs.
Cause
The netdata-dem-runtime package is not installed.
Fix
Install netdata-dem-runtime with the package manager. The package restarts the Agent when it finishes.
DEM browser execution requires the plugin to run as an unprivileged user; root RUM operation does not enable browser jobs
Cause
The Netdata service runs as root. Browser jobs refuse to start Chromium as root.
Fix
Run the Netdata service as its unprivileged service account (netdata by default). RUM keeps working either way.
DEM browser execution requires prepared Linux amd64 or arm64 runtime
Cause
The host is not Linux on amd64 or arm64, where the browser runtime is not available.
Fix
Run browser jobs from an Agent on an amd64 or arm64 Linux host. RUM does not need the runtime.
online runtime preparation requires runtime.release_url
When
Installing the runtime online, with kickstart, the helper or --allow-download.
Cause
The build has no release identity, or runtime.release_url in dem.conf explicitly disables the default URL.
Fix
Use a release build's default URL, configure an exact matching signed release URL, or provide signed offline inputs (see the browser runtime host setup guide).
offline preparation requires runtime.offline_keyring; no runtime release verification key is configured
When
Installing the runtime from a release file and archive with --release and --archive.
Cause
There is no public key to verify the release signature.
Fix
Set runtime.offline_keyring in dem.conf to the absolute path of the Netdata release signing keyring, readable by the Netdata service account.
Runtime installation or qualification fails with a Chromium sandbox error
Cause
The host does not let an unprivileged process create the user namespaces Chromium's sandbox needs, usually because of an AppArmor restriction (Ubuntu 24.04) or a container's seccomp or namespace settings.
Fix
Install the runtime with kickstart or the netdata-dem-runtime.sh helper, which prepare the AppArmor
allowance; for Docker, use the documented container settings, including apparmor=unconfined on AppArmor
hosts. Look for denials in the kernel log:
sudo journalctl -k --since '10 minutes ago'
Do not disable Chromium's sandbox or the host's restrictions.
Checks are coalesced, or the state chart shows stale
Cause
The browser is busy with other jobs for longer than this job's check interval, so its checks wait and newer ones replace them. The scheduling charts show growing queue age and coalesced occurrences.
Fix
Raise check_every or lower timeout on busy jobs, or raise browser.concurrency in dem.conf if the host has CPU and memory to spare, then restart the Agent.
plugin exiting with retained unverified synthetic work: ERROR
When
A journey or Lighthouse run, or a runtime check, ends without proof that its browser processes exited, and the whole plugin, RUM included, exits.
Cause
DEM could not confirm that every browser and Node.js process of the run exited, for example because one is stuck in uninterruptible disk I/O or Netdata lost track of it. It keeps the run's files and its runtime release protected instead of deleting something that may still be in use.
Fix
Look for leftover processes of the Netdata service account (for example ps -u netdata -f) and resolve what
keeps them running, then restart the Agent. A process stuck in uninterruptible disk I/O can need a host
reboot, which also lets DEM release the protected runtime files.
Leave the files in the dem directory under the Agent's state directory (usually /var/lib/netdata/dem/)
in place: DEM never removes protected work based on age or a missing process ID.
unverified synthetic completion: ERROR
When
The plugin was shutting down when a run or runtime check ended without proof that its browser processes exited.
Cause
DEM could not confirm that every browser and Node.js process of the run exited, for example because one is stuck in uninterruptible disk I/O or Netdata lost track of it. It keeps the run's files and its runtime release protected instead of deleting something that may still be in use.
Fix
Look for leftover processes of the Netdata service account (for example ps -u netdata -f) and resolve what
keeps them running, then restart the Agent. A process stuck in uninterruptible disk I/O can need a host
reboot, which also lets DEM release the protected runtime files.
Leave the files in the dem directory under the Agent's state directory (usually /var/lib/netdata/dem/)
in place: DEM never removes protected work based on age or a missing process ID.
set exactly one of script and script_path
Cause
The job sets both script and script_path, or neither.
Fix
Keep exactly one of them.
script_path must be an absolute JS or TS file
Cause
script_path is a relative path, or does not end in .js, .ts, .mjs, .cjs, .mts or .cts.
Fix
Use the absolute path of the test file.
script_path must reference a readable regular file
Cause
The file does not exist, is not a regular file, or a directory on its path cannot be searched by the Netdata service account.
Fix
Check the path and the permissions as the service account:
sudo -u netdata cat /etc/netdata/dem/journeys/checkout.spec.ts
script_path must be readable
Cause
The file exists, but the Netdata service account cannot read it.
Fix
Check the path and the permissions as the service account:
sudo -u netdata cat /etc/netdata/dem/journeys/checkout.spec.ts
script must not be blank
Cause
script contains only whitespace.
Fix
Put the Playwright Test source in script, or remove it and set script_path.
trace_on_failure requires screenshot_on_failure
Cause
Traces are saved only together with failure screenshots.
Fix
Set screenshot_on_failure to true, or trace_on_failure to false.
invalid DEM_SECRET_ environment entry
Cause
A secret name does not start with DEM_SECRET_, contains characters other than letters, digits and underscores, or the value contains a NUL character.
Fix
Rename the secret, for example to DEM_SECRET_PASSWORD.
secret names must be unique
Cause
Two secrets in the job have the same name.
Fix
Give each secret its own name.
Runs end as inconclusive
Cause
No test failed, but not every declared test passed. The file has no tests, or tests were skipped, marked as expected to fail (test.fail), or did not run.
Fix
Check the test counts in the journey run history, and make every test in the file run and pass.
Runs end as error
Cause
The run could not produce test results, for example because the script has a syntax error or imports a module that is not available, or the browser failed to start.
Fix
Open the run in the journey run history; its error column has the message. Check that the script runs with npx playwright test on a development machine.
Runs end as timeout
Cause
A test or the whole file took longer than timeout. The run's termination reason tells which.
Fix
Open the run in the journey run history. The last observed step and stop context show what the browser was waiting for; speed up that step or raise timeout.
The Test action in the job editor times out
Cause
Test first waits for a free browser, shared with the running jobs, then runs the whole journey; the editor's request must cover both, which a long journey or a busy Agent can exceed. A Test that timed out keeps no result to look at later.
Fix
Save the job without testing it and check its first run in the journey run history, or test again when fewer checks are running.
Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.