Lidsky řečeno
Letadlo má černou skříňku. Za normálního letu ji nikdo nečte, ale když se něco stane, je jediným svědkem. Logy jsou černá skříňka programu. Na serveru u něj nesedíš, nemůžeš ho krokovat a chyba nastala v noci. Zbývá to, co si program stihl poznamenat.
Proč nestačí print
print je fajn na výstup pro člověka u terminálu. Pro záznam o běhu programu mu chybí skoro všechno: nepoznáš, kdy se zpráva vypsala, odkud pochází ani jak je závažná. A když chceš ladicí výpisy vypnout, musíš je z kódu mazat.
Modul logging to řeší. Každá zpráva má úroveň závažnosti a v nastavení určíš, od které úrovně se má něco zapisovat.
import logging
import sys
logging.basicConfig(
level=logging.INFO,
format="%(levelname)-8s %(name)s: %(message)s",
stream=sys.stdout,
force=True,
)
log = logging.getLogger("kavarna")
log.debug("obsah košíku: %s", ["káva"])
log.info("objednávka %d přijata", 1042)
log.warning("zbývají poslední %d kusy", 3)
log.error("platba %d odmítnuta", 1042)
log.critical("databáze není dostupná")
INFO kavarna: objednávka 1042 přijata WARNING kavarna: zbývají poslední 3 kusy ERROR kavarna: platba 1042 odmítnuta CRITICAL kavarna: databáze není dostupná
Zpráva debug se nevypsala, protože nastavená hranice je INFO. Stačí změnit jedno slovo v nastavení a ladicí výpisy se vrátí, bez zásahu do zbytku kódu.
| Úroveň | Číslo | Kdy ji použít |
|---|---|---|
DEBUG | 10 | podrobnosti pro ladění, v produkci obvykle vypnuté |
INFO | 20 | běžné události: spuštění, dokončená objednávka |
WARNING | 30 | něco je špatně, ale program si poradil |
ERROR | 40 | operace selhala, někdo by se na to měl podívat |
CRITICAL | 50 | aplikace nemůže dál fungovat |
V ukázkách je stream=sys.stdout, abys výpis viděl pod kódem. Bez něj jdou logy do sys.stderr, což je pro běžné programy správně: výstup programu a diagnostika se nepomíchají. Parametr force=True zahodí předchozí nastavení. basicConfig by jinak při opakovaném volání neudělal nic.
Správná úroveň pro každou platbu
Doplň funkci zpracuj(platby). Každá platba je slovník s klíči id a castka. Kladná částka se zapíše přes log.info, nulová přes log.warning, záporná přes log.error. Každá zpráva musí obsahovat id a musí ho předat jako argument: log.info("platba %s", id). Funkce vrátí počet plateb s kladnou částkou.
import logging
log = logging.getLogger("platby")
def zpracuj(platby):
pass
Logger, handler, formátovač
logging má čtyři součástky. Vyplatí se je znát, protože jinak nastavení působí jako magie.
log.info("...")
│
▼
Logger kdo píše: "kavarna.platby", má úroveň a filtry
│ vznikne LogRecord
▼
Handler kam to jde: terminál, soubor, síť; má vlastní úroveň
│
▼
Formatter jak to vypadá: text nebo JSONJména loggerů tvoří strom podle teček. Logger kavarna.platby je potomkem kavarna a všichni jsou potomky kořenového loggeru. Záznam po vytvoření stoupá stromem nahoru a použijí se handlery předků. Obvykle tak stačí jeden handler na kořeni.
V každém souboru se proto píše stejný řádek:
import logging
log = logging.getLogger(__name__) # např. "kavarna.platby"Větší nastavení se zapisuje jako slovník přes dictConfig, jednou při startu aplikace. Hlučnou knihovnu tak ztlumíš a svůj modul rozmluvíš.
import logging
import logging.config
logging.config.dictConfig({
"version": 1,
"disable_existing_loggers": False,
"formatters": {
"kratky": {"format": "%(levelname)-7s %(name)-15s %(message)s"},
},
"handlers": {
"konzole": {
"class": "logging.StreamHandler",
"stream": "ext://sys.stdout",
"formatter": "kratky",
},
},
"root": {"level": "WARNING", "handlers": ["konzole"]},
"loggers": {
"kavarna": {"level": "INFO"},
"kavarna.platby": {"level": "DEBUG"},
},
})
logging.getLogger("kavarna.sklad").debug("sklad: tohle se nevypíše")
logging.getLogger("kavarna.sklad").info("sklad: naskladněno")
logging.getLogger("kavarna.platby").debug("platby: ladicí detail")
logging.getLogger("cizi.knihovna").info("knihovna: zbytečný šum")
logging.getLogger("cizi.knihovna").warning("knihovna: tohle za pozornost stojí")
INFO kavarna.sklad sklad: naskladněno DEBUG kavarna.platby platby: ladicí detail WARNING cizi.knihovna knihovna: tohle za pozornost stojí
Logger kavarna.sklad nemá vlastní úroveň, takže ji zdědí od nejbližšího předka, tedy INFO. Cizí knihovna spadá pod kořen s úrovní WARNING.
Logger app.db má úroveň DEBUG, jeho předek app má ERROR a handler je jen na kořeni s úrovní NOTSET. Co se stane s getLogger("app.db").debug("x")?
Úroveň loggeru se kontroluje jen tam, kde zpráva vznikla. Při průchodu nahoru rozhodují už jen úrovně handlerů. Tohle překvapí i zkušené lidi.
Co do zprávy patří a co ne
Dobrý záznam odpoví na otázky: co se stalo, u čeho, s jakým výsledkem. „Chyba!“ neřekne nic, zato platba 1042 odmítnuta: nedostatek prostředků ano.
Argumenty předávej zvlášť přes %s, ne přes f-string. Text se pak skládá, až když se zpráva opravdu zapisuje.
import logging
import sys
logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stdout, force=True)
log = logging.getLogger("lenost")
class Drahy:
prevodu = 0
def __str__(self):
Drahy.prevodu += 1
return "velký objekt"
objekt = Drahy()
log.debug(f"f-string: {objekt}")
print("po f-stringu:", Drahy.prevodu)
log.debug("argument: %s", objekt)
print("po %s:", Drahy.prevodu)
log.info("zapsaná zpráva: %s", objekt)
print("po zapsané zprávě:", Drahy.prevodu)
po f-stringu: 1 po %s: 1 zapsaná zpráva: velký objekt po zapsané zprávě: 2
F-string složil text, přestože se zpráva zahodila. Se %s proběhl převod až u zprávy, která se opravdu zapsala.
Výjimky zapisuj přes log.exception uvnitř bloku except. Přidá úroveň ERROR a celý výpis zásobníku. Bez něj se v noci dozvíš jen to, že „něco selhalo“.
import logging
import sys
class KratkyFormat(logging.Formatter):
# Jen pro ukázku: cesty ve výpisu se liší počítač od počítače.
def formatException(self, exc_info):
return f" [traceback] {exc_info[0].__name__}: {exc_info[1]}"
obsluha = logging.StreamHandler(sys.stdout)
obsluha.setFormatter(KratkyFormat("%(levelname)s %(message)s"))
logging.basicConfig(level=logging.INFO, handlers=[obsluha], force=True)
log = logging.getLogger("platby.vyjimky")
def zauctuj(castka, kusu):
try:
return castka / kusu
except ZeroDivisionError:
log.exception("zaúčtování selhalo, castka=%s kusu=%s", castka, kusu)
return None
print(zauctuj(100, 4))
print(zauctuj(100, 0))
25.0 ERROR zaúčtování selhalo, castka=100 kusu=0 [traceback] ZeroDivisionError: division by zero None
Ve skutečnosti se místo řádku [traceback] vypíše celý zásobník s čísly řádků.
Začerni hesla
Napiš filtr SkryjHesla, potomka logging.Filter. Jeho metoda filter(self, record) vezme hotovou zprávu z record.getMessage(), nahradí v ní každý výskyt heslo=něco za heslo=*** (hodnota končí první mezerou nebo koncem textu), výsledek uloží do record.msg, nastaví record.args = None a vrátí True.
import logging
import re
class SkryjHesla(logging.Filter):
def filter(self, record):
return True
Pod kapotou · výkon, chyby a past jménem disable_existing_loggers
Logger.isEnabledFor se cachuje, takže vypnutý log.debug stojí málo. Argumenty se ale vyhodnotí vždy. Drahý výpočet proto obal do if log.isEnabledFor(logging.DEBUG):. Šablona "platba %s" má ještě jednu výhodu: nástroje jako Sentry podle record.msg seskupují stejné události, zatímco f-string z každé udělá unikát. Ruff to hlídá pravidlem G004.
Chyba ve formátování aplikaci neshodí. log.info("%d", "text") vypíše do stderr --- Logging error --- a program běží dál (řídí to logging.raiseExceptions).
dictConfig má výchozí disable_existing_loggers=True. Vypne všechny loggery, které už existují a v konfiguraci nejsou. Moduly s log = getLogger(__name__) naimportované před konfigurací tak potichu oněmí.
import logging
import logging.config
log = logging.getLogger("modul.nacteny.driv")
def nastav(vypnout):
logging.config.dictConfig({
"version": 1,
"disable_existing_loggers": vypnout,
"formatters": {"f": {"format": " zapsáno: %(message)s"}},
"handlers": {"h": {
"class": "logging.StreamHandler",
"stream": "ext://sys.stdout",
"formatter": "f",
}},
"root": {"level": "INFO", "handlers": ["h"]},
})
print("výchozí chování (True):")
nastav(True)
log.info("slyšíš mě?")
print("disabled =", log.disabled)
print("s False:")
log.disabled = False
nastav(False)
log.info("slyšíš mě?")
# Úklid, ať vypnutí neovlivní další ukázky.
for jiny in logging.root.manager.loggerDict.values():
if isinstance(jiny, logging.Logger):
jiny.disabled = False
výchozí chování (True): disabled = True s False: zapsáno: slyšíš mě?
Zápis do pomalého cíle blokuje vlákno, které loguje, a v asyncio celou smyčku událostí. Od verze 3.12 jde QueueHandler s posluchačem nastavit přímo v dictConfig a najít přes logging.getHandlerByName:
import logging
import logging.config
logging.config.dictConfig({
"version": 1,
"disable_existing_loggers": False,
"formatters": {"f": {"format": "%(threadName)s vytvořil: %(message)s"}},
"handlers": {
"konzole": {"class": "logging.StreamHandler", "stream": "ext://sys.stdout", "formatter": "f"},
"fronta": {"class": "logging.handlers.QueueHandler", "handlers": ["konzole"], "respect_handler_level": True},
},
"root": {"level": "INFO", "handlers": ["fronta"]},
})
posluchac = logging.getHandlerByName("fronta").listener
posluchac.start()
logging.getLogger("rychle").info("zápis jen vloží záznam do fronty")
posluchac.stop() # dopíše frontu; v aplikaci přes atexitQueueHandler.prepare záznam před vložením zformátuje a smaže args i exc_info, traceback tedy dorazí jen jako text ve zprávě. Vlastní JSON formátovač za frontou s ním proto nepracuje jako s objektem. RotatingFileHandler není bezpečný pro více procesů. V kontejnerech piš na stdout a rotaci i sběr nech platformě.
Strukturované logy a kontext
Text se dobře čte člověku, ale špatně stroji. Z věty platba 1042 odmítnuta se součet podle důvodu zjišťuje regulárním výrazem. Strukturovaný log zapisuje každou událost jako JSON na jeden řádek, s pojmenovanými poli. Nástroje jako Loki, Elasticsearch nebo CloudWatch pak umí filtrovat duvod = "limit".
Další pole přidáš parametrem extra. Skončí jako atributy záznamu a formátovač je přečte.
import json
import logging
import sys
from datetime import UTC, datetime
STANDARDNI = set(vars(logging.makeLogRecord({}))) | {"message", "asctime"}
class JsonFormat(logging.Formatter):
def format(self, record):
data = {
"cas": datetime.fromtimestamp(record.created, UTC).isoformat(timespec="seconds"),
"uroven": record.levelname,
"logger": record.name,
"zprava": record.getMessage(),
}
data |= {k: v for k, v in vars(record).items() if k not in STANDARDNI}
if record.exc_info:
data["vyjimka"] = record.exc_info[0].__name__
return json.dumps(data, ensure_ascii=False, default=str)
def pevny_cas(record):
record.created = 1_763_460_000 # jen aby ukázka vypsala pokaždé totéž
return True
obsluha = logging.StreamHandler(sys.stdout)
obsluha.setFormatter(JsonFormat())
obsluha.addFilter(pevny_cas)
logging.basicConfig(level=logging.INFO, handlers=[obsluha], force=True)
log = logging.getLogger("platby.json")
log.info("platba přijata", extra={"objednavka": 1042, "castka": 129.5})
try:
1 / 0
except ZeroDivisionError:
log.exception("výpočet selhal", extra={"objednavka": 1043})
{"cas": "2025-11-18T10:00:00+00:00", "uroven": "INFO", "logger": "platby.json", "zprava": "platba přijata", "objednavka": 1042, "castka": 129.5}
{"cas": "2025-11-18T10:00:00+00:00", "uroven": "ERROR", "logger": "platby.json", "zprava": "výpočet selhal", "objednavka": 1043, "vyjimka": "ZeroDivisionError"}Webová aplikace vyřizuje stovky požadavků najednou a jejich řádky se v logu prolínají. Pomůže ID požadavku: každý požadavek dostane značku a ta se přidá ke všem jeho záznamům. Předávat ji parametrem přes všechny funkce by bylo otravné. Modul contextvars nabízí proměnnou, která drží hodnotu pro právě běžící úlohu. Filtr ji pak do každého záznamu doplní sám.
import contextvars
import logging
import sys
from contextlib import contextmanager
id_pozadavku = contextvars.ContextVar("id_pozadavku", default="-")
class PridejKontext(logging.Filter):
def filter(self, record):
record.pozadavek = id_pozadavku.get()
return True
@contextmanager
def pozadavek(hodnota):
znacka = id_pozadavku.set(hodnota)
try:
yield
finally:
id_pozadavku.reset(znacka)
obsluha = logging.StreamHandler(sys.stdout)
obsluha.setFormatter(logging.Formatter("[%(pozadavek)s] %(message)s"))
obsluha.addFilter(PridejKontext())
logging.basicConfig(level=logging.INFO, handlers=[obsluha], force=True)
log = logging.getLogger("web.kontext")
def nacti_kosik():
log.info("načítám košík") # funkce o žádném ID neví
log.info("server běží")
with pozadavek("a1f3"):
log.info("začátek požadavku")
nacti_kosik()
with pozadavek("b7c9"):
nacti_kosik()
log.info("hotovo")
[-] server běží [a1f3] začátek požadavku [a1f3] načítám košík [b7c9] načítám košík [-] hotovo
Filtr je na handleru záměrně. Filtr na loggeru by se u záznamů z dceřiných loggerů nespustil.
Vlastní JSON formátovač
Napiš třídu JsonFormat, potomka logging.Formatter. Metoda format(self, record) vrátí JSON řetězec s klíči level (název úrovně), logger (jméno loggeru) a msg (hotová zpráva s dosazenými argumenty). Když má záznam atribut user, přidej i klíč user. České znaky nech čitelné.
import json
import logging
class JsonFormat(logging.Formatter):
def format(self, record):
return record.getMessage()
Pod kapotou · kontext přežije i asyncio
Vlákno-lokální proměnná v asyncio selže, protože všechny úlohy sdílejí jedno vlákno. ContextVar funguje, protože každý Task dostane kopii kontextu. Výpis se prolíná, ID přesto sedí. Od 3.12 má LogRecord i atribut taskName.
import asyncio
import contextvars
import logging
import sys
id_pozadavku = contextvars.ContextVar("id_pozadavku", default="-")
class PridejKontext(logging.Filter):
def filter(self, record):
record.pozadavek = id_pozadavku.get()
return True
obsluha = logging.StreamHandler(sys.stdout)
obsluha.setFormatter(logging.Formatter("%(taskName)s [%(pozadavek)s] %(message)s"))
obsluha.addFilter(PridejKontext())
logging.basicConfig(level=logging.INFO, handlers=[obsluha], force=True)
log = logging.getLogger("web.async")
async def obsluz(hodnota):
id_pozadavku.set(hodnota)
for krok in ("začátek", "konec"):
log.info(krok)
await asyncio.sleep(0)
async def hlavni():
async with asyncio.TaskGroup() as skupina:
skupina.create_task(obsluz("a1"), name="uloha-1")
skupina.create_task(obsluz("b2"), name="uloha-2")
asyncio.run(hlavni())
uloha-1 [a1] začátek uloha-2 [b2] začátek uloha-1 [a1] konec uloha-2 [b2] konec
Pozor na run_in_executor, ten kontext nepředává (asyncio.to_thread ano). Při ručním spouštění vláken použij contextvars.copy_context().run(...).
JSON logy jsou zároveň obranou proti log injection. Vstup s koncem řádku v textovém logu podvrhne celý falešný záznam, json.dumps ho escapuje. Pozor na kolize polí: extra={"name": ...} vyvolá KeyError, protože přepisuje atribut LogRecord. Totéž platí pro message a asctime.
Pozorovatelnost: logy, metriky, trasy
Pozorovatelnost znamená, že z vnějších signálů poznáš, co se děje uvnitř běžícího systému, i když jde o problém, který nikdo nečekal. Obvykle se opírá o tři druhy dat:
| Signál | Odpovídá na | Příklad |
|---|---|---|
| Logy | co přesně se stalo | platba 1042 odmítnuta, důvod limit |
| Metriky | kolik, jak rychle, jaký je trend | 12 chyb za minutu |
| Trasy | kde se v řetězci ztratil čas | 480 ms z 500 v databázi |
Metrika je číslo sledované v čase. Pro webovou službu začni třemi, zkratka RED: Rate (počet požadavků), Errors (podíl chyb), Duration (doba odezvy).
U doby odezvy nestačí průměr. Pár velmi pomalých požadavků se v něm schová, nebo naopak všechno zkreslí. Používají se percentily: p95 říká, že 95 % požadavků bylo rychlejších.
import statistics
# 90 rychlých požadavků a 10 pomalých, v milisekundách
doby = [40] * 90 + [2000] * 10
prumer = statistics.mean(doby)
percentily = statistics.quantiles(doby, n=100, method="inclusive")
print("průměr:", prumer)
print("medián (p50):", percentily[49])
print("p95:", percentily[94])
print("p99:", percentily[98])
průměr: 236 medián (p50): 40.0 p95: 2000.0 p99: 2000.0
Průměr ukazuje hodnotu, kterou nezažil vůbec nikdo. Medián tvrdí, že je vše v pořádku. Teprve p95 prozradí, že část lidí čeká dvě sekundy. V těchto datech je to každý desátý.
Trasa (trace) sleduje jeden požadavek napříč funkcemi a službami. Skládá se z úseků (spans), které mají začátek, konec a rodiče. Malý vlastní model ukáže princip. Hodiny jsou falešné, aby výsledek vyšel pokaždé stejně.
import contextvars
import itertools
from contextlib import contextmanager
hodiny = itertools.count(0, 10) # každé čtení posune čas o 10 ms
pocitadlo = itertools.count(1)
aktualni = contextvars.ContextVar("usek", default=None)
hotove = []
@contextmanager
def usek(nazev):
rodic = aktualni.get()
zaznam = {
"id": next(pocitadlo),
"nazev": nazev,
"rodic": rodic["id"] if rodic else None,
"hloubka": rodic["hloubka"] + 1 if rodic else 0,
}
znacka = aktualni.set(zaznam)
zacatek = next(hodiny)
try:
yield
finally:
zaznam["ms"] = next(hodiny) - zacatek
aktualni.reset(znacka)
hotove.append(zaznam)
with usek("POST /objednavka"):
with usek("kontrola skladu"):
pass
with usek("platba"):
with usek("volání brány"):
pass
for z in sorted(hotove, key=lambda z: z["id"]):
print(f"{' ' * z['hloubka']}{z['nazev']}: {z['ms']} ms (rodič {z['rodic']})")
POST /objednavka: 70 ms (rodič None)
kontrola skladu: 10 ms (rodič 1)
platba: 30 ms (rodič 1)
volání brány: 10 ms (rodič 3)V praxi to nepíšeš sám. Standardem je OpenTelemetry, které umí sbírat trasy, metriky i logy a posílat je do různých systémů. Metriky se často vystavují pro Prometheus a zobrazují v Grafaně.
from opentelemetry import trace
from prometheus_client import Counter, Histogram
tracer = trace.get_tracer("kavarna")
POZADAVKY = Counter("http_requests_total", "Počet požadavků", ["method", "status"])
DOBA = Histogram("http_request_duration_seconds", "Doba odezvy", ["method"])
def zaplat(objednavka_id):
with tracer.start_as_current_span("zaplat") as span, DOBA.labels("POST").time():
span.set_attribute("objednavka.id", objednavka_id)
...
POZADAVKY.labels("POST", "200").inc()Průměrná odezva je 90 ms, ale zákazníci si stěžují na pomalý web. Co pomůže nejvíc?
Průměr pomalý zlomek požadavků zakryje. Percentil ukáže, jak velký problém je, a trasa, kde vzniká.
Pod kapotou · jak to neutopit v datech a účtech
- Kardinalita je počet různých kombinací štítků a metriky na ní umírají.
user_idnebo celá URL ve štítku vytvoří miliony časových řad. Použij šablonu trasy/objednavka/{id}a identifikátory nech v logech a trasách. - Histogram se nedá zprůměrovat z percentilů. p95 z několika serverů nezískáš jejich průměrem. Sbírej koše a percentil počítej až při dotazu. Hranice košů nastav kolem svého cíle.
- Propojení signálů dává největší užitek. Přidej
trace_iddo každého logu, W3C hlavičkatraceparentho přenese mezi službami a z grafu se dostaneš na konkrétní požadavek. - Vzorkování šetří peníze, ale náhodné vzorkování na začátku zahodí i vzácné chyby. Vzorkování až po dokončení (tail-based) si nechá chyby a pomalé trasy, za cenu dočasného držení dat.
- Široké události jsou užitečná alternativa ke stovkám drobných řádků: jeden záznam na požadavek se všemi poli, tedy uživatelský segment, verze, doby jednotlivých kroků.
- Alertuj na příznaky, ne na příčiny. Vzbudit má člověka porušení cíle (SLO) z pohledu uživatele, ne chvilkové vytížení CPU. Metoda burn rate sleduje, jak rychle se spotřebovává povolená míra chyb.
logging.captureWarnings(True)přesměrujewarningsdo loggerupy.warnings, takže v produkci neuniknouDeprecationWarning.