wp-prometheus/README.md

WP Prometheus

A WordPress plugin that provides a Prometheus-compatible /metrics endpoint with extensible hooks for custom metrics.

Features

• Prometheus-compatible authenticated /metrics endpoint
• Default WordPress metrics (users, posts, comments, plugins)
• Runtime metrics (HTTP requests, database queries)
• Cron job and transient cache metrics
• WooCommerce integration (products, orders, revenue)
• Custom metric builder with admin UI
• Grafana dashboard templates with download
• Extensible by other plugins using hooks
• Dashboard extension hook for third-party Grafana dashboards
• Settings page under Settings > Metrics
• Bearer token authentication
• License management integration

Requirements

• PHP 8.3 or higher
• WordPress 6.4 or higher
• Composer (for development)

Installation

From Release Package

1. Download the latest release from the releases page
2. Upload the zip file via Plugins > Add New > Upload Plugin
3. Activate the plugin
4. Configure settings under Settings > Metrics

From Source

1. Clone the repository to your WordPress plugins directory:

   cd wp-content/plugins/
   git clone https://src.bundespruefstelle.ch/magdev/wp-prometheus.git
   cd wp-prometheus
   git submodule update --init --recursive
   composer install
   

2. Activate the plugin in WordPress admin

Configuration

License

1. Go to Settings > Metrics
2. Enter your license server URL, license key, and server secret
3. Click "Save License Settings"
4. Click "Validate License" or "Activate License"

Authentication Token

A random auth token is generated on activation. You can view it or regenerate it in Settings > Metrics.

Prometheus Configuration

Add the following to your prometheus.yml:

scrape_configs:
  - job_name: 'wordpress'
    static_configs:
      - targets: ['your-wordpress-site.com']
    metrics_path: '/metrics/'
    scheme: 'https'
    authorization:
      type: Bearer
      credentials: 'your-auth-token-from-settings'

Default Metrics

Static Metrics

Metric	Type	Labels	Description
wordpress_info	Gauge	version, php_version, multisite	WordPress installation info
wordpress_users_total	Gauge	role	Total users by role
wordpress_posts_total	Gauge	post_type, status	Total posts by type and status
wordpress_comments_total	Gauge	status	Total comments by status
wordpress_plugins_total	Gauge	status	Total plugins (active/inactive)

Runtime Metrics (v0.1.0+)

Metric	Type	Labels	Description
wordpress_http_requests_total	Counter	method, status, endpoint	Total HTTP requests
wordpress_http_request_duration_seconds	Histogram	method, endpoint	Request duration distribution
wordpress_db_queries_total	Counter	endpoint	Total database queries
wordpress_db_query_duration_seconds	Histogram	endpoint	Query duration (requires SAVEQUERIES)

Note: Runtime metrics aggregate data across requests. Enable only the metrics you need to minimize performance impact.

Enabling Database Query Timing

The wordpress_db_query_duration_seconds histogram requires WordPress's SAVEQUERIES constant to be enabled. Add this to your wp-config.php:

define( 'SAVEQUERIES', true );

Important considerations:

• SAVEQUERIES has a performance overhead as it logs all queries with timing and call stacks
• Recommended for development/staging environments, use with caution in production
• Without SAVEQUERIES, only query counts (wordpress_db_queries_total) are available
• The histogram shows total query time per request, grouped by endpoint

Cron Metrics (v0.2.0+)

Metric	Type	Labels	Description
wordpress_cron_events_total	Gauge	hook	Scheduled cron events by hook
wordpress_cron_overdue_total	Gauge	-	Number of overdue cron events
wordpress_cron_next_run_timestamp	Gauge	-	Unix timestamp of next scheduled cron

Transient Metrics (v0.2.0+)

Metric	Type	Labels	Description
wordpress_transients_total	Gauge	type	Transients by type (total, with_expiration, persistent, expired)

WooCommerce Metrics (v0.2.0+)

These metrics are only available when WooCommerce is active.

Metric	Type	Labels	Description
wordpress_woocommerce_products_total	Gauge	status, type	Products by status and type
wordpress_woocommerce_orders_total	Gauge	status	Orders by status
wordpress_woocommerce_revenue_total	Gauge	period, currency	Revenue (all_time, today, month)
wordpress_woocommerce_customers_total	Gauge	type	Customers (registered, guest)

Note: WooCommerce metrics support both legacy post-based orders and HPOS (High-Performance Order Storage).

Extending with Custom Metrics

Add your own metrics using the wp_prometheus_collect_metrics action:

add_action( 'wp_prometheus_collect_metrics', function( $collector ) {
    // Register a gauge
    $gauge = $collector->register_gauge(
        'my_custom_metric',
        'Description of my metric',
        array( 'label1', 'label2' )
    );

    // Set value with labels
    $gauge->set( 42, array( 'value1', 'value2' ) );
} );

Available Methods

// Gauge (can go up and down)
$gauge = $collector->register_gauge( $name, $help, $labels );
$gauge->set( $value, $labelValues );

// Counter (only goes up)
$counter = $collector->register_counter( $name, $help, $labels );
$counter->inc( $labelValues );
$counter->incBy( $amount, $labelValues );

// Histogram (for distributions)
$histogram = $collector->register_histogram( $name, $help, $labels, $buckets );
$histogram->observe( $value, $labelValues );

Extending with Custom Dashboards (v0.4.6+)

Add your own Grafana dashboard templates using the wp_prometheus_register_dashboards action:

add_action( 'wp_prometheus_register_dashboards', function( $provider ) {
    // File-based dashboard
    $provider->register_dashboard( 'my-plugin-dashboard', array(
        'title'       => __( 'My Plugin Metrics', 'my-plugin' ),
        'description' => __( 'Dashboard for my custom metrics', 'my-plugin' ),
        'icon'        => 'dashicons-chart-bar',
        'file'        => MY_PLUGIN_PATH . 'assets/dashboards/my-dashboard.json',
        'plugin'      => 'My Plugin Name',
    ) );

    // OR inline JSON dashboard
    $provider->register_dashboard( 'dynamic-dashboard', array(
        'title'       => __( 'Dynamic Dashboard', 'my-plugin' ),
        'description' => __( 'Dynamically generated dashboard', 'my-plugin' ),
        'icon'        => 'dashicons-admin-generic',
        'json'        => json_encode( $dashboard_array ),
        'plugin'      => 'My Plugin Name',
    ) );
} );

Registration Parameters

Parameter	Required	Description
title	Yes	Dashboard title displayed in admin
description	No	Description shown below the title
icon	No	Dashicon class (default: dashicons-chart-line)
file	Yes*	Absolute path to JSON file
json	Yes*	Inline JSON content
plugin	No	Plugin name for attribution

*Either file or json is required, but not both.

Security Notes

• File paths must be absolute and within wp-content/
• Inline JSON is validated during registration
• Third-party dashboards are marked with an "Extension" badge in the admin UI

Development

Build for Release

# Set PHP platform version
composer config platform.php 8.3.0

# Install production dependencies
composer install --no-dev --optimize-autoloader

# Compile translations
for po in languages/*.po; do msgfmt -o "${po%.po}.mo" "$po"; done

Create Release Package

From the plugins directory (parent of wp-prometheus):

cd /wp-content/plugins/
zip -r wp-prometheus/releases/wp-prometheus-x.x.x.zip wp-prometheus \
  -x "wp-prometheus/.git/*" \
  -x "wp-prometheus/.gitea/*" \
  -x "wp-prometheus/.claude/*" \
  -x "wp-prometheus/CLAUDE.md" \
  -x "wp-prometheus/wp-core" \
  -x "wp-prometheus/wp-plugins" \
  -x "wp-prometheus/releases/*" \
  -x "wp-prometheus/composer.lock" \
  -x "*.DS_Store"

Author

Marco Graetsch

• Website: https://src.bundespruefstelle.ch/magdev
• Email: magdev3.0@gmail.com

License

This plugin is licensed under the GPL v2 or later.

Credits

• PromPHP/prometheus_client_php - Prometheus client library
• Built with Claude AI assistance