0 dní v řadě · 0 bodů

Profesionální vývoj · 30 min

Logování a pozorovatelnost

Nastavíš logging, který pomůže ve tři ráno: úrovně, handlery, JSON logy, ID požadavku, metriky a trasování.

Hloubka
Úkoly
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á")
Výstup
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ňČísloKdy ji použít
DEBUG10podrobnosti pro ladění, v produkci obvykle vypnuté
INFO20běžné události: spuštění, dokončená objednávka
WARNING30něco je špatně, ale program si poradil
ERROR40operace selhala, někdo by se na to měl podívat
CRITICAL50aplikace 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.

Úkol

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
Výstup

Logger, handler, formátovač

logging má čtyři součástky. Vyplatí se je znát, protože jinak nastavení působí jako magie.

text
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 JSON

Jmé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:

python
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í")
Výstup
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.

Kvíz

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")?

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)
Výstup
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))
Výstup
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ů.

Úkol

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
Výstup
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ýstup
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:

python
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 atexit

QueueHandler.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})
Výstup
{"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")
Výstup
[-] 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.

Úkol

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()
Výstup
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())
Výstup
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álOdpovídá naPříklad
Logyco přesně se staloplatba 1042 odmítnuta, důvod limit
Metrikykolik, jak rychle, jaký je trend12 chyb za minutu
Trasykde se v řetězci ztratil čas480 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])
Výstup
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']})")
Výstup
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ě.

python
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()
Kvíz

Průměrná odezva je 90 ms, ale zákazníci si stěžují na pomalý web. Co pomůže nejvíc?

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_id nebo 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_id do každého logu, W3C hlavička traceparent ho 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ěruje warnings do loggeru py.warnings, takže v produkci neuniknou DeprecationWarning.