# central_logging — drop-in klient pro centrální logování

**Verze:** 1.0 · **Datum:** 2026-06-08
**Soubory:** `central_logging.py` (import shim) + `central_logging_v1.0.py` (impl)

Knihovna, která ke stávajícímu souborovému logování přidá odesílání logů do
Loki přes bránu `log_gateway`. Jen standardní knihovna — žádné `pip install`.

## Rychlý start

```python
from central_logging import setup_logging
log = setup_logging("nazev_skriptu")
log.info("start")
log.error("chyba: %s", err)
```

## `setup_logging(...)` — parametry

| Argument    | Default                | Popis                                       |
|-------------|------------------------|---------------------------------------------|
| `app_name`  | (povinný)              | label aplikace v Loki                        |
| `log_file`  | `<app_name>.log`       | cesta souborového logu                       |
| `keep_file` | ENV / `True`           | psát i do souboru? po měsíci → `False`       |
| `level`     | ENV / `INFO`           | min. úroveň                                  |
| `gateway`   | ENV / `192.168.1.76:8770` | URL brány                                |
| `token`     | ENV                    | sdílené tajemství                            |
| `env`       | ENV / `prod`           | label prostředí                              |

## Jak to funguje

1. `emit()` jen vloží záznam do fronty (neblokuje skript).
2. Vlákno na pozadí každé ~2 s pošle dávku (max 200 záznamů) na
   `POST /log/batch`.
3. **Výpadek brány** → dávka se zapíše do `_log_spool/central_logging_spool_<app>.ndjson`
   a přehraje se při příštím úspěšném spojení. Žádný log se neztratí.
4. `atexit` při ukončení skriptu dolije zbytek fronty.

Handler je psaný tak, aby **nikdy neshodil aplikaci** — všechny chyby logování
se polykají.

## Import a konvence verzí

Konvence projektu = verze ve jméně (`central_logging_v1.0.py`). Python ale neumí
import názvu s tečkou, proto je tu shim `central_logging.py`, který verzovaný
soubor načte přes `importlib` a re-exportuje `setup_logging`. Při vydání v1.1
stačí v shimu přepnout `VERSION_FILE` a starou verzi přesunout do `TRASH/`.

## Vypnutí souborů (fáze C migrace)

Globálně:
```bash
set CENTRAL_LOG_KEEP_FILE=0      # Windows
export CENTRAL_LOG_KEEP_FILE=0   # Linux
```
nebo v kódu `setup_logging(..., keep_file=False)`.