1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
<div align="center">
<img src="logo.png" alt="Epimetheus Logo" width="400"/>
</div>
# Epimetheus
A versatile Go tool for pushing metrics to Prometheus (and Prometheus-compatible backends like VictoriaMetrics) and ClickHouse, with support for realtime and historic data ingestion.
## Why "Epimetheus"?
In Greek mythology, [Epimetheus](https://en.wikipedia.org/wiki/Epimetheus_(mythology)) is Prometheus's brother—"afterthought" or "hindsight" (while Prometheus means "forethought"). This tool brings data to Prometheus **after** collection: historic data from hours or days ago, or realtime data pushed on-demand. It's never too late to bring your metrics home.
## Overview
Epimetheus is a standalone binary that:
- Pushes metrics via **Pushgateway** (realtime) or **Remote Write API** (historic, watch)
- Optionally ingests to **ClickHouse** in watch mode
- Supports **Prometheus-compatible backends** (e.g. VictoriaMetrics) by using their Remote Write URL
- Offers modes: realtime, historic, backfill, auto, and watch (CSV file monitoring)
- Accepts CSV and JSON input and provides a Grafana dashboard for test metrics
## Quick Start
1. **Build:** `mage build` or `go build -o epimetheus cmd/epimetheus/main.go`
2. **Realtime (Pushgateway):** Deploy Pushgateway and Prometheus, then run:
```bash
./epimetheus -mode=realtime -continuous
```
3. **Watch (Remote Write):** Enable [Remote Write receiver](docs/operations/setup-prometheus.md), then:
```bash
./epimetheus -mode=watch -file=mydata.csv -metric-name=myapp -prometheus=http://localhost:9090/api/v1/write
```
4. **View:** Prometheus at http://localhost:9090 (after port-forward if needed). For full steps see [Quick Start](docs/guides/quickstart.md).
## Documentation
Full documentation is in the [docs](docs/README.md) directory:
| Section | Description |
|---------|-------------|
| [Guides](docs/guides/quickstart.md) | [Quick Start](docs/guides/quickstart.md), [Modes](docs/guides/modes.md), [Data Formats](docs/guides/data-formats.md), [CSV flexibility](docs/guides/csv-format-flexibility.md), [DNS resolution](docs/guides/dns-resolution.md), [Dtail example](docs/guides/dtail-metrics-example.md) |
| [Backends](docs/backends/prometheus.md) | [Prometheus / VictoriaMetrics](docs/backends/prometheus.md), [ClickHouse](docs/backends/clickhouse.md) |
| [Operations](docs/operations/setup-prometheus.md) | [Setup Prometheus](docs/operations/setup-prometheus.md), [Setup ClickHouse](docs/operations/setup-clickhouse.md), [Troubleshooting](docs/operations/troubleshooting.md), [Cleanup](docs/operations/cleanup.md), [macOS](docs/operations/macos-setup.md), [Kubernetes](docs/operations/kubernetes.md) |
| [Reference](docs/reference/cli.md) | [CLI](docs/reference/cli.md), [Test metrics](docs/reference/test-metrics.md), [Grafana dashboard](docs/reference/grafana-dashboard.md), [Example queries](docs/reference/example-queries.md), [Magefile](docs/reference/magefile.md) |
| [Design](docs/design/architecture.md) | [Architecture](docs/design/architecture.md) |
[Documentation index](docs/README.md) — complete list with one-line descriptions.
## Building
**Using Mage (recommended):**
```bash
go install github.com/magefile/mage@latest
mage build
mage test
mage run # realtime mode
```
See [Magefile reference](docs/reference/magefile.md) for all targets.
**Using Go:**
```bash
go build -o epimetheus cmd/epimetheus/main.go
go test ./...
```
## Project Structure
```
epimetheus/
├── cmd/epimetheus/ # Main entry point
├── internal/ # config, ingester, metrics, parser, resolver, watcher
├── docs/ # Documentation
├── scripts/ # Helper shell scripts (verify-clickhouse, generate-test-data, etc.)
├── test-data/ # Test CSVs
├── Magefile.go # Build and run targets
└── README.md
```
## Version
Current version: 0.0.0
## License
See LICENSE file for details.
|
