wc-licensed-product/docs/grafana-dashboard.md

# 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();
```