Skip to content
HELMET Source Back to HELMET
Menu

Metrics#

This page is for the opt-in Prometheus metrics endpoint: how to turn it on, how to gate access, and what the response carries. Read it before you expose /metrics, then pick the section that matches your stack.

HELMET can expose a Prometheus metrics endpoint. It is off by default and stays off until you turn it on. No Prometheus scraper is wired yet; the endpoint is there for when one is.

The goal#

Expose a single endpoint that reports the PHP and HELMET versions, gated so only an authorized scraper can read it. The endpoint speaks Prometheus exposition format, uses no personal data in labels, and keeps labels low-cardinality.

Enable it#

Set HELMET_METRICS_ENABLED=true and choose at least one way to prove who is asking:

Variable What it does
HELMET_METRICS_TOKEN A bearer token. The scraper sends Authorization: Bearer <token>. Compared with hash_equals.
HELMET_METRICS_ALLOW Comma-separated IPs or CIDR ranges allowed to scrape without a token.

Laravel#

The provider registers a Route::helmetMetrics() macro. The route is not created until you call it:

// routes/web.php
Route::helmetMetrics();                          // GET /metrics, throttle:60,1
Route::helmetMetrics('/metrics', 'throttle:120,1'); // your own throttle
Route::helmetMetrics('/metrics', null);           // no throttle

The controller reads helmet.metrics from the published config, resolves the client IP through the same trusted-proxy list the headers use, and renders text/plain; version=0.0.4.

Raw PHP#

use function Waynestate\Helmet\helmet_metrics;

$result = helmet_metrics([
    'enabled' => true,
    'token'   => 's3cret',
    'allow'   => ['10.0.0.0/8'],
    'preset'  => 'citadel',
]);

http_response_code($result['status']);
header('Content-Type: ' . $result['content_type']);
echo $result['body'];

What the response carries#

The response carries a helmet_info gauge with the PHP and HELMET versions, and a helmet_php_version_status gauge when a PolicySource is available. No personal data in labels; labels stay low-cardinality.

The endpoint is the only place in HELMET that says "I am still here" without saying "here is your page". A lullaby, in a way.

Graph it in Grafana#

The fleet dashboard for these metrics ships in docs/grafana/helmet.json: in Grafana, open Dashboards, New, Import, paste the file, and pick your Prometheus data source for the DS_PROMETHEUS input. It shows how many apps report, which HELMET and PHP versions they run, the PHP support status of each app, every reporting instance, and whether Prometheus can reach them.

A sample scrape config for a Prometheus server, with a bearer token file and example targets:

scrape_configs:
  - job_name: helmet
    metrics_path: /metrics
    authorization:
      credentials_file: /etc/prometheus/secrets/helmet-token
    static_configs:
      - targets:
          - app-one.example.test:80
          - app-two.example.test:80

WSU has no Prometheus server yet (decision D-024), so the dashboard is ready, not live: it graphs as soon as a server exists and scrapes /metrics.