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
│   ├── 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:

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

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

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

```yaml
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