Lighthouse Desktop Audit

Plugin: dem.plugin Module: lighthouse

Overview

Monitor desktop lab performance for a web page with Lighthouse. Inspect the performance category score, individual lab timings, layout shift and audit execution outcomes.

Audits the configured HTTP or HTTPS page using the Lighthouse desktop preset and sandboxed Chromium at the native job interval. Configuration Test validates preparation without running an audit. Lab measurements describe this browser attempt and are not field Core Web Vitals.

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

Default Behavior

Auto-Detection

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

Limits

Missing scores or timings produce measurement gaps; a measured zero remains zero. Running and waiting attempts do not refresh the prior observation, which becomes stale after two collection intervals. HTML reports are disabled unless requested. No stock performance-score threshold alert is configured.

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
Target	name	Native job name used to identify this monitor and its history. Renaming creates a separate monitor.		yes
	url	Absolute HTTP or HTTPS URL of the page to audit. Embedded credentials are not accepted.		yes
Diagnosis	save_report	Save the full Lighthouse HTML report. Reports can contain sensitive URLs and page content.	no	no
Collection	update_every	Data collection interval, in seconds.	1800	no
	timeout	Browser attempt timeout, in seconds. Waiting for another browser attempt is excluded.	180	no

via File

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

Examples

Monitor a home page

Create one native browser monitor after preparing the runtime.

Examples

jobs:
  - name: home
    url: https://example.org/

Alerts

There are no alerts configured by default for this integration.

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.lighthouse.performance	Lighthouse performance score	performance	points
dem_synthetic.lighthouse.timings	Lighthouse lab timings	fcp, lcp, tbt, speed_index	milliseconds
dem_synthetic.lighthouse.cls	Lighthouse cumulative layout shift	cls	ratio

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. 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.

Retained synthetic captures

Invoke synthetics-artifacts to find retained screenshot and report sets, newest publication first, even after run history expires or a monitor is disabled or deleted. Each set contains one run's captures. The shared default allowance is seven days and 2 GiB, preferring each monitor's newest eligible capture. Age and size pressure can still remove it; this is not complete incident history or a hard disk cap. A later Lighthouse report may displace that monitor's earlier poor-score report. Journey recovery without a screenshot leaves its previous failure capture eligible. Disabled or deleted monitors keep the same preference; renamed monitors form separate groups.

Aspect	Description
Name	Synthetics-artifacts
Require Cloud	no
Performance	Reads local capture metadata and file sizes without reading capture contents or starting a browser.
Security	Requires member-equivalent access. Exposes monitor identities and capture metadata, not capture contents.
Availability	Available while dem.plugin is running, independently of active journey or Lighthouse jobs and retained run history. Captures can expire under age or size limits.

Prerequisites

No additional configuration is required.

Parameters

Parameter	Type	Description	Required	Default	Options
Monitor (job_id)	string	Exact native module and job name to filter captures, such as journey:checkout. Leave empty for all monitors. Storage totals remain global.	no
Previous page cursor (before)	string	The next cursor returned by the previous page. Leave empty for the newest captures.	no
Maximum rows (limit)	string	Maximum returned sets, from 1 to 2000. Use next as before to continue when truncated is true. Captures may expire between pages.	no	2000

Returns

One row per retained capture set. The storage object reports global effective policy, observation time, retained capture bytes, workspace bytes, unclassified bytes, pending-deletion bytes, known set and monitor counts, cleanup status and policy reload errors. Unreadable sizes are unknown with an error. Sizes are logical file lengths; workspace, unclassified files and pending deletions are outside the retained-capture allowance. Metadata does not verify file integrity.

Column	Type	Unit	Visibility	Description
run_id	string			Run.
job_id	string			Monitor.
published_us	timestamp			Publication time in Unix microseconds.
bytes	integer	bytes		Capture set size, including its manifest.
artifact_count	integer			Number of captures in the set.

Synthetic capture detail

Invoke synthetics-artifact. Retained capture metadata for one run, independently of run history retention; 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 the retained capture list, 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

Retained capture metadata remains available after run history expires. 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.