# Epimetheus Documentation

Documentation for Epimetheus: a Go tool for pushing metrics to Prometheus (and Prometheus-compatible backends) and ClickHouse.

## Index

### Guides

| Document | Description |
|----------|-------------|
| [Quick Start](guides/quickstart.md) | Minimal path to first push: build, run, view in Prometheus or ClickHouse |
| [Operating Modes](guides/modes.md) | Realtime, historic, backfill, auto, and watch modes with examples |
| [Data Formats](guides/data-formats.md) | Epimetheus CSV and JSON input formats |
| [CSV Format Flexibility](guides/csv-format-flexibility.md) | Use any tabular CSV; numeric vs string columns; sanitization and examples |
| [DNS Resolution](guides/dns-resolution.md) | IP-to-hostname resolution for watch mode labels |
| [Dtail Metrics Example](guides/dtail-metrics-example.md) | Walkthrough using dtail.csv |

### Ingestion Backends

| Document | Description |
|----------|-------------|
| [Prometheus (and Prometheus-compatible)](backends/prometheus.md) | Pushgateway, Remote Write, time ranges; VictoriaMetrics via same URL |
| [ClickHouse](backends/clickhouse.md) | Watch-mode ingestion; table schema; verify script |

### Operations

| Document | Description |
|----------|-------------|
| [Setup: Prometheus](operations/setup-prometheus.md) | Enable Remote Write receiver, scrape config, retention |
| [Setup: ClickHouse](operations/setup-clickhouse.md) | Table creation, verification |
| [Troubleshooting](operations/troubleshooting.md) | Connection issues, metrics not appearing, out-of-order errors |
| [Cleanup](operations/cleanup.md) | Benchmark cleanup, Pushgateway delete, port-forwards |
| [macOS Setup](operations/macos-setup.md) | Homebrew, Prometheus args, Remote Write on macOS |
| [Kubernetes](operations/kubernetes.md) | Port-forwards, Helm, ConfigMaps |

### Reference

| Document | Description |
|----------|-------------|
| [CLI Reference](reference/cli.md) | All flags by mode with defaults |
| [Test Metrics](reference/test-metrics.md) | epimetheus_test_* metrics and types |
| [Grafana Dashboard](reference/grafana-dashboard.md) | Panels, deployment options, datasource |
| [Example Queries](reference/example-queries.md) | PromQL and curl examples |
| [Magefile](reference/magefile.md) | Mage build and run targets |

### Design

| Document | Description |
|----------|-------------|
| [Architecture](design/architecture.md) | Data flow, when to use Pushgateway vs Remote Write, backend choice |

### Helper scripts

Helper shell scripts live in **`scripts/`** at the repo root. Run them from the repo root (e.g. `./scripts/verify-clickhouse.sh`).

| Script | Purpose |
|--------|---------|
| `verify-clickhouse.sh` | Verify ClickHouse ingestion (row count, sample data) |
| `generate-test-data.sh` | Generate `test-all-ages.csv` for auto mode |
| `cleanup-benchmark-data.sh` | Delete benchmark metrics from Prometheus (Admin API) |
| `cleanup-benchmark-metrics.sh` | Same + starts port-forward, then cleans up |
| `benchmark-100mb.sh` | 100MB ingestion benchmark |
| `benchmark-1gb.sh` | 1GB ingestion benchmark |
| `backfill-historic-data.sh` | Backfill 7 days of historic data to Prometheus |
| `run.sh` | Port-forward Pushgateway and run epimetheus in realtime mode |
| `deploy-dashboard.sh` | Deploy Grafana dashboard via API (if present) |