# gttl — Comprehensive Specification & Agent Reference

> Ephemeral Grafana on Demand | Zero Cloud Sprawl, Zero Inbound Firewall Exposure.

Website: https://gttlsh.brimble.app
Repository: https://github.com/sodiqscript111/gttl
Short LLM Summary: https://gttlsh.brimble.app/llms.txt

---

## 1. Overview & Problem Solved

Traditional observability setups with Grafana and Prometheus require:
1. Provisioning persistent instances or cloud accounts (sprawl & cost).
2. Modifying firewall rules or opening inbound ports (security vulnerability).
3. Maintaining dashboards that are abandoned after incidents or triage sessions.

gttl solves this by:
- Creating disposable, auto-expiring dashboards on demand.
- Dialing an outbound encrypted WebSocket reverse tunnel from your machine/server to a central router. Your private Prometheus server never needs a public IP.
- Streaming real-time telemetry over WebSockets directly to the user's browser.
- Cleaning up all in-memory streams and evicting state upon TTL expiration or Ctrl+C.

---

## 2. Installation One-Liners

### Linux & macOS
```bash
curl -fsSL https://gttlsh.brimble.app/install.sh | sh
```
Installs the pre-built `gttl` executable to `/usr/local/bin` (or `~/.local/bin`).

### Windows (PowerShell)
```powershell
irm https://gttlsh.brimble.app/install.ps1 | iex
```
Installs `gttl.exe` to `$HOME\.gttl\bin` and appends to User PATH.

### Docker
```bash
docker run --rm -it -p 8080:8080 sodiqscript/gttl:latest
```

---

## 3. Architecture & Data Flow

```text
[Local Machine / Server / VPC]
+-------------------------------------------------------------+
| Private Prometheus Server                                   |
| (127.0.0.1:9090 - Inbound blocked by firewall)              |
+-------------------------------------------------------------+
                               ^
                               | Local PromQL Queries
                               v
+-------------------------------------------------------------+
| gttl CLI Agent (local process)                             |
+-------------------------------------------------------------+
                               |
                               | Outbound TLS WebSocket (Port 443)
                               | (0 open inbound firewall ports)
                               v
[Central Edge Router (gttl server: https://gttlsh.brimble.app)]
+-------------------------------------------------------------+
| Hub Manager & In-Memory Session Store                       |
| - Verifies 6-character slug + token                         |
| - Relays queries & binary/JSON frames                        |
| - Background reaper evicts expired sessions (TTL)           |
+-------------------------------------------------------------+
                               ^
                               | Real-time WebSocket Stream
                               v
[Browser Client]
+-------------------------------------------------------------+
| Web Console (React / Svelte + ECharts)                     |
| - Live streaming charts, volume guardrails, countdown timer|
+-------------------------------------------------------------+
```

---

## 4. PromQL Templates & Panel Types

### Supported Panel Types
- `timeseries`: Continuous metric waveform graph (renders line/area charts with ECharts / SVG).
- `stat`: Single scalar value display with secondary volume checks.
- `gauge`: Circular arc percentage meter (e.g. CPU saturation, memory utilization).
- `table`: Tabular label/value breakdown (e.g. HTTP status codes, top consumers).

### Template: `http-api`
- Request Rate (RPS): `sum(rate(http_requests_total[1m]))` (type: timeseries)
- P95 Latency: `histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))` (type: timeseries)
- Error Rate: `sum(rate(http_errors_total[1m])) / sum(rate(http_requests_total[1m])) * 100` (type: stat)
  - Companion Volume Query: `sum(rate(http_requests_total[1m]))` (threshold: 10 samples)
- Status Codes Breakdown: `sum(rate(http_requests_total[5m])) by (status)` (type: table)

### Template: `system` (Node Exporter)
- CPU Usage: `100 - (avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[1m])) * 100)`
- Memory Usage: `(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100`
- Disk I/O: `rate(node_disk_read_bytes_total[1m]) + rate(node_disk_written_bytes_total[1m])`
- Network Bandwidth: `sum(rate(node_network_receive_bytes_total[1m]))`

---

## 5. API Reference (JSON Schemas)

### Create Dashboard
`POST /api/v1/dashboards`

Request Body:
```json
{
  "title": "Incident Triage - Service Auth",
  "prometheus": "http://localhost:9090",
  "ttl": "2h",
  "template": "http-api",
  "panels": [
    {
      "id": "p1",
      "title": "Requests per Second",
      "type": "timeseries",
      "query": "sum(rate(http_requests_total[1m]))",
      "unit": "req/s",
      "width": 8,
      "height": 4
    }
  ]
}
```

Response Body (HTTP 201):
```json
{
  "id": "8zwzzu",
  "url": "https://gttlsh.brimble.app/d/8zwzzu?token=e4c83fa901b",
  "token": "e4c83fa901b",
  "expires_at": "2026-09-24T04:22:00Z"
}
```

### Kill Dashboard
`POST /api/v1/dashboards/{id}?token={token}`
Or `POST /api/v1/dashboards/{id}/kill` with `Authorization: Bearer <cli-api-key>`

Response Body (HTTP 200):
```json
{
  "status": "killed",
  "message": "Dashboard 8zwzzu has been expired"
}
```