bvandeusen
230b542015
- Rename package fablednetmon → fabledscryer throughout - Multi-dashboard: ownership, per-user defaults, HTMX edit (add/remove/reorder) - Read-only share tokens scoped to individual dashboards - Dashboard edit is HTMX-driven (no page reloads) - Plugin management system: remote catalog, download/install, hot-reload, in-app restart - plugin_index.py: fetch/cache remote index.yaml; default URL → bvandeusen/fabledscryer-plugins - plugin_manager.py: download_and_install_plugin, hot_reload_plugin, restart_app - ZIP extraction handles GitHub archive formats (name-v1.0.0/, name-main/) - Settings split into tabbed sections: General, Notifications, Ansible, Plugins - Plugins tab: catalog browser (HTMX), install/activate/update/restart actions - UI/branding: dark palette (#07071a), crystal ball SVG logo, animated star field, Libertinus Serif applied to headings, nav, labels, and section titles - Widget registry (core/widgets.py) for dashboard plugin integration - UPS widget.html (dashboard card) and settings/_tabs.html include - Migrations 0005–0008: dashboards, is_default, ownership, share tokens - docs/plugins/: writing-a-plugin.md updated with publishing guide, index.yaml.example template for fabledscryer-plugins repo Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
116 lines
4.2 KiB
Markdown
116 lines
4.2 KiB
Markdown
# Traefik Plugin
|
|
|
|
The Traefik plugin scrapes the Traefik reverse proxy's Prometheus `/metrics` endpoint on a configurable interval, stores per-router metrics, and surfaces them on the dashboard and a dedicated detail page.
|
|
|
|
---
|
|
|
|
## What It Does
|
|
|
|
On each scrape:
|
|
1. Fetches raw Prometheus text from the configured `metrics_url`
|
|
2. Parses histogram and counter data to compute per-router rates and latency approximations
|
|
3. Writes computed metrics to the `traefik_metrics` history table
|
|
4. Calls `record_metric()` for each metric, making them available to alert rules
|
|
|
|
Request rates and error rates are computed as deltas between the current and previous scrape, divided by elapsed time. Latency percentiles (p50, p95, p99) are approximated via linear interpolation over histogram buckets — these are estimates, not exact percentiles.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
| Key | Default | Description |
|
|
|---|---|---|
|
|
| `metrics_url` | `http://localhost:8080/metrics` | Traefik Prometheus endpoint |
|
|
| `scrape_interval_seconds` | `60` | How often to scrape |
|
|
|
|
Enable the plugin by setting `enabled: true` in the app settings (Settings UI or directly in `app_settings` DB table under key `plugin.traefik`).
|
|
|
|
Traefik must have metrics enabled. In Traefik config:
|
|
|
|
```yaml
|
|
# traefik.yml
|
|
metrics:
|
|
prometheus: {}
|
|
```
|
|
|
|
---
|
|
|
|
## Metrics Collected
|
|
|
|
Per Traefik router, per scrape:
|
|
|
|
| Metric name | Description |
|
|
|---|---|
|
|
| `request_rate` | Requests per second (delta from previous scrape) |
|
|
| `error_rate_4xx_pct` | 4xx responses as % of total requests |
|
|
| `error_rate_5xx_pct` | 5xx responses as % of total requests |
|
|
| `latency_p50_ms` | Approximate p50 latency (ms) |
|
|
| `latency_p95_ms` | Approximate p95 latency (ms) |
|
|
| `latency_p99_ms` | Approximate p99 latency (ms) |
|
|
|
|
All metrics are available for alert rules with `source_module = "traefik"` and `resource_name = <router name>`.
|
|
|
|
---
|
|
|
|
## Alert Rule Examples
|
|
|
|
| Rule | source_module | resource_name | metric_name | operator | threshold |
|
|
|---|---|---|---|---|---|
|
|
| High 5xx rate on API router | `traefik` | `api@docker` | `error_rate_5xx_pct` | `>` | `1.0` |
|
|
| Slow API (p95 > 500ms) | `traefik` | `api@docker` | `latency_p95_ms` | `>` | `500` |
|
|
| Traffic spike | `traefik` | `web@docker` | `request_rate` | `>` | `1000` |
|
|
|
|
Router names are the Traefik router labels as reported in the Prometheus metrics (e.g. `api@docker`, `dashboard@internal`). Check the raw metrics at your `metrics_url` to see the exact names in use.
|
|
|
|
---
|
|
|
|
## UI
|
|
|
|
### Dashboard Widget
|
|
|
|
The widget appears on the dashboard when the Traefik plugin is enabled. It shows, per router:
|
|
|
|
- Router name
|
|
- Current req/s
|
|
- p95 latency (color-coded: green < 200ms, yellow < 500ms, red ≥ 500ms)
|
|
- 5xx error rate (shown only if > 0)
|
|
|
|
The widget auto-refreshes via HTMX polling every `poll_interval` seconds. Fragment endpoint: `GET /plugins/traefik/widget`.
|
|
|
|
### Detail Page
|
|
|
|
The full Traefik page at `/plugins/traefik/` shows all routers with sparkline history charts (last 20 data points) for request rate, p95 latency, and 5xx error rate.
|
|
|
|
---
|
|
|
|
## File Locations
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `plugins/traefik/__init__.py` | Plugin entry point: `setup()`, `get_scheduled_tasks()`, `get_blueprint()` |
|
|
| `plugins/traefik/plugin.yaml` | Plugin metadata and default config |
|
|
| `plugins/traefik/models.py` | `TraefikMetric` SQLAlchemy model |
|
|
| `plugins/traefik/scheduler.py` | `make_scrape_task()` and scrape logic |
|
|
| `plugins/traefik/scraper.py` | Prometheus text parsing and metric computation |
|
|
| `plugins/traefik/routes.py` | `GET /` (detail page) and `GET /widget` (HTMX fragment) |
|
|
| `plugins/traefik/migrations/` | Alembic migration for `traefik_metrics` table |
|
|
| `plugins/traefik/templates/traefik/` | `index.html` (detail) and `widget.html` (dashboard fragment) |
|
|
|
|
---
|
|
|
|
## Database Table
|
|
|
|
`traefik_metrics` (defined in `plugins/traefik/models.py`):
|
|
|
|
| Column | Type | Description |
|
|
|---|---|---|
|
|
| `id` | UUID | Primary key |
|
|
| `router_name` | str | Traefik router name |
|
|
| `scraped_at` | timestamp UTC | When this row was written |
|
|
| `request_rate` | float | req/s |
|
|
| `error_rate_4xx_pct` | float | % 4xx |
|
|
| `error_rate_5xx_pct` | float | % 5xx |
|
|
| `latency_p50_ms` | float | Approx p50 (ms) |
|
|
| `latency_p95_ms` | float | Approx p95 (ms) |
|
|
| `latency_p99_ms` | float | Approx p99 (ms) |
|