Add Grafana dashboard and wp-prometheus integration (v0.7.5)

- Add example Grafana dashboard with 24 panels for license metrics
- Register dashboard with wp-prometheus via hook
- Add dashboard documentation with PromQL examples and alerting rules
- Update README with monitoring section

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/grafana-dashboard.md

@@ -0,0 +1,219 @@
+# Grafana Dashboard for WC Licensed Product
+
+This dashboard provides comprehensive monitoring for the WC Licensed Product plugin using Prometheus metrics exposed via the [wp-prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) plugin.
+
+## Prerequisites
+
+1. **WP Prometheus Plugin** - Install and configure [wp-prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) on your WordPress site
+2. **Prometheus** - Configure Prometheus to scrape your WordPress metrics endpoint
+3. **Grafana** - Grafana 9.0+ with Prometheus data source configured
+4. **Enable Metrics** - In WordPress admin: WooCommerce > Settings > Licensed Products > Metrics > Enable Prometheus Metrics
+
+## Installation
+
+### Option 1: Via WP Prometheus Settings (Recommended)
+
+When metrics are enabled, the dashboard is automatically registered with wp-prometheus:
+
+1. Go to **Settings > WP Prometheus** in WordPress admin
+2. Navigate to the **Dashboards** tab
+3. Find "WC Licensed Product - License Metrics" in the list
+4. Click **Download JSON** to get the dashboard file
+5. Import the downloaded file into Grafana
+
+### Option 2: Manual Import
+
+1. Open Grafana and navigate to **Dashboards > Import**
+2. Upload the `grafana-dashboard.json` file or paste its contents
+3. Select your Prometheus data source
+4. Click **Import**
+
+### Configure Variables
+
+The dashboard includes two template variables:
+
+- **datasource** - Select your Prometheus data source
+- **instance** - Filter by WordPress instance (useful for multi-site monitoring)
+
+## Dashboard Panels
+
+### License Overview
+
+| Panel | Description |
+| --- | --- |
+| Total Licenses | Total count of all licenses |
+| Active Licenses | Licenses with `status=active` |
+| Lifetime Licenses | Licenses without expiration date |
+| Expiring Soon (30d) | Licenses expiring within 30 days |
+| Expired Licenses | Licenses with `status=expired` |
+| Revoked Licenses | Licenses with `status=revoked` |
+| Licenses by Status | Pie chart showing distribution |
+| License Status Over Time | Time series of license counts |
+
+### Downloads & Versions
+
+| Panel | Description |
+| --- | --- |
+| Total Downloads | Cumulative download count |
+| Active Product Versions | Number of active versions |
+| Downloads Over Time | Download trend graph |
+| Downloads (Selected Range) | Downloads in selected time range |
+
+### API Metrics
+
+| Panel | Description |
+| --- | --- |
+| API Requests (5m intervals) | Stacked bar chart by endpoint/result |
+| Requests by Endpoint | Donut chart of endpoint distribution |
+| Top API Requests | Table of most frequent requests |
+
+### Errors & Rate Limiting
+
+| Panel | Description |
+| --- | --- |
+| Rate Limit Events (Total) | Total HTTP 429 responses |
+| Validation Errors (Total) | Total validation failures |
+| Validation Errors Over Time | Error trend by type |
+| Validation Errors by Type | Pie chart breakdown |
+| Rate Limit Events by Endpoint | Rate limits per endpoint |
+
+## Metrics Reference
+
+### Gauges (current values)
+
+```promql
+# Licenses by status
+wclp_licenses_total{status="active|expired|revoked|inactive"}
+
+# Lifetime licenses (no expiration)
+wclp_licenses_lifetime_total
+
+# Licenses with expiration date
+wclp_licenses_expiring_total
+
+# Licenses expiring within 30 days
+wclp_licenses_expiring_soon
+
+# Total downloads
+wclp_downloads_total
+
+# Active product versions
+wclp_versions_active_total
+```
+
+### Counters (cumulative)
+
+```promql
+# API requests by endpoint and result
+wclp_api_requests_total{endpoint="validate|status|activate|update-check", result="success|error"}
+
+# Rate limit exceeded events
+wclp_rate_limit_exceeded_total{endpoint="validate|status|activate|update-check"}
+
+# Validation errors by type
+wclp_validation_errors_total{error_type="license_not_found|domain_mismatch|license_expired|license_revoked|..."}
+```
+
+## Example Prometheus Queries
+
+### Success Rate
+
+```promql
+sum(rate(wclp_api_requests_total{result="success"}[5m])) /
+sum(rate(wclp_api_requests_total[5m])) * 100
+```
+
+### Error Rate by Endpoint
+
+```promql
+sum by (endpoint) (rate(wclp_api_requests_total{result="error"}[5m]))
+```
+
+### License Churn (new activations)
+
+```promql
+increase(wclp_licenses_total{status="active"}[1d])
+```
+
+### Top Validation Errors
+
+```promql
+topk(5, sum by (error_type) (wclp_validation_errors_total))
+```
+
+## Alerting Examples
+
+Add these alerts to your Prometheus alerting rules:
+
+```yaml
+groups:
+  - name: wc-licensed-product
+    rules:
+      # High rate limit events
+      - alert: HighRateLimitEvents
+        expr: increase(wclp_rate_limit_exceeded_total[5m]) > 10
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High rate limiting on {{ $labels.endpoint }}"
+
+      # Many expiring licenses
+      - alert: LicensesExpiringSoon
+        expr: wclp_licenses_expiring_soon > 20
+        for: 1h
+        labels:
+          severity: info
+        annotations:
+          summary: "{{ $value }} licenses expiring within 30 days"
+
+      # API error rate
+      - alert: HighAPIErrorRate
+        expr: |
+          sum(rate(wclp_api_requests_total{result="error"}[5m])) /
+          sum(rate(wclp_api_requests_total[5m])) > 0.1
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "API error rate above 10%"
+```
+
+## Prometheus Configuration
+
+Add to your `prometheus.yml`:
+
+```yaml
+scrape_configs:
+  - job_name: 'wordpress'
+    metrics_path: '/metrics'
+    scheme: https
+    bearer_token: 'YOUR_WP_PROMETHEUS_TOKEN'
+    static_configs:
+      - targets: ['your-wordpress-site.com']
+```
+
+## Troubleshooting
+
+### No data showing
+
+1. Verify wp-prometheus is installed and configured
+2. Check that metrics are enabled in WC Licensed Product settings
+3. Confirm Prometheus can reach your WordPress metrics endpoint
+4. Check the data source selection in Grafana
+
+### Missing metrics
+
+Some metrics only appear after relevant actions occur:
+
+- `wclp_api_requests_total` - After API requests
+- `wclp_rate_limit_exceeded_total` - After rate limit events
+- `wclp_validation_errors_total` - After validation errors
+
+### Counter resets
+
+Counters persist in WordPress options and survive restarts. To reset:
+
+```php
+\Jeremias\WcLicensedProduct\Metrics\PrometheusController::resetCounters();
+```