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)
• Extensible by other plugins using hooks
• 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.

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 );

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