wp-prometheus/PLAN.md

WP Prometheus Implementation Plan

Overview

This document outlines the implementation plan for the WP Prometheus plugin, providing a Prometheus-compatible /metrics endpoint for WordPress.

Architecture

Core Components

1. Plugin Bootstrap (wp-prometheus.php)

   • WordPress plugin header
   • Version constants
   • PHP/WordPress version checks
   • Autoloader initialization
   • Activation/Deactivation hooks

2. Plugin Class (src/Plugin.php)

   • Singleton pattern
   • Component initialization
   • Hook registration
   • Text domain loading

3. Installer (src/Installer.php)

   • Activation logic
   • Default options setup
   • Rewrite rules flushing
   • Uninstallation cleanup

4. License Manager (src/License/Manager.php)

   • Integration with wc-licensed-product-client
   • License validation/activation
   • Status caching (24-hour transient)
   • AJAX handlers for admin actions

5. Metrics Collector (src/Metrics/Collector.php)

   • Prometheus CollectorRegistry wrapper
   • Default WordPress metrics
   • Custom metric registration hooks
   • Extensibility via wp_prometheus_collect_metrics action

6. Metrics Endpoint (src/Endpoint/MetricsEndpoint.php)

   • Custom rewrite rule for /metrics/
   • Bearer token authentication
   • Prometheus text format output
   • Cache control headers

7. Admin Settings (src/Admin/Settings.php)

   • Settings page under Settings > Metrics
   • License configuration form
   • Auth token management
   • Metric toggle checkboxes

Directory Structure

wp-prometheus/
├── .gitea/workflows/
│   └── release.yml          # CI/CD pipeline
├── assets/
│   ├── css/                  # Admin/Frontend styles
│   ├── dashboards/           # Grafana dashboard templates
│   └── js/
│       └── admin.js          # Admin JavaScript
├── languages/                # Translation files
├── lib/
│   └── wc-licensed-product-client/  # Git submodule
├── releases/                 # Release packages
├── src/
│   ├── Admin/
│   │   ├── DashboardProvider.php
│   │   └── Settings.php
│   ├── Endpoint/
│   │   └── MetricsEndpoint.php
│   ├── License/
│   │   └── Manager.php
│   ├── Metrics/
│   │   ├── Collector.php
│   │   ├── CustomMetricBuilder.php
│   │   ├── RuntimeCollector.php
│   │   └── StorageFactory.php
│   ├── Installer.php
│   ├── Plugin.php
│   └── index.php
├── CHANGELOG.md
├── CLAUDE.md
├── composer.json
├── index.php
├── PLAN.md
├── README.md
├── uninstall.php
└── wp-prometheus.php

Default Metrics

The plugin provides the following default metrics (can be toggled in settings):

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

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)

Extensibility

Adding Custom Metrics

Third-party plugins can add custom metrics using the wp_prometheus_collect_metrics action:

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

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

Available Methods

• $collector->register_gauge( $name, $help, $labels )
• $collector->register_counter( $name, $help, $labels )
• $collector->register_histogram( $name, $help, $labels, $buckets )

Authentication

The /metrics endpoint requires authentication using a Bearer token:

# Prometheus configuration
scrape_configs:
  - job_name: 'wordpress'
    static_configs:
      - targets: ['example.com']
    metrics_path: '/metrics/'
    scheme: 'https'
    authorization:
      type: Bearer
      credentials: 'your-auth-token'

Alternatively, the token can be passed as a query parameter (for testing):

https://example.com/metrics/?token=your-auth-token

Storage Configuration

The plugin supports multiple storage backends for Prometheus metrics:

Available Adapters

Adapter	Description	Use Case
In-Memory	Default, no persistence	Development, single request metrics
Redis	Shared storage across instances	Production, load-balanced environments
APCu	High-performance local cache	Production, single-server deployments

Environment Variables

For Docker or containerized environments, configure storage via environment variables:

# Storage adapter selection
WP_PROMETHEUS_STORAGE_ADAPTER=redis

# Redis configuration
WP_PROMETHEUS_REDIS_HOST=redis
WP_PROMETHEUS_REDIS_PORT=6379
WP_PROMETHEUS_REDIS_PASSWORD=secret
WP_PROMETHEUS_REDIS_DATABASE=0
WP_PROMETHEUS_REDIS_PREFIX=WORDPRESS_PROMETHEUS_

# APCu configuration
WP_PROMETHEUS_APCU_PREFIX=wp_prom

Docker Compose Example

services:
  wordpress:
    image: wordpress:latest
    environment:
      WP_PROMETHEUS_STORAGE_ADAPTER: redis
      WP_PROMETHEUS_REDIS_HOST: redis
      WP_PROMETHEUS_REDIS_PORT: 6379
    depends_on:
      - redis

  redis:
    image: redis:alpine

Future Enhancements

No planned features at this time.

Dependencies

• PHP 8.3+
• WordPress 6.4+
• Composer packages:
  • promphp/prometheus_client_php - Prometheus client library
  • magdev/wc-licensed-product-client - License validation

Security Considerations

1. Auth token stored securely in WordPress options
2. Bearer token authentication for metrics endpoint
3. Admin capability check for settings
4. Nonce verification for AJAX requests
5. Input sanitization and output escaping
6. Direct file access prevention

License

GPL v2 or later