Browser Journey

Plugin: dem.plugin Module: journey

Overview

Monitor whether browser workflow checks execute and pass with real Playwright Test. Inspect test outcomes, attempt durations and retained failure details.

Runs the configured Playwright Test entry with sandboxed Chromium at the native job interval, using one worker without retries. Workflows can perform the actions their scripts request on the target website. Configuration Test validates preparation without executing the workflow.

This collector is only supported on the following platforms:

• Linux

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

Permission	Needed when
Execute the prepared Node runtime and sandboxed Chromium	Every browser attempt
Write to the DEM state directory	Retaining history and optional captures
Read the entry file and its imports	Using script_path

Default Behavior

Auto-Detection

Jobs require explicit configuration; no websites or scripts are discovered automatically.

Limits

Empty suites, skipped tests and expected failures cannot establish successful coverage. A failed check takes precedence over incomplete coverage. Waiting and running attempts retain the prior result for diagnosis; that observation becomes stale after two collection intervals and does not imply recovery. Failure screenshots are disabled unless requested.

Performance Impact

Each attempt starts a fresh browser and consumes CPU, memory and target website requests. Increasing update_every reduces frequency. Jobs share one browser admission slot, so concurrent due jobs can wait. Optional captures consume local disk space.

Setup

Prerequisites

Prepare the browser runtime

Configure the Node executable, pinned Playwright and Lighthouse dependencies, and full Chromium binary in the runtime section of dem.conf. Chromium must run with its sandbox enabled as the Netdata service account. Restart dem.plugin after changing runtime paths; the plugin does not download dependencies. Follow the DEM runtime preparation guide for the pinned versions and setup commands.

Configuration

Options

Options apply independently to each native job.

Configuration options

Group	Option	Description	Default	Required
Journey	name	Native job name used to identify this monitor and its history. Renaming creates a separate monitor.		yes
	script	Inline Playwright Test JavaScript or TypeScript source. Leave empty when using Script path.		no
	script_path	Absolute path to a readable Playwright Test JavaScript or TypeScript entry file. Leave empty when using Script.		no
Secrets	secrets[].name	Unique environment variable name starting with DEM_SECRET_, followed by letters, digits or underscores.		no
	secrets[].value	Credential value or a native secret reference, such as ${env:WORKFLOW_PASSWORD}.		no
Diagnosis	screenshot_on_failure	Save a screenshot when a workflow check fails. Screenshots can contain sensitive page content; timeout capture is best effort.	no	no
Collection	update_every	Data collection interval, in seconds.	900	no
	timeout	Browser attempt timeout, in seconds. Waiting for another browser attempt is excluded.	120	no

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

Monitor a home page

Create one native browser monitor after preparing the runtime.

Examples

jobs:
  - name: home
    script: |
      import { test, expect } from '@playwright/test';
      test('home page', async ({ page }) => {
        await page.goto('https://example.org/');
        await expect(page).toHaveTitle(/Example Domain/);
      });

Alerts

The following alerts are available:

Alert name	On metric	Description
Alert name dem_journey_failed	On metricdem_synthetic.execution_state	DescriptionLatest 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 native job has its own chart identity. Attempt duration excludes waiting for admission. Missing observations are omitted.

Per job

One configured native browser monitor.

This scope has no labels.

Metrics:

Metric	Description	Dimensions	Unit
dem_synthetic.execution_state	Synthetic attempt outcome	unknown, success, failed, timeout, inconclusive, error, cancelled	state
dem_synthetic.duration	Synthetic attempt duration	duration	milliseconds
dem_synthetic.journey.declared_tests	Declared journey tests	declared	tests
dem_synthetic.journey.test_outcomes	Journey test outcomes	passed, failed, timed_out, skipped, expected_failure, not_run	tests

Live Data

Use these process-wide Functions through the Agent or Cloud for both journey and Lighthouse jobs. Invoke their public synthetics-* names with the documented filters; no job selector or active browser is required.

Synthetic monitors

Invoke synthetics-checks. Active native monitors and their latest observation. Disabled and failed-startup configuration remains in native job status. Freshness belongs to the last observation, independently of a waiting or running attempt.

Aspect	Description
Name	Synthetics-checks
Require Cloud	no
Performance	Reads local active snapshots and retained evidence without starting a browser or acquiring browser admission. Artifact fetch reads at most 5 MiB.
Security	Requires member-equivalent access for observations and retained text; artifact bytes require administrator-equivalent access. Captures and reports may contain sensitive URLs, page content and user input; they are not universally redacted.
Availability	Available while dem.plugin is running, independently of active journey or Lighthouse jobs. Individual retained evidence may be absent or expired.

Prerequisites

No additional configuration is required.

Parameters

Parameter	Type	Description	Required	Default	Options
Monitor (job_id)	string	Native module and job name, such as journey:checkout. Leave empty to include all monitors when listing.	no
Kind (kind)	string	Filter by journey or lighthouse. Leave empty to include both kinds.	no
Maximum rows (limit)	string	Maximum returned rows, from 1 to 2000. Defaults to 2000; truncated indicates additional matching rows.	no	2000

Returns

At most limit active jobs, with independent current-attempt state and last-observation freshness. The response includes process artifact retained_bytes, protected_bytes and cleanup_errors under artifacts. Disabled and failed-startup jobs are visible through native configuration status.

Column	Type	Unit	Visibility	Description
job_id	string			Monitor.
kind	string			Kind.
name	string			Name.
target	string			Target.
state	string			Current state.
fresh	boolean			Last observation fresh.
run_id	string			Last run.
outcome	string			Last outcome.
completed_us	timestamp			Last completion. Unix microseconds; null when unavailable.
duration_ms	float	ms		Attempt duration.
last_success_us	timestamp			Last success in this activation. Unix microseconds; null when unavailable.
last_failure_us	timestamp			Last failure in this activation. Unix microseconds; null when unavailable.
error	string			Last error.
history_error	string			History error.

Synthetic runs

Invoke synthetics-runs. Retained attempts selected by start time, with their latest retained outcome even when completion is outside the range. after and before include their entire Unix second or accept negative offsets from now; omitted bounds cover retained history through now. Results are capped at 2000 and disclose truncation.

Aspect	Description
Name	Synthetics-runs
Require Cloud	no
Performance	Reads local active snapshots and retained evidence without starting a browser or acquiring browser admission. Artifact fetch reads at most 5 MiB.
Security	Requires member-equivalent access for observations and retained text; artifact bytes require administrator-equivalent access. Captures and reports may contain sensitive URLs, page content and user input; they are not universally redacted.
Availability	Available while dem.plugin is running, independently of active journey or Lighthouse jobs. Individual retained evidence may be absent or expired.

Prerequisites

No additional configuration is required.

Parameters

Parameter	Type	Description	Required	Default	Options
Monitor (job_id)	string	Native module and job name, such as journey:checkout. Leave empty to include all monitors when listing.	no
Kind (kind)	string	Filter by journey or lighthouse. Leave empty to include both kinds.	no
Outcome (outcome)	string	Filter by unknown, success, failed, timeout, inconclusive, error or cancelled. Leave empty for all outcomes.	no
Started after (after)	string	Inclusive run start-time lower bound in Unix seconds or a negative offset from now. Leave empty for all retained history.	no
Started before (before)	string	Inclusive run start-time upper bound in Unix seconds or a negative offset from now. Leave empty for the current time.	no
Maximum rows (limit)	string	Maximum returned rows, from 1 to 2000. Defaults to 2000; truncated indicates additional matching rows.	no	2000

Returns

At most limit retained attempts selected by start time, with explicit truncated and effective time bounds. Zero or missing execution timestamps and missing durations are null rather than fabricated measurements.

Column	Type	Unit	Visibility	Description
run_id	string			Run.
job_id	string			Monitor.
kind	string			Kind.
name	string			Name.
target	string			Target.
started_us	timestamp			Started. Unix microseconds; null when unavailable.
completed_us	timestamp			Completed. Unix microseconds; null when unavailable.
outcome	string			Outcome.
duration_ms	float	ms		Attempt duration.
capture_state	string			Capture state.
error	string			Error.
history_error	string			History error.

Synthetic run detail

Invoke synthetics-run. One retained or latest active attempt, independent of picker bounds, with original test phases, errors, counts, nullable lab measurements and bounded reporter events. Missing completion means no verified terminal observation.

Aspect	Description
Name	Synthetics-run
Require Cloud	no
Performance	Reads local active snapshots and retained evidence without starting a browser or acquiring browser admission. Artifact fetch reads at most 5 MiB.
Security	Requires member-equivalent access for observations and retained text; artifact bytes require administrator-equivalent access. Captures and reports may contain sensitive URLs, page content and user input; they are not universally redacted.
Availability	Available while dem.plugin is running, independently of active journey or Lighthouse jobs. Individual retained evidence may be absent or expired.

Prerequisites

No additional configuration is required.

Parameters

Parameter	Type	Description	Required	Default	Options
Monitor (job_id)	string	Exact native module and job name that owns the requested run, such as journey:checkout.	yes
Run (run_id)	string	Exact run identifier returned by synthetic inventory or run history.	yes

Returns

One row per retained reporter event, preserving actual and expected status and failure phase. The run object also contains test counts, nullable lab metrics, capture state, artifact metadata and history errors; dropped_events discloses omitted event detail.

Column	Type	Unit	Visibility	Description
at_ms	timestamp			Event time. Unix milliseconds.
kind	string			Event.
test_id	string			Test.
title	string			Title.
phase	string			Phase.
status	string			Actual status.
expected_status	string			Expected status.
duration_ms	float	ms		Duration.
message	string			Message.

Synthetic artifacts

Invoke synthetics-artifact. Retained capture metadata for one run; file bytes are verified when fetched. Supplying artifact_id requests base64-encoded bytes and requires administrator-equivalent permissions. Screenshots and HTML reports may contain sensitive content. Missing retained files are expired or unavailable; fetches are limited to 5 MiB.

Aspect	Description
Name	Synthetics-artifact
Require Cloud	no
Performance	Reads local active snapshots and retained evidence without starting a browser or acquiring browser admission. Artifact fetch reads at most 5 MiB.
Security	Requires member-equivalent access for observations and retained text; artifact bytes require administrator-equivalent access. Captures and reports may contain sensitive URLs, page content and user input; they are not universally redacted.
Availability	Available while dem.plugin is running, independently of active journey or Lighthouse jobs. Individual retained evidence may be absent or expired.

Prerequisites

No additional configuration is required.

Parameters

Parameter	Type	Description	Required	Default	Options
Monitor (job_id)	string	Exact native module and job name that owns the requested run, such as journey:checkout.	yes
Run (run_id)	string	Exact run identifier returned by synthetic inventory or run history.	yes
Artifact (artifact_id)	string	Exact recorded artifact identifier to fetch its bytes. Leave empty to list capture metadata.	no

Returns

Recorded capture metadata with retained-manifest availability. Fetch verifies content and returns encoding=base64 and data_base64 without rendering HTML. A missing recorded capture returns expired_or_unavailable, which does not prove why the file is absent.

Column	Type	Unit	Visibility	Description
artifact_id	string			Artifact.
kind	string			Kind.
mime	string			Content type.
bytes	integer	bytes		Size.
sha256	string			SHA-256.
availability	string			Availability.

Troubleshooting

Other Problems

No conclusive observations

Inspect native job status and synthetic inventory for runtime preparation errors, waiting attempts or execution inability. Open the latest retained run for errors and actual failure phases. Missing measurements are gaps; stale, inconclusive and cancelled observations are not recovery.