> **🚧 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.

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