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

```txt
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:

```php
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:

```yaml
# 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):

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

## Future Enhancements

### 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