🚧 PRE-ALPHA SOFTWARE: This project is in a pre-alpha state and is intended for my own personal use only. Use at your own risk.

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 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:

   ./epimetheus -mode=realtime -continuous
   

3. Watch (Remote Write): Enable Remote Write receiver, then:

   ./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.

Documentation

Full documentation is in the docs directory:

Section	Description
Guides	Quick Start, Modes, Data Formats, CSV flexibility, DNS resolution, Dtail example
Backends	Prometheus / VictoriaMetrics, ClickHouse
Operations	Setup Prometheus, Setup ClickHouse, Troubleshooting, Cleanup, macOS, Kubernetes
Reference	CLI, Test metrics, Grafana dashboard, Example queries, Magefile
Design	Architecture

Documentation index — complete list with one-line descriptions.

Building

Using Mage (recommended):

go install github.com/magefile/mage@latest
mage build
mage test
mage run   # realtime mode

See Magefile reference for all targets.

Using Go:

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.