Skip to main content

Browser Journey

Browser Journey

Plugin: dem.plugin Module: journey

Maintained by Netdata

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.

PermissionNeeded 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.concurrency in dem.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 stale and 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 (history and artifacts in dem.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_every to run less often. update_every only refreshes the charts and starts no browser.
  • browser.concurrency in dem.conf limits how many browsers run at once; size it for the host's CPU and memory, and restart the Agent to apply it.
  • trace_on_failure records a trace during every run, including runs that pass, which adds CPU, memory and temporary disk use.
  • browser_error_summary can 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 installationInstall the runtime with
Native DEB or RPM packagesThe 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 installationkickstart.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
GroupOptionDescriptionDefaultRequired
JourneynameJob name. It identifies the journey in charts, alerts and run history, so renaming starts a separate history.yes
scriptPlaywright Test source code, in JavaScript or TypeScript. Set either this or script_path.no
script_pathAbsolute 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
Secretssecrets[].nameEnvironment 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[].valueSecret value. Prefer a secret reference, such as ${env:WORKFLOW_PASSWORD}, over a literal value.no
Diagnosisscreenshot_on_failureSave a screenshot when a test fails. Screenshots can show sensitive page content.nono
trace_on_failureSave a Playwright trace when a test fails; requires failure screenshots. Traces can contain passwords, cookies and request and response bodies.nono
browser_error_summaryCount 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.nono
Collectioncheck_everyHow often to run the journey, in seconds.900no
update_everyHow often to refresh the charts from the latest result, in seconds. Refreshing never starts a browser.10no
timeoutTime limit for one run of the journey, in seconds. Time spent waiting for a free browser does not count.120no
Virtual NodevnodeAssociates 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 nameOn metricDescription
dem_journey_failed dem_synthetic.execution_stateLatest 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:

MetricDescriptionDimensionsUnit
dem_synthetic.execution_stateLatest synthetic observation stateunknown, success, failed, timeout, inconclusive, error, cancelled, stalestate
dem_synthetic.durationLatest synthetic attempt durationdurationmilliseconds
dem_synthetic.observation_ageAge of latest synthetic observationageseconds
dem_synthetic.attemptsCompleted synthetic attemptssuccess, failed, timeout, inconclusive, error, cancelled, unknownattempts/s
dem_synthetic.occurrencesSynthetic scheduled occurrencesscheduled, admitted, coalescedoccurrences/s
dem_synthetic.scheduler_stateSynthetic active and pending attemptsactive, pendingattempts
dem_synthetic.queue_ageOldest synthetic admission waitageseconds
dem_synthetic.scheduling_delayLatest synthetic admission delay from selected due timedelayseconds
dem_synthetic.journey.declared_testsLatest declared journey testsdeclaredtests
dem_synthetic.journey.test_outcomesLatest journey test outcomespassed, failed, timed_out, skipped, expected_failure, not_runtests

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.

AspectDescription
NameSynthetics-checks
Require Cloudyes
PerformanceReads the jobs' current state in memory. Starts no browser and contacts no website.
SecurityShows job names, audited URLs and error messages, which can contain sensitive text.
AvailabilityWhile the Agent has at least one active synthetic job, saved run or saved capture.

Prerequisites​

No additional configuration is required.

Parameters​

ParameterTypeDescriptionRequiredDefaultOptions
Virtual node name (vnode)stringOnly 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)stringOnly jobs recorded under the virtual node with this GUID. Do not combine with vnode.no
Job (job_id)stringOnly this job, written as module and job name, such as journey:checkout or lighthouse:home.no
Kind (kind)stringOnly journey or only lighthouse jobs.no
Maximum rows (limit)stringThe maximum number of rows to return, from 1 to 2000. The response sets truncated when more rows match.no2000

Returns​

One row per active job.

ColumnTypeUnitVisibilityDescription
job_idstringModule and job name, such as journey:checkout.
kindstringjourney or lighthouse.
namestringJob name.
targetstringAudited URL of a Lighthouse job, without credentials. Empty for journeys.
statestringThe 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.
freshbooleanWhether the latest result is less than two check intervals old.
run_idstringID of the latest run.
outcomestringOutcome of the latest run.
completed_ustimestampWhen the latest run finished.
duration_msfloatmsHow long the latest run took.
last_success_ustimestampWhen a run last succeeded, since the job started or moved to another virtual node.
last_failure_ustimestampWhen a run last failed or timed out, since the job started or moved to another virtual node.
errorstringError message of the latest run.
history_errorstringProblem saving the latest run to the run history.
vnode_guidstringGUID of the job's virtual node. Empty when it has none.
check_everyintegersConfigured check interval.
scheduledintegerChecks that came due since the job started.
admittedintegerChecks that got a browser and ran.
coalescedintegerChecks skipped because the job's previous check was still waiting for a browser.
pendingbooleanWhether a check is waiting for a browser.
queue_agefloatsHow long the waiting check has waited.
scheduling_delayfloatsHow 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.

AspectDescription
NameSynthetics-journey-runs
Require Cloudyes
PerformanceReads the run history from disk, up to 2000 rows per request. Starts no browser and contacts no website.
SecurityRows can contain URLs, test and step titles, and error messages from the website, which can include sensitive text.
AvailabilityWhile the Agent has at least one active synthetic job, saved run or saved capture.

Prerequisites​

No additional configuration is required.

Parameters​

ParameterTypeDescriptionRequiredDefaultOptions
Virtual node name (vnode)stringOnly 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)stringOnly jobs recorded under the virtual node with this GUID. Do not combine with vnode.no
Job (job_id)stringOnly runs of this journey, such as journey:checkout.no
Outcome (outcome)stringOnly runs with this outcome - success, failed, timeout, inconclusive, error, cancelled or unknown.no
Started after (after)stringOnly 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)stringOnly runs started at or before this time, in Unix seconds, or seconds before now when negative. Empty means now.no
Maximum rows (limit)stringThe maximum number of rows to return, from 1 to 2000. The response sets truncated when more rows match.no2000

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.

ColumnTypeUnitVisibilityDescription
run_idstringRun ID.
job_idstringModule and job name.
namestringJob name.
targetstringAudited URL, without credentials. Empty for journeys.
started_ustimestampWhen the run started.
completed_ustimestampWhen the run finished. Null when it did not finish, for example because the Agent stopped.
outcomestringOutcome of the run.
duration_msfloatmsHow long the run took, excluding the wait for a browser.
capture_statestringWhether captures were saved - available, not_needed, unavailable or disabled.
errorstringFirst error reported by the run.
history_errorstringProblem saving the run to the history.
vnode_guidstringGUID of the virtual node the run belonged to. Empty when it had none.
scheduled_ustimestampWhen the check was due.
queued_ustimestampWhen the check started waiting for a browser.
termination_reasonstringWhy the run stopped early, such as test_timeout, suite_timeout, execution_budget or cancelled. Empty when it ran to the end.
tests_declaredintegerTests declared in the file.
tests_passedintegerTests that passed.
tests_failedintegerTests that failed.
tests_timed_outintegerTests that timed out.
tests_skippedintegerTests that were skipped.
tests_expected_failureintegerTests that failed as expected (test.fail).
tests_not_runintegerTests that did not run.
failure_evidence_statusstringWhether failure details were recorded - complete, partial, unavailable, unsupported, invalid or not_recorded.
first_failurestringThe first unexpected test failure, with its step, source location and error message.
last_observed_stepstringThe last step seen running. It does not mean the browser is still on it.
stop_contextstringWhat a timed-out or interrupted test was waiting for when it was stopped. It shows what was pending, not necessarily the cause.
browser_summary_statusstringWhether browser error counts were recorded, with the same values as failure_evidence_status. Requires browser_error_summary.
browser_errorsstringBrowser 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.

AspectDescription
NameSynthetics-run
Require Cloudyes
PerformanceReads one run from memory or disk. Starts no browser and contacts no website.
SecurityShows URLs, titles and error messages from the website, which can contain sensitive text.
AvailabilityWhile the Agent has at least one active synthetic job, saved run or saved capture.

Prerequisites​

No additional configuration is required.

Parameters​

ParameterTypeDescriptionRequiredDefaultOptions
Job (job_id)stringModule and job name of the run, such as journey:checkout.yes
Run (run_id)stringRun 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).

ColumnTypeUnitVisibilityDescription
at_mstimestampWhen the event happened.
kindstringEvent type, such as a test, step or error.
test_idstringTest the event belongs to.
titlestringTest or step title.
phasestringPhase of the run, such as start or end.
statusstringStatus the test or step ended with.
expected_statusstringStatus the test was expected to end with.
duration_msfloatmsHow long the test or step took.
messagestringError 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.

AspectDescription
NameSynthetics-artifacts
Require Cloudyes
PerformanceReads capture file sizes and metadata from disk, not their contents. Starts no browser.
SecurityShows job names and capture metadata, not capture contents.
AvailabilityWhile the Agent has at least one active synthetic job, saved run or saved capture.

Prerequisites​

No additional configuration is required.

Parameters​

ParameterTypeDescriptionRequiredDefaultOptions
Virtual node name (vnode)stringOnly 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)stringOnly jobs recorded under the virtual node with this GUID. Do not combine with vnode.no
Job (job_id)stringOnly captures of this job, such as journey:checkout. The storage totals always cover all jobs.no
Page cursor (cursor)stringThe next value of the previous response, to read the next page. Empty starts from the newest captures.no
Maximum rows (limit)stringThe maximum number of capture sets to return, from 1 to 2000. When truncated is true, pass next as cursor for more.no2000

Returns​

One row per saved capture set. The storage object reports the retention policy, the disk space used and any cleanup error.

ColumnTypeUnitVisibilityDescription
run_idstringRun the captures belong to.
job_idstringModule and job name.
published_ustimestampWhen the captures were saved.
bytesintegerbytesSize of the capture set.
artifact_countintegerNumber of files in the set.
vnode_guidstringGUID 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.

AspectDescription
NameSynthetics-artifact
Require Cloudyes
PerformanceReads metadata from disk, and one file of up to 5 MiB when downloading. Starts no browser.
SecurityListing requires member access; downloading requires administrator access. Screenshots, traces and reports can contain passwords, cookies, personal data and other page content.
AvailabilityWhile the Agent has at least one active synthetic job, saved run or saved capture.

Prerequisites​

No additional configuration is required.

Parameters​

ParameterTypeDescriptionRequiredDefaultOptions
Job (job_id)stringModule and job name of the run, such as journey:checkout.yes
Run (run_id)stringRun ID, from the capture list, the monitor overview or the run history.yes
Capture (artifact_id)stringCapture 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.

ColumnTypeUnitVisibilityDescription
artifact_idstringCapture ID, for download.
kindstringCapture type.
mimestringContent type.
bytesintegerbytesFile size.
sha256stringSHA-256 of the file.
availabilitystringWhether the file is still kept.
teststringTitle of the test a screenshot or trace belongs to, or Test not recorded when the run did not report it. Empty for Lighthouse reports.
labelstringScreenshot, 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.