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
│   └── js/
│       └── admin.js          # Admin JavaScript
├── languages/                # Translation files
├── lib/
│   └── wc-licensed-product-client/  # Git submodule
├── releases/                 # Release packages
├── src/
│   ├── Admin/
│   │   └── Settings.php
│   ├── Endpoint/
│   │   └── MetricsEndpoint.php
│   ├── License/
│   │   └── Manager.php
│   ├── Metrics/
│   │   └── Collector.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

Future Enhancements

Version 0.2.0

• WooCommerce integration metrics
• Cron job metrics
• Transient cache metrics

Version 0.3.0

• Custom metric builder in admin
• Metric export/import
• Grafana dashboard templates

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