# log_gateway — FastAPI brána pro centrální logování

**Verze:** 1.0 · **Datum:** 2026-06-08 · **Soubor:** `log_gateway_v1.0.py`

FastAPI služba, která přijímá logy od klientských skriptů a přeposílá je do
Grafana Loki přes jeho HTTP push API.

## Endpoints

| Metoda | Cesta         | Popis                                            |
|--------|---------------|--------------------------------------------------|
| GET    | `/health`     | liveness + dostupnost Loki (`/ready`)            |
| POST   | `/log/batch`  | dávka záznamů (klient používá toto)              |
| POST   | `/log`        | jeden záznam (query: `app_name`, `host`, `env`)  |

Autorizace: hlavička `Authorization: Bearer <LOG_TOKEN>`.

## Payload `/log/batch`

```json
{
  "app": "parse_emails_graph",
  "host": "PC-VB",
  "env": "prod",
  "records": [
    {"ts": 1780921433.81, "level": "ERROR", "msg": "bulk_write: ...",
     "logger": "root", "func": "save_batch", "line": 542, "exc": "Traceback ..."}
  ]
}
```

Brána seskupí záznamy podle `(app, host, level, env)` do Loki streamů, převede
`ts` na nanosekundy, tělo řádku uloží jako JSON (kvůli `| json` v Grafaně) a
pošle na `POST {LOKI_URL}/loki/api/v1/push`.

## ENV

| ENV          | Default                | Popis                              |
|--------------|------------------------|------------------------------------|
| `LOKI_URL`   | `http://loki:3100`     | adresa Loki (uvnitř docker sítě)   |
| `LOG_TOKEN`  | `change-this-...`      | sdílené tajemství (= klientův token)|
| `GATEWAY_ENV`| `prod`                 | výchozí label env, když klient neuvede|

## Lokální běh (mimo docker)

```bash
pip install -r requirements.txt
LOKI_URL=http://192.168.1.76:3100 LOG_TOKEN=tajne \
    uvicorn log_gateway_v1.0:app --host 0.0.0.0 --port 8770
```

## Návrhové poznámky

- Labely držíme nízkokardinální (`ALLOWED_LABELS`). Nikdy nedávat do labelů
  např. ID zprávy / pacienta — explodovala by kardinalita sérií v Loki.
- Při chybě Loki vrací brána 502; klient si záznam uloží do spoolu a zkusí
  znovu → data se neztratí.
