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

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

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

- Request/Response timing metrics
- HTTP status code counters
- Database query metrics

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