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, including remote instances.

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.

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.

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

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

Alerts

There are no alerts configured by default for this integration.

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
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	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 filtered by journal saved time. after and before accept Unix seconds or 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
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
Saved after (`after`)	string	Inclusive journal saved-time lower bound in Unix seconds or a negative offset from now. Leave empty for all retained history.	no
Saved before (`before`)	string	Inclusive journal saved-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 saved 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	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 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	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
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	Description
artifact_id	string		Artifact.
kind	string		Kind.
mime	string		Content type.
bytes	integer	bytes	Size.
sha256	string		SHA-256.
availability	string		Availability.

Troubleshooting

The observability platform companies need to succeed

Want a personalised demo of Netdata for your use case?

Contact Sales

Lighthouse Desktop Audit