Initial plugin setup (v0.0.1)

- Create initial WordPress plugin structure - Add Prometheus metrics collector with default metrics - Implement authenticated /metrics endpoint with Bearer token - Add license management integration - Create admin settings page under Settings > Metrics - Set up Gitea CI/CD pipeline for automated releases - Add extensibility via wp_prometheus_collect_metrics hook Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-01 15:31:21 +01:00
commit 7ff87f7c8d
21 changed files with 2890 additions and 0 deletions
--- a/PLAN.md
+++ b/PLAN.md
@@ -0,0 +1,190 @@
+# 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