Metadata-Version: 2.4
Name: tcms-prometheus-exporter
Version: 0.1.0
Summary: Prometheus metrics exporter plugin for Kiwi TCMS
Author-email: Achmad Fienan Rahardianto <veenone@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/veenone/tcms-prometheus-exporter
Keywords: tcms,kiwi,plugin,prometheus,metrics
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: prometheus-client>=0.17.0
Dynamic: license-file

# tcms-prometheus-exporter

A Kiwi TCMS plugin that exposes Prometheus-format metrics for scraping.

![Dashboard Screenshot](https://raw.githubusercontent.com/veenone/kiwi-tcms-prometheus-exporter-plugin/master/docs/dashboard.png)

## Installation

```bash
pip install -e /path/to/tcms-prometheus-exporter
```

Then add to `INSTALLED_APPS` (handled automatically via the `kiwitcms.plugins` entry point).

Restart Kiwi TCMS.

## Metrics Endpoint

Once installed, the following URLs are available:

- `/tcms_prometheus_exporter/` — Dashboard (requires login)
- `/tcms_prometheus_exporter/metrics/` — Prometheus scrape endpoint

## Token Protection

By default, the `/metrics/` endpoint is open (no authentication required so that Prometheus can scrape it).

To add token-based protection, set the `PROMETHEUS_METRICS_TOKEN` environment variable:

```bash
export PROMETHEUS_METRICS_TOKEN=my-secret-token
```

Then configure Prometheus to pass the token as a query parameter:

```yaml
scrape_configs:
  - job_name: 'kiwi-tcms'
    params:
      token: ['my-secret-token']
    metrics_path: '/tcms_prometheus_exporter/metrics/'
    static_configs:
      - targets: ['your-kiwi-host:8000']
```

## Exposed Metrics (23 total)

### Test Cases (4)
| Metric | Labels | Description |
|---|---|---|
| `kiwi_test_cases_total` | product, status, priority, is_automated | Total test cases |
| `kiwi_test_cases_by_status` | status | Test cases by status |
| `kiwi_test_cases_by_priority` | priority | Test cases by priority |
| `kiwi_test_cases_automated_total` | automated | Test cases by automation status |

### Test Plans (3)
| Metric | Labels | Description |
|---|---|---|
| `kiwi_test_plans_total` | product, type, is_active | Total test plans |
| `kiwi_test_plans_active_total` | — | Active test plans |
| `kiwi_test_plans_cases_count` | plan_id, plan_name, product | Cases per active plan |

### Test Runs (4)
| Metric | Labels | Description |
|---|---|---|
| `kiwi_test_runs_total` | product, plan_name | Total test runs |
| `kiwi_test_runs_active_total` | — | Active (not stopped) test runs |
| `kiwi_test_runs_completion_percent` | run_id, run_summary, product | Completion % (recent 100 active) |
| `kiwi_test_runs_pass_rate_percent` | run_id, run_summary, product | Pass rate % (recent 100 active) |

### Test Executions (3)
| Metric | Labels | Description |
|---|---|---|
| `kiwi_test_executions_total` | product, status | Total executions |
| `kiwi_test_executions_by_status` | status, weight_class | Executions by status with weight class |
| `kiwi_test_execution_pass_rate` | — | Overall pass rate % |

### Products & Builds (2)
| Metric | Labels | Description |
|---|---|---|
| `kiwi_products_total` | — | Total products |
| `kiwi_builds_total` | product, is_active | Total builds |

### Users & Activity (6)
| Metric | Labels | Description |
|---|---|---|
| `kiwi_users_total` | is_active, is_staff | Registered users by active/staff status |
| `kiwi_users_logged_in_total` | period | Users who logged in within period (7d, 30d, 90d, never) |
| `kiwi_user_test_cases_authored` | username | Test cases authored per user |
| `kiwi_user_test_plans_authored` | username | Test plans authored per user |
| `kiwi_user_test_runs_managed` | username | Test runs managed per user |
| `kiwi_user_test_executions_completed` | username | Test executions completed per user |

### Instance Info (1)
| Metric | Labels | Description |
|---|---|---|
| `kiwi_instance_info` | version | Kiwi TCMS version |

## License

MIT
