# gttl

> Ephemeral Grafana on Demand. Spin up instant, disposable Prometheus dashboards with auto-expiring TTLs. Zero inbound firewall changes, outbound reverse WebSocket tunnels, and drop-in Grafana JSON conversion.

Website: https://gttlsh.brimble.app
Repository: https://github.com/sodiqscript111/gttl
Full Specification: https://gttlsh.brimble.app/llms-full.txt

## Quickstart

### 1. Installation
Install the single static binary for your platform:
- Linux / macOS: `curl -fsSL https://gttlsh.brimble.app/install.sh | sh`
- Windows (PowerShell): `irm https://gttlsh.brimble.app/install.ps1 | iex`
- Docker: `docker run --rm -it -p 8080:8080 sodiqscript/gttl:latest`

### 2. Authentication (Optional)
Anonymous ephemeral sessions work out of the box with default templates. To save custom Grafana templates and sync across devices:
- Log in or create an account at https://gttlsh.brimble.app
- Run: `gttl auth login <your-api-key>`

### 3. Expose Prometheus Metrics
Point gttl to your internal Prometheus server or application metrics endpoint:
```bash
gttl create --prometheus http://localhost:9090 --ttl 2h --template http-api
```
- gttl dials an encrypted outbound TLS WebSocket to the central router (https://gttlsh.brimble.app).
- Zero inbound ports need to be opened in your firewall or security group.
- The terminal outputs a shareable live dashboard URL: `https://gttlsh.brimble.app/d/<id>?token=<token>`

### 4. Offline Simulation
If no local Prometheus server is running, simulate realistic synthetic metrics immediately:
```bash
gttl mock-prom --port 9090
```

---

## Core Capabilities

- **Zero Inbound Firewall Exposure**: Outbound-only reverse WebSocket tunnel. Private Prometheus servers remain on internal networks or localhost.
- **Auto-Expiring Lifecycle (TTL)**: Sessions evaporate cleanly after the specified duration (e.g. 15m, 1h, 2h, 24h). Background reapers garbage-collect in-memory streams.
- **Statistical Integrity (Volume Guardrails)**: Companion volume query checks sample counts before computing error rates to suppress misleading 100% spikes on low-traffic microservices.
- **Drop-in Grafana Converter**: Paste raw Grafana dashboard JSON on the web UI or pass `--config dashboard.json` to the CLI to convert 24-column grid panels into clean gttl definitions.
- **Built-in Templates**: Out-of-the-box panels for HTTP APIs (`http-api`), Node Exporter host metrics (`system`), and Kubernetes workloads (`kubernetes`).

---

## CLI Reference

### `gttl create`
Creates an ephemeral dashboard and connects your local Prometheus metrics.
- `--prometheus <url>`: Prometheus base URL (default: `http://localhost:9090`)
- `--ttl <duration>`: Session lifespan e.g. `15m`, `1h`, `2h`, `24h` (default: `1h`)
- `--template <name>`: Template name (`http-api`, `system`, `kubernetes`, or custom saved template)
- `--title <title>`: Human-readable title for the dashboard
- `--config <path>`: Path to custom gttl or exported Grafana JSON file
- `--port <port>`: Local port when running embedded server mode (default: `8080`)

### `gttl auth login <api-key>`
Saves the API key to `~/.gttl/credentials.json` for authenticated template access.

### `gttl auth logout`
Clears local credentials.

### `gttl mock-prom`
Runs a synthetic Prometheus-compatible metrics server on `--port 9090` with randomized traffic, error spikes, and P95 latency distributions.

---

## HTTP REST & WebSocket API

Base URL: `https://gttlsh.brimble.app`

### Public Endpoints
- `GET /healthz` -> Returns health status `{"status":"ok"}`
- `GET /install.sh` -> Shell script installer for Linux/macOS
- `GET /install.ps1` -> PowerShell script installer for Windows
- `GET /bin/{platform}/{filename}` -> Direct binary download (e.g. `linux-amd64/gttl`, `windows-amd64/gttl.exe`)

### Ephemeral Dashboards
- `POST /api/v1/dashboards`
  - Body: `{"title":"...","prometheus":"...","ttl":"2h","panels":[...],"template":"http-api"}`
  - Optional Header: `Authorization: Bearer <api-key>`
  - Response: `{"id":"...","url":"...","token":"...","expires_at":"..."}`
- `GET /api/v1/dashboards/{id}`
  - Returns metadata and panel definitions
- `POST /api/v1/dashboards/{id}?token=<token>` (or `POST /api/v1/dashboards/{id}/kill`)
  - Terminates session immediately and closes outbound tunnels.
- `GET /dashboards/{id}/ws?token=<token>&role=connector`
  - Outbound WebSocket reverse tunnel dialed by the CLI.
- `GET /dashboards/{id}/ws?token=<token>&role=client`
  - Inbound WebSocket stream for browser clients to receive live ECharts telemetry.

### Authentication & Saved Templates
- `POST /api/v1/auth/signup` -> `{"email":"...","password":"..."}`
- `POST /api/v1/auth/login` -> `{"email":"...","password":"..."}`
- `POST /api/v1/auth/keys` -> Generates new CLI API key
- `GET /api/v1/users/me/dashboards` -> List saved custom Grafana dashboard templates
- `POST /api/v1/users/me/dashboards/import` -> Import and parse Grafana JSON