From c426b9b5133edb72ebe81cac7079f8a7b15e5d61 Mon Sep 17 00:00:00 2001 From: qpismont Date: Sun, 26 Jul 2026 11:56:58 +0000 Subject: [PATCH] update readme --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index 93d73d8..1c1de1e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ Herald is a Gitea bot that performs automated AI-powered code reviews on pull re - Concurrent review processing with configurable parallelism - Graceful shutdown — in-progress reviews finish before the process exits - Error tracking via Sentry +- Prometheus metrics endpoint for monitoring - Tiny memory footprint (~4MB) thanks to Rust ## Installation @@ -34,6 +35,7 @@ Herald reads its configuration from environment variables (a `.env` file is supp | `GITEA_URL` | Base URL of your Gitea instance | | `GITEA_TOKEN` | Gitea API token | | `GITEA_TIMEOUT` | Gitea API request timeout in seconds | +| `METRICS_BIND_ADDR` | *(optional)* Bind address for the Prometheus metrics endpoint (e.g. `0.0.0.0:9100`). If unset, the metrics exporter is disabled. | | `SENTRY_DSN` | *(optional)* Sentry DSN for error tracking | | `RUST_LOG` | *(optional)* Log level, defaults to `info` | @@ -51,3 +53,40 @@ cargo run ``` Copy `.env.example` to `.env` and fill in your values before running. + +## Metrics + +Herald optionally exposes a Prometheus metrics endpoint, useful for scraping with an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) or any Prometheus-compatible scraper. + +Set `METRICS_BIND_ADDR` (e.g. `0.0.0.0:9100`) to enable it. The metrics are then available at `http://:9100/metrics`. + +### Exposed metrics + +| Metric | Type | Description | +|---|---|---| +| `herald_webhooks_received_total` | counter | Total webhooks received (label: `event_type`) | +| `herald_webhooks_duplicate_total` | counter | Webhooks rejected as duplicates (label: `event_type`) | +| `herald_webhooks_channel_full_total` | counter | Webhooks dropped because the bot channel was full (label: `event_type`) | +| `herald_bot_tasks_active` | gauge | Bot tasks currently in progress | +| `herald_bot_tasks_completed_total` | counter | Bot tasks completed successfully (label: `event_type`) | +| `herald_bot_tasks_failed_total` | counter | Bot tasks that failed (label: `event_type`) | +| `herald_openrouter_cost_cents_total` | counter | Total OpenRouter cost in cents (divide by 100 for USD) | + +### OTel collector example + +```yaml +receivers: + prometheus: + config: + scrape_configs: + - job_name: herald + scrape_interval: 15s + static_configs: + - targets: ["herald:9100"] + +service: + pipelines: + metrics: + receivers: [prometheus] + exporters: [otlp] +``` \ No newline at end of file