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