Prometheus Exporter for Google Pagespeed Online Metrics

Examples

To start the example with the default dashboard (docker-compose required)

$ git clone [email protected]:foomo/pagespeed_exporter.git
$ cd pagespeed_exporter/example
$ docker-compose up -d

After that, the application should be running on localhost:3000 with username admin and password s3cr3t.

The provided dashboard (Pagespeed) will be loaded with data after the first scrape.

The dashboard can be found at grafana

Note: The example dashboard assumes you're fetching all pagespeed categories.

Understanding Metrics

• https://github.com/GoogleChrome/lighthouse/blob/master/docs/understanding-results.md
• https://developers.google.com/speed/docs/insights/v5/reference/pagespeedapi/runpagespeed

Prometheus exporter for google pagespeed metrics

CrUX Metrics (Real User Monitoring)

The exporter provides Chrome User Experience Report (CrUX) metrics, which represent real-world user experience data collected from Chrome browsers. CrUX data is only available for URLs and origins with sufficient user traffic.

Metric Prefixes

• pagespeed_loading_experience_* - URL-specific RUM data (when available for the specific page)
• pagespeed_origin_loading_experience_* - Origin-wide RUM data (aggregated across the entire domain)

Available CrUX Metrics

The exporter provides three types of metrics for each Core Web Vital:

1. P75 Percentile - The 75th percentile value (75% of users experience better performance)
2. Category Ratios - Proportion of users experiencing fast/average/slow performance
3. Thresholds - Google's Core Web Vitals performance boundaries

Core Web Vitals Included

• Largest Contentful Paint (LCP) - Measures loading performance
• Interaction to Next Paint (INP) - Measures interactivity
• Cumulative Layout Shift (CLS) - Measures visual stability
• First Contentful Paint (FCP) - Measures perceived load speed
• Experimental Time to First Byte (TTFB) - Measures server responsiveness

Example Metrics Output

For Largest Contentful Paint (LCP):

# P75 percentile (existing metric)
pagespeed_loading_experience_metrics_largest_contentful_paint_duration_seconds 1.278

# Category distribution ratios (proportion of users in each category)
pagespeed_loading_experience_metrics_largest_contentful_paint_category_ratio{category="fast"} 0.9389
pagespeed_loading_experience_metrics_largest_contentful_paint_category_ratio{category="average"} 0.0371
pagespeed_loading_experience_metrics_largest_contentful_paint_category_ratio{category="slow"} 0.0240

# Core Web Vitals thresholds
pagespeed_loading_experience_metrics_largest_contentful_paint_threshold_duration_seconds{threshold="good"} 2.5
pagespeed_loading_experience_metrics_largest_contentful_paint_threshold_duration_seconds{threshold="poor"} 4.0

The same pattern applies to INP, FCP, and TTFB. For CLS (which is unitless), the metrics omit the _duration_seconds suffix:

pagespeed_loading_experience_metrics_cumulative_layout_shift_score 0.0
pagespeed_loading_experience_metrics_cumulative_layout_shift_score_category_ratio{category="fast"} 0.9994
pagespeed_loading_experience_metrics_cumulative_layout_shift_score_threshold{threshold="good"} 0.1

Performance Categories

• Fast - Meets Google's "good" threshold (provides a good user experience)
• Average - Between "good" and "poor" thresholds (needs improvement)
• Slow - Exceeds "poor" threshold (provides a poor user experience)

Data Availability

CrUX data is based on real user measurements from Chrome browsers over the last 28 days. Metrics will only be available for:

• URLs with sufficient Chrome user traffic
• Origins (domains) with sufficient Chrome user traffic

If data is unavailable, the corresponding metrics will not be exported.

Building And Running

Building

$ make

Examples

To run pagespeed exporter we need to obtain the google api key for the pagespeed. Instructions how to create a key for pagespeed can be found here

pagespeed_exporter <arguments>

$ pagespeed_exporter -api-key {KEY} -targets https://google.com,https://prometheus.io -listener :80

Exporter Target Specification

Targets can be configured in either plaintext

https://github.com/foomo/pagespeed_exporter
https://mysite.com/test?test=true

Or via JSON which adds additional parameters

// URL can't be invalid
// Strategy can only be mobile/desktop
// If strategy is not specified, both desktop & mobile will be used
// Categories can be any of accessibility/best-practices/performance/seo
// If categories are not specified, all categories will be used
// Parameters are passed down to google pagespeed api

{"url":"https://github.com/foomo/pagespeed_exporter","campaign":"test","locale":"en","source":"source"}

{"url":"https://mysite.com/test?test=true","strategy":"mobile"}

{"url":"https://mysite.com/test?test=true","categories": ["best-practices"]}

Configuration specification in JSON and plain is supported both in command line & prometheus configuration

Exporter configuration

Configuration of targets can be done via docker and via prometheus

Flag	Variable	Description	Default	Required
-api-key	PAGESPEED_API_KEY	sets the google API key used for pagespeed		False
-targets	PAGESPEED_TARGETS	comma separated list of targets to measure		False
-categories	PAGESPEED_CATEGORIES	comma separated list of categories to check	accessibility,best-practices,performance,seo	False
-t	NONE	multi-value target array (check docker comp)		False
-listener	PAGESPEED_LISTENER	sets the listener address for the exporters	:9271	False
-parallel	PAGESPEED_PARALLEL	sets the execution of targets to be parallel	false	False
-pushGatewayUrl	PUSHGATEWAY_URL	sets the pushgateway url to send the metrics		False
-pushGatewayJob	PUSHGATEWAY_JOB	sets the pushgateway job name	pagespeed_exporter	False
-cache-ttl	CACHE_TTL	cache TTL for API results (e.g. 60s, 5m); disables cache if unset		False

Note: google api key is required only if scraping more than 2 targets/second

Note: exporter can be run without targets, and later targets provided via prometheus

Pushing metrics via push gateway

If you don't want to change the prometheus scrape_configs, you can send the metrics using push gateway using a batch job. Just configure the pushgateway url and use the /probe endpoint with query parameter target and the metrics will be send to prometheus.

curl http://localhost:9271/probe?target=https://www.example.com

Exporter Target Configuration (VIA PROMETHEUS)

Example configuration with simple and complex values

(Examples can ve found in the example folder)

  - job_name: pagespeed_exporter_probe
      metrics_path: /probe
      # Re-Label configurations so that we can use them
      # to configure the pagespeed exporter
      relabel_configs:
        - source_labels: [__address__]
          target_label: __param_target
        - source_labels: [__param_target]
          target_label: instance
        - target_label: __address__
          replacement: "pagespeed_exporter:9271"
      static_configs:
        - targets:
            - 'https://example.com/' # Example PLAIN
            - '{"url":"https://example.com/","campaign":"test","locale":"en","source":"source"}'  
            - '{"url":"https://example.com/mobileonly","strategy":"mobile"}'                    

Docker

$ docker run -p "9271:9271" --rm foomo/pagespeed_exporter -api-key {KEY} -t https://google.com,https://prometheus.io

or

$ docker run -p "9271:9271" --rm \
    --env PAGESPEED_API_KEY={KEY} \
    --env PAGESPEED_TARGETS=https://google.com,https://prometheus.io \
    --env PAGESPEED_CATEGORIES=accessibility,seo \
    foomo/pagespeed_exporter

Prometheus & Docker Compose

Check out the docker-compose folder

Kubernetes/Helm

Deploy PageSpeed Exporter to Kubernetes using the included Helm chart. First, create a secret with your API key (only required if monitoring more than 2 targets/sec):

kubectl create secret generic pagespeed-configuration-secret \
  --from-literal=PAGESPEED_API_KEY=your-api-key-here

Install the chart with your target URLs:

helm install pagespeed-exporter ./helm/pagespeed-exporter \
  --set 'config.targets={https://www.example.com,https://www.yoursite.com}' \
  --set config.parallel=true

Test the deployment:

kubectl port-forward svc/pagespeed-exporter 9271:9271
curl http://localhost:9271/metrics

For detailed configuration options, installation examples, and Prometheus integration, see the Helm Chart README.