wp-prometheus/README.md

# WP Prometheus

A WordPress plugin that provides a Prometheus-compatible `/metrics` endpoint with extensible hooks for custom metrics.

## Features

- Prometheus-compatible authenticated `/metrics` endpoint
- Default WordPress metrics (users, posts, comments, plugins)
- Runtime metrics (HTTP requests, database queries)
- Cron job and transient cache metrics
- WooCommerce integration (products, orders, revenue)
- Custom metric builder with admin UI
- Grafana dashboard templates with download
- Extensible by other plugins using hooks
- Dashboard extension hook for third-party Grafana dashboards
- Settings page under Settings > Metrics
- Bearer token authentication
- License management integration

## Requirements

- PHP 8.3 or higher
- WordPress 6.4 or higher
- Composer (for development)

## Installation

### From Release Package

1. Download the latest release from the [releases page](https://src.bundespruefstelle.ch/magdev/wp-prometheus/releases)
2. Upload the zip file via Plugins > Add New > Upload Plugin
3. Activate the plugin
4. Configure settings under Settings > Metrics

### From Source

1. Clone the repository to your WordPress plugins directory:

   ```bash
   cd wp-content/plugins/
   git clone https://src.bundespruefstelle.ch/magdev/wp-prometheus.git
   cd wp-prometheus
   git submodule update --init --recursive
   composer install
   ```

2. Activate the plugin in WordPress admin

## Configuration

### License

1. Go to Settings > Metrics
2. Enter your license server URL, license key, and server secret
3. Click "Save License Settings"
4. Click "Validate License" or "Activate License"

### Authentication Token

A random auth token is generated on activation. You can view it or regenerate it in Settings > Metrics.

### Prometheus Configuration

Add the following to your `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: 'wordpress'
    static_configs:
      - targets: ['your-wordpress-site.com']
    metrics_path: '/metrics/'
    scheme: 'https'
    authorization:
      type: Bearer
      credentials: 'your-auth-token-from-settings'
```

## Default Metrics

### 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 (v0.1.0+)

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

**Note:** Runtime metrics aggregate data across requests. Enable only the metrics you need to minimize performance impact.

### Cron Metrics (v0.2.0+)

| Metric | Type | Labels | Description |
|--------|------|--------|-------------|
| wordpress_cron_events_total | Gauge | hook | Scheduled cron events by hook |
| wordpress_cron_overdue_total | Gauge | - | Number of overdue cron events |
| wordpress_cron_next_run_timestamp | Gauge | - | Unix timestamp of next scheduled cron |

### Transient Metrics (v0.2.0+)

| Metric | Type | Labels | Description |
|--------|------|--------|-------------|
| wordpress_transients_total | Gauge | type | Transients by type (total, with_expiration, persistent, expired) |

### WooCommerce Metrics (v0.2.0+)

These metrics are only available when WooCommerce is active.

| Metric | Type | Labels | Description |
|--------|------|--------|-------------|
| wordpress_woocommerce_products_total | Gauge | status, type | Products by status and type |
| wordpress_woocommerce_orders_total | Gauge | status | Orders by status |
| wordpress_woocommerce_revenue_total | Gauge | period, currency | Revenue (all_time, today, month) |
| wordpress_woocommerce_customers_total | Gauge | type | Customers (registered, guest) |

**Note:** WooCommerce metrics support both legacy post-based orders and HPOS (High-Performance Order Storage).

## Extending with Custom Metrics

Add your own metrics using the `wp_prometheus_collect_metrics` action:

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

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

### Available Methods

```php
// Gauge (can go up and down)
$gauge = $collector->register_gauge( $name, $help, $labels );
$gauge->set( $value, $labelValues );

// Counter (only goes up)
$counter = $collector->register_counter( $name, $help, $labels );
$counter->inc( $labelValues );
$counter->incBy( $amount, $labelValues );

// Histogram (for distributions)
$histogram = $collector->register_histogram( $name, $help, $labels, $buckets );
$histogram->observe( $value, $labelValues );
```

## Extending with Custom Dashboards (v0.4.6+)

Add your own Grafana dashboard templates using the `wp_prometheus_register_dashboards` action:

```php
add_action( 'wp_prometheus_register_dashboards', function( $provider ) {
    // File-based dashboard
    $provider->register_dashboard( 'my-plugin-dashboard', array(
        'title'       => __( 'My Plugin Metrics', 'my-plugin' ),
        'description' => __( 'Dashboard for my custom metrics', 'my-plugin' ),
        'icon'        => 'dashicons-chart-bar',
        'file'        => MY_PLUGIN_PATH . 'assets/dashboards/my-dashboard.json',
        'plugin'      => 'My Plugin Name',
    ) );

    // OR inline JSON dashboard
    $provider->register_dashboard( 'dynamic-dashboard', array(
        'title'       => __( 'Dynamic Dashboard', 'my-plugin' ),
        'description' => __( 'Dynamically generated dashboard', 'my-plugin' ),
        'icon'        => 'dashicons-admin-generic',
        'json'        => json_encode( $dashboard_array ),
        'plugin'      => 'My Plugin Name',
    ) );
} );
```

### Registration Parameters

| Parameter | Required | Description |
| --------- | -------- | ----------- |
| `title` | Yes | Dashboard title displayed in admin |
| `description` | No | Description shown below the title |
| `icon` | No | Dashicon class (default: `dashicons-chart-line`) |
| `file` | Yes* | Absolute path to JSON file |
| `json` | Yes* | Inline JSON content |
| `plugin` | No | Plugin name for attribution |

*Either `file` or `json` is required, but not both.

### Security Notes

- File paths must be absolute and within `wp-content/`
- Inline JSON is validated during registration
- Third-party dashboards are marked with an "Extension" badge in the admin UI

## Development

### Build for Release

```bash
# Set PHP platform version
composer config platform.php 8.3.0

# Install production dependencies
composer install --no-dev --optimize-autoloader

# Compile translations
for po in languages/*.po; do msgfmt -o "${po%.po}.mo" "$po"; done
```

### Create Release Package

From the plugins directory (parent of wp-prometheus):

```bash
cd /wp-content/plugins/
zip -r wp-prometheus/releases/wp-prometheus-x.x.x.zip wp-prometheus \
  -x "wp-prometheus/.git/*" \
  -x "wp-prometheus/.gitea/*" \
  -x "wp-prometheus/.claude/*" \
  -x "wp-prometheus/CLAUDE.md" \
  -x "wp-prometheus/wp-core" \
  -x "wp-prometheus/wp-plugins" \
  -x "wp-prometheus/releases/*" \
  -x "wp-prometheus/composer.lock" \
  -x "*.DS_Store"
```

## Author

**Marco Graetsch**

- Website: <https://src.bundespruefstelle.ch/magdev>
- Email: magdev3.0@gmail.com

## License

This plugin is licensed under the GPL v2 or later.

## Credits

- [PromPHP/prometheus_client_php](https://github.com/PromPHP/prometheus_client_php) - Prometheus client library
- Built with Claude AI assistance