blog.diba.dev

Hello World

2026-02-21T00:00:00+01:00

Vítejte na blogu! Toto je první článek, který slouží jako ukázka formátování.

Proč Flask?

Flask je minimalistický webový framework pro Python. Na rozdíl od Djanga vám nediktuje strukturu projektu — postavíte si přesně to, co potřebujete.

Ukázka kódu

Jednoduchá Flask aplikace:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello, World!"

if __name__ == "__main__":
    app.run(debug=True)

A tady je příklad práce se soubory v Pythonu:

from pathlib import Path

posts_dir = Path("posts")
for md_file in sorted(posts_dir.glob("*.md")):
    print(f"Nalezen článek: {md_file.stem}")

Seznamy

Věci, které tento blog umí:

Markdown články s YAML frontmatter
Syntax highlighting přes Pygments
Lazy cache — HTML se generuje při prvním přístupu
RSS/Atom feed
Tagy a filtrování podle nich

Kód inline

Konfiguraci najdete v souboru app.py. Články se ukládají do složky posts/ jako .md soubory.

Jak logovat informativně a nerozhazovat Sentry grouping

2026-02-22T00:00:00+01:00

Context manager, který potlačí duplicitní Sentry log-eventy a pošle jednu výjimku s plným kontextem — informativní logy v aplikaci, čistý grouping v Sentry.

Problém

Sentry Python SDK s LoggingIntegration zachytává každý logger.error() / logger.warning() jako samostatný Sentry event. To přináší dva problémy najednou.

Duplikáty. Když chybu ošetříte a zalogujete, dostanete v Sentry dva eventy: log-event + exception event (pokud voláte i capture_exception). Jeden caught error vygeneruje 2–3 Sentry eventy, každý s jiným groupingem, a kvóta se plní zbytečně rychle.

Rozbitý grouping. Sentry u log-eventů vidí jen text zprávy. Nemá výjimku, nemá stacktrace — nemá se čeho chytit. Zprávy Download failed: url=AAA a Download failed: url=BBB jsou pro Sentry dva různé problémy, i když jde o tutéž chybu se stejným stacktrace. Naivní řešení je nedávat specifické informace do log message — ale to je přesně to, co v logu chceme. Informativní zpráva Download failed: url=https://example.com/api/v2/products je v logu neocenitelná, ale pro Sentry grouping je jed.

Co context manager dělá

with sentry_suppress_logs_capture_exception(exc):
    logger.warning("Download failed: url=%s", url)

Uvnitř bloku:

logger.warning()/logger.error() jde jen do lokálního logu — Sentry log-event se zahodí (přes before_send hook)
Můžete logovat kolik chcete, žádný z logů nevytvoří Sentry event

Po ukončení bloku:

Sentry dostane přesně 1 event: capture_exception(exc) s úrovní warning
Event obsahuje plný stacktrace, exception chain, tagy a context

Jak to funguje uvnitř

Tři spolupracující komponenty:

1. Context variable

Signalizuje, že jsme uvnitř suppress bloku:

_suppress_ctx: contextvars.ContextVar[bool] = contextvars.ContextVar(
    "sentry_suppress", default=False
)

2. Log record factory hook

Označí log záznamy z potlačeného bloku:

def factory(*args, **kwargs):
    record = original_factory(*args, **kwargs)
    if record.levelno >= logging.WARNING and _suppress_ctx.get():
        record.sentry_skip = True
    return record

3. before_send hook

Zahodí označené log-eventy:

def before_send(event, hint):
    record = hint.get("log_record")
    if record is not None and getattr(record, "sentry_skip", False):
        return None
    return event

Context manager samotný

@contextmanager
def sentry_suppress_logs_capture_exception(
    exc: BaseException,
    *,
    tags: Mapping[str, str] | None = None,
    context: Mapping[str, Any] | None = None,
) -> Iterator[None]:
    token = _suppress_ctx.set(True)
    try:
        yield
    finally:
        _suppress_ctx.reset(token)

        with sentry_sdk.new_scope() as scope:
            scope.set_level("warning")

            if tags:
                for k, v in tags.items():
                    scope.set_tag(k, v)

            scope.set_extra("exc_type", type(exc).__name__)
            scope.set_extra("exc_message", str(exc))

            if context:
                scope.set_context("warn.context", dict(context))

            scope.capture_exception(exc)

Typické použití

Caught error, který nechceme propagovat, ale chceme ho vidět v Sentry:

try:
    page = await downloader.download(url=url)
except HTTPError as exc:
    with sentry_suppress_logs_capture_exception(exc):
        logger.warning("Download failed: url=%s", url)
    page = DownloadPage(url=url, content="")  # fallback

Ošetření chyby v error handleru — nechceme, aby sekundární selhání přebilo primární:

try:
    task = await repository.find(id=task_id)
except Exception as refetch_err:
    with sentry_suppress_logs_capture_exception(refetch_err):
        logger.warning("Failed to re-fetch task %s: %s", task_id, refetch_err)
    task = None

Race condition — objekt smazán jiným procesem:

except StaleDataError as exc:
    with sentry_suppress_logs_capture_exception(exc):
        logger.warning(
            "Product %s deleted before update could commit, skipping.",
            product_id,
        )

Bez vs. s context managerem

Bez	S
`logger.error()` → 1 Sentry log-event (bez stacktrace)	`logger.warning()` → jen lokální log
`capture_exception()` → 1 Sentry exception event	`capture_exception()` → 1 Sentry exception event
2 eventy v Sentry, duplikátní šum	1 event v Sentry, plný kontext

Proč contextvars a ne thread-local

Aplikace je async (asyncio). Thread-local by nefungoval — coroutiny sdílejí vlákno. contextvars.ContextVar je asyncio-aware a správně izoluje kontext per-task.

Více vypovídající titulky u Sentry eventů

2026-02-22T00:00:00+01:00

Jak proměnit titulek Sentry issue z ExceptionGroup: Download failed na DownloadError -> [HTTPDownloadError -> RuntimeError, HTTPStatusError].

Problém

Sentry zobrazuje issue tak, že titulkem je exception_type a podtitulkem exception_value. U ExceptionGroup to vede k identickým titulkům pro zcela odlišné root causes — titulek je vždy jen ExceptionGroup a podtitulek generický message:

ExceptionGroup: Download failed
ExceptionGroup: Download failed
ExceptionGroup: Download failed
ExceptionGroup: Download failed

Čtyři různé Sentry issues, každý s jiným problémem (DNS error, HTTP 403, HTTP 404, nevalidní URL), ale na první pohled nerozlišitelné. Stejný problém nastává u výjimek balených do generického obalu. To je běžný pattern — obal nese metainformaci (retry count, endpoint URL, batch ID), ale Sentry zobrazí jen typ obalu:

DownloadError: Download failed
DownloadError: Download failed
DownloadError: Download failed

Příčiny jsou přitom pokaždé jiné — ConnectionTimeout, SSLCertVerificationError, HTTPStatusError(403) — ale v seznamu issues vidíme jen generický DownloadError. Musíme rozkliknout každý event, abychom zjistili, co se skutečně stalo.

Nebo třeba:

TaskError: Task processing failed
TaskError: Task processing failed

Jeden je JSONDecodeError, druhý PermissionError — ale titulek je identický.

Jádro problému: Jak ExceptionGroup, tak výjimky s chain (__cause__/__context__) nesou skutečnou informaci ve vnořených výjimkách, ne v top-level message. Sentry tuhle strukturu neumí zobrazit v titulku.

Řešení: SDK tag + server-side fingerprint rule

Kombinace dvou mechanismů:

SDK (Python, before_send hook) — má přístup k živému exception objektu, umí rekurzivně projít ExceptionGroup.exceptions a __cause__/__context__ chainy. Výsledek zapíše jako tag.
Sentry server (fingerprint rule) — umí přepsat titulek, ale potřebuje hotová data. Tag z SDK je v eventu k dispozici.

Proč to funguje

before_send se volá před odesláním eventu na server — tag je součástí payloadu
Server-side fingerprint rules se aplikují po přijetí eventu — vidí tagy z SDK
title= v fingerprint rule je jediný dokumentovaný způsob, jak přepsat titulek issue

Proč tag a ne jiný mechanismus

Tag je standardní součást Event payloadu — žádné hackování TypedDictu
Je viditelný v Sentry UI (filtrování, vyhledávání)
Fingerprint rule tags.* matcher je dokumentovaný a podporovaný
Čistá separace: backend dodá data, server je zobrazí

Implementace

Mixin pro výjimky

class SentryTitleMixin:
    """Mixin for exceptions with informative Sentry titles."""

    @staticmethod
    def _format_sentry_title(exc: BaseException) -> str:
        name = type(exc).__name__
        if isinstance(exc, BaseExceptionGroup):
            inner = ", ".join(
                SentryTitleMixin._format_sentry_title(e) for e in exc.exceptions
            )
            return f"{name} -> [{inner}]"
        cause = exc.__cause__ or exc.__context__
        if cause:
            return f"{name} -> {SentryTitleMixin._format_sentry_title(cause)}"
        return name

    def sentry_title(self) -> str:
        """Return a human-readable title describing the exception chain."""
        assert isinstance(self, BaseException)
        return self._format_sentry_title(self)

_format_sentry_title() je @staticmethod, protože rekurzivně prochází vnořené výjimky, které samy SentryTitleMixin nemají — potřebuje přijmout libovolný BaseException, ne jen self.

Rekurzivní _format_sentry_title() sestaví hierarchický popis:

ExceptionGroup → Name -> [Sub1, Sub2]
Chained exception (__cause__/__context__) → Name -> CauseName
Kombinace → DownloadError -> [HTTPDownloadError -> RuntimeError, HTTPStatusError]

Výjimka s mixinem

class DownloadError(ExceptionGroup, SentryTitleMixin):
    """Download failed in all attempts."""

Žádný __new__, žádný derive() — mixin je opt-in a přidává se jen na výjimky, kde to dává smysl. Zasahuje pouze do Sentry zobrazení, žádné změny v chování výjimek.

`before_send` hook

def before_send(event, hint):
    # ... existing filters ...

    # SentryTitleMixin — set tag for server-side fingerprint rules.
    #   Requires a fingerprint rule in Sentry (Project Settings → Issue Grouping):
    #   tags.sentry_title:* -> {{ default }} title="{{ tags.sentry_title }}"
    exc_info = hint.get("exc_info") if hint else None
    if exc_info and len(exc_info) >= 2:
        exc = exc_info[1]
        if isinstance(exc, SentryTitleMixin):
            event.setdefault("tags", {})["sentry_title"] = exc.sentry_title()

    return event

Fingerprint rule v Sentry UI

Project Settings → Issue Grouping → Fingerprint Rules:

tags.sentry_title:* -> {{ default }} title="{{ tags.sentry_title }}"

{{ default }} zachovává výchozí grouping — pravidlo mění pouze zobrazený titulek.

Výsledek

Místo:

ExceptionGroup: Download failed

Sentry zobrazí:

DownloadError -> [HTTPDownloadError -> RuntimeError, HTTPStatusError]

Obecnější pozorování

Sentry SDK a server mají asymetrické schopnosti: SDK vidí runtime objekty, server vidí jen serializovaný payload. Ale titulek umí přepsat jen server (přes fingerprint rules).
ExceptionGroup (Python 3.11+) je v Sentry stále občan druhé kategorie — titulek zobrazuje jen top-level message, ne strukturu sub-výjimek.
Fingerprint rules jsou primárně navržené pro grouping, ale title= atribut z nich dělá jediný způsob, jak ovlivnit zobrazení issue v seznamu.
Pattern "SDK připraví data jako tag, server je spotřebuje v pravidle" je obecně použitelný i pro jiné scénáře, kde potřebujete runtime informaci v server-side konfiguraci.

Běžné projekty netrpí nedostatkem testů, ale dominancí unittestů

2026-04-01T00:00:00+01:00

Běžné projekty netrpí nedostatkem testů, ale dominancí unittestů

V mnoha projektech nejsou testy problém proto, že by chyběly. Problém je, že jich je hodně právě tam, kde chrání málo.

Build padá, ale jeho pád je hlučný a málo užitečný. Build projde, ale nikdo mu úplně nevěří. Refaktor je stres, přestože „přece máme testy“. A když se člověk podívá dovnitř, zjistí, že většina té údajné ochrany jsou izolované unittesty, často dopsané až na hotový kód, často silně mockované, často motivované coverage.

Tohle není nedostatek testů. Tohle je špatně složená testovací sada.

Dogma, které zní nevinně

Spousta programátorů zná skoro jen unittesty. Když se řekne „dopiš testy“, téměř vždy se tím myslí „dopiš unittesty“. Když se řekne „kvalita“, často se tím myslí „coverage“. Když se řekne „správný test“, často se tím myslí „izolovaný test jedné třídy s mocky okolo“.

Jenže tohle není technická pravda. To je kulturní zvyk.

Unittesty jsou dominantní ne proto, že by vždy nejlépe chránily projekt. Jsou dominantní proto, že se dobře učí, dobře měří a dobře mechanicky vyrábějí. A právě proto jich bývá v projektech příliš mnoho vůči zbytku testovací sady.

Největší problém běžných projektů není absolutní počet testů. Je to jejich poměr.

Šest set unittestů a tři integrační testy není silná testovací sada. Je to známka toho, že tým testuje hlavně to, co se nejsnáze izoluje, ne to, co se nejsnáze rozbije.

Ano, unittesty mají své místo

Unit test je dobrý nástroj pro lokální pravidlo. Pro hraniční podmínku. Pro malou transformační logiku. Pro deterministický výpočet. Tam funguje dobře.

Jenže takového kódu bývá v běžném projektu překvapivě málo.

Typický backend netvoří hlavně elegantní izolovaná pravidla. Tvoří ho orchestrace, persistence, serializace, DTO, framework, glue code, side effecty a rozhraní mezi částmi systému. A právě tam vznikají chyby, které při změně bolí.

Unit testy tedy nejsou zbytečné. Jen bývají přeceněné. Jsou dobré na úzký typ problému. Spousta projektů se ale tváří, jako by ten úzký problém byl celý systém.

Mentální experiment: jaký projekt bych chtěl převzít?

Představ si, že jako nově příchozí člen týmu přebíráš cizí projekt. Máš ho měnit, opravovat a refaktorovat.

Co chceš najít?

Nechceš najít stovky testů, které mockují vlastní vrstvy aplikace a dokazují, že controller zavolal service a service zavolala repository.

Chceš najít projekt, kde červený build něco znamená.

Chceš vidět testy, které hlídají, že:

endpoint, service a repository si opravdu rozumí,
důležitý flow projde od vstupu k výsledku,
hranice mezi moduly drží kontrakt,
historické bugy se nevracejí,
nebezpečný refaktor rozbije testy tehdy, když rozbije systém, ne když jen přeskupí vnitřní volání.

A teď druhá část experimentu: jak takové projekty většinou vypadají doopravdy?

Přesně opačně.

Najdeš hodně unittestů. Často izolovaných. Často mock-heavy. Často dopsaných až po dokončení kódu. Málo integračních testů. Téměř žádné contract testy. Pár E2E scénářů, pokud vůbec. A build, kterému tým věří méně, než by odpovídalo množství testů.

To není detail. To je jádro problému.

V projektech se většinou nerozbije izolovaná funkce

Nejnebezpečnější chyba při změně často nevypadá takto:

„Napsal jsem špatný if.“

Mnohem častěji vypadá takto:

„Změnil jsem něco lokálně správně, ale okolí čekalo něco jiného.“

Změní se shape dat. Jiný název pole. Jiný význam pole. None místo výjimky. Decimal místo integeru v centech. Jiný payload eventu. Jiný invariant. Jiná serializace. Jiná interpretace stavu.

Lokálně je kód korektní. Systémově je rozbitý.

To je důležitý rozdíl. Jedna chyba vzniká při psaní nové logiky. Druhá vzniká při změně systému, když jinak korektní kód naruší tiché předpoklady okolí. A právě ta druhá bývá v praxi nebezpečnější.

Proto nestačí říct „máme unittesty“. Záleží, co vlastně chrání.

Mnoho unittestů má největší hodnotu v den svého vzniku

Tohle je nepříjemné, ale důležité přiznání.

Mnoho unit testů je opravdu užitečných ve chvíli, kdy vznikají spolu s kódem. Autor si jimi ověřuje, že právě napsané lokální pravidlo funguje. V ten moment dávají smysl. Pomáhají při tvorbě.

Jenže jejich dlouhodobá hodnota bývá přeceňovaná.

Jakmile je kód hotový a projekt dál žije hlavně změnami na rozhraních, mnoho takových testů už nepřináší reálnou ochranu proti budoucím regresím. Zůstávají v projektu spíš jako pomníček tehdejší implementace. Archiv lokální snahy. Důkaz, že jsme kdysi chtěli být pečliví.

Projekt pak nenese jejich přínos. Nese jejich údržbu.

To neznamená, že všechny unit testy jsou po týdnu zbytečné. Znamená to, že jejich dlouhodobý přínos bývá systematicky nadhodnocený a jejich údržbový náklad podceňovaný.

Co myslím mock-heavy testem

Mock-heavy test je test, který nahradí většinu vnitřních spolupracovníků aplikace mocky a pak hlavně ověřuje, kdo koho zavolal, s jakými argumenty a v jakém pořadí.

Controller mockuje service. Service mockuje repository. Repository mockuje klienta. Test nakonec skončí sérií assert_called_once_with(...).

Takový test často netestuje pozorovatelné chování systému. Testuje choreografii jeho vnitřních volání.

A právě proto bývá křehký při refaktoru a slabý při chytání skutečných regresí.

Mock-heavy testy mají často zápornou hodnotu

Tohle je potřeba říct naplno.

Mock-heavy testy často změny neulevňují, ale prodražují.

Nejen že často nechytnou důležitou regresi. Ony navíc při změně samy vytvářejí práci. Neopravuješ chybu v systému. Opravuješ testy, které byly napsané na starou strukturu volání.

Takový test často neříká: „Systém přestal fungovat.“

Říká spíš: „Implementace už nevypadá tak, jak jsem si ji kdysi představoval.“

To je jejich záporná hodnota pro projekt. Platíš jejich psaní. Platíš jejich údržbu. A přitom ti často neposkytují odpovídající ochranu tam, kde se systém opravdu láme.

Největší slabina mock-heavy testů není jen to, že občas něco nechytnou. Je to to, že při změně samy vytvářejí práci.

Nemockujte vnitřek aplikace. Mockujte její okolí.

Pokud má test opravdu chránit projekt při změně, neměl by co nejvíc odřezávat vnitřek aplikace. Měl by naopak nechat spolupracovat co nejvíc skutečných částí systému a mockovat až to, co leží za jeho hranou.

Uvnitř aplikace chceme co nejvíc reality, ne co nejvíc izolace.

Právě uvnitř aplikace totiž nejčastěji vznikají regresní chyby v návaznosti částí. Když tyto návaznosti nahradíme mocky, netestujeme systém. Testujeme představu o systému.

Dobrými kandidáty na mock nebo náhradu jsou hlavně:

externí HTTP API,
email a SMS brány,
čas, UUID, random,
message broker mimo proces,
filesystem nebo cloud storage,
platby a jiné nevratné side effecty.

To jsou místa, kde izolace opravdu pomáhá. Ne proto, že „správný unittest musí vše mockovat“, ale proto, že tyto závislosti jsou mimo naši aplikaci, jsou drahé, pomalé, nedeterministické nebo nebezpečné.

Když už izolovat, často je lepší fake než mock

Mock jen tvrdí, že se něco zavolalo. Fake se snaží chovat jako jednoduchá, ale skutečná implementace.

Mock repository ti řekne, že někdo zavolal save(order). Fake repository ti umožní opravdu objednávku uložit do in-memory kolekce a pak ověřit výsledek.

To je důležitý rozdíl.

Mock hlídá volání. Fake hlídá chování.

Právě proto bývá fake do budoucna cennější. Méně lže. Méně fixuje vnitřní call-flow. Častěji přežije refaktor. Když už tedy něco izolovat, je často lepší použít jednoduchou náhradní realitu než prázdnou atrapu.

Přestaňme řešit, co je „správný unittest“

V mnoha týmech se zbytečně řeší, jestli test spadá do správné škatulky. Jestli je to ještě unit test, nebo už integrační test. Jestli je dost izolovaný. Jestli sahá na moc vrstev.

Tohle není podstatná otázka.

Podstatná otázka zní jinak: zachytí ten test důležitou regresi za rozumnou cenu?

Test, který projde přes controller, service, mapper a repository, může být pro projekt výrazně cennější než deset čistých unittestů na jednotlivé třídy. I když tím porušuje učebnicová pravidla.

Projekt nechrání ten nejčistší test. Projekt chrání ten test, který zachytí skutečný způsob poruchy.

Coverage je metrika aktivity, ne ochrany

Coverage se dobře ukazuje v dashboardu. Dobře se porovnává. Dobře se tlačí v code review. A právě proto je nebezpečná.

Coverage neříká, že je projekt chráněný. Říká jen, že se kód nějak vykonal.

Coverage neříká:

že test hlídá správný kontrakt,
že test dává důvěryhodný fail,
že test chrání důležitou hranici systému,
že build má skutečnou vypovídací hodnotu.

Proto můžeš mít projekt s vysokou coverage a nízkou důvěrou v testy. To není paradox. To je běžná realita.

Když tým optimalizuje na coverage, začne snadno vyrábět testy, které se dobře počítají, ale málo chrání.

Lepší model: testy podle typu poruchy

Nemáme se ptát: „Kde dopíšeme unittesty?“

Máme se ptát: „Jaký typ poruchy tato změna nejspíš zavede?“

Když je riziko v lokálním pravidle, napiš unit test.

Když je riziko v návaznosti vrstev, napiš integrační test.

Když je riziko na hranici modulů nebo služeb, napiš contract test.

Když je riziko v kritickém flow, napiš E2E nebo aspoň smoke test.

Když opravuješ historický bug, přidej regresní test na místě, kde chyba skutečně vznikla.

Test se nemá vybírat podle tradice. Má se vybírat podle místa, kde se to opravdu rozbije.

Co bych chtěl po týmu a po LLM agentech

Nechci, aby automaticky dopisovali unittesty na hotový kód.

Chci, aby se nejdřív ptali:

kde je skutečné regresní riziko,
co tady mock skryje,
co má být v testu reálné,
která nejnižší vrstva ten problém opravdu odhalí,
a jestli ten test chrání systém, nebo jen aktuální implementaci.

Nechci testy, které dokazují, že controller zavolal service.

Chci testy, kterým budu věřit, když přepíšu půlku flow objednávky.

To je úplně jiná motivace. A právě tu dnes v mnoha projektech postrádáme.

Závěr

Unittesty nejsou špatné. Jejich dominance ano.

Běžné projekty netrpí nedostatkem testů. Trpí tím, že mají testy ve špatném poměru. Příliš mnoho unittestů. Příliš mnoho mocků uvnitř systému. Příliš málo testů na hranách a návaznostech, kde se systém skutečně láme.

Dokud budeme na tento typ poruchy odpovídat hlavně unittesty, budeme mít víc testů, víc coverage a méně skutečné jistoty.

Silná testovací sada nevzniká tím, že má hodně testů. Vzniká tím, že má testy na správných místech.

Když zelené testy nahradí dobrý návrh

2026-04-01T00:00:00+01:00

Když zelené testy nahradí dobrý návrh

U TDD se často říká, že vede k lepšímu návrhu. Nejdřív test, pak implementace, nakonec zelený build. Zní to disciplinovaně. Čistě. Profesionálně.

Jenže právě v tom je i jeho nechtěný efekt: TDD velmi snadno mění definici hotovo.

Místo „kód je zjevně správný, čitelný a dobře navržený“ začne hotovo znamenat „testy jsou zelené“.

A to není totéž.

TDD nevyrábí jen testy. Vyrábí i určitý způsob myšlení

Ten postup známe:

Napíšu testy. Snažím se, aby byly zelené. Když jsou zelené, mám hotovo. Když něco nesedí, upravím implementaci tak, aby to prošlo.

V normální podobě to zní nevinně. V přehnané podobě už je ale dobře vidět, kam ten tlak míří: ne k co nejzřejměji správnému kódu, ale ke kódu, který je dostatečně podepřený testy, aby se tvářil funkčně.

To není obvinění, že TDD vždy vede ke špatnému kódu. Je to upozornění, že optimalizační tlak jde jinam, než se často tvrdí.

TDD systematicky zvýhodňuje jednu otázku:

Co ještě musím upravit, aby testy prošly?

Jenže kvalitní návrh často začíná jinou otázkou:

Jak napsat kód tak, aby z něj bylo co nejvíc vidět, že je správný?

Dva mentální póly

Je užitečné si představit dva extrémy.

První pól je tento:

Hlavně ať jsou testy zelené. Kód doladím tak, aby vyhověl testovací sadě.

Druhý pól je tento:

Musím napsat tak dobrý kód, aby byl sám o sobě co nejčitelnější, nejjednodušší a co nejzřejměji správný.

V čisté podobě se v praxi skoro nevyskytuje ani jeden. Ale právě proto jsou užitečné. Vymezují prostor, ve kterém se opravdu pohybujeme.

A TDD nás často táhne směrem k prvnímu pólu.

Ne proto, že by to bylo jeho deklarovaným cílem. Ale proto, že dává velmi silný signál hotovosti: build je zelený, tedy je hotovo.

Zelené testy nejsou důkaz dobrého návrhu

Tohle je podle mě klíčový bod.

Zelené testy dokazují, že implementace uspokojila určitou testovací sadu. Nedokazují, že je návrh dobrý. Nedokazují, že je kód srozumitelný. Nedokazují, že je jednoduchý. Nedokazují, že budou budoucí změny levné.

A přesto se v praxi tyto věci velmi často směšují.

Testy prošly, takže je to správně. Testy prošly, takže je to dobře navržené. Testy prošly, takže můžeme přestat přemýšlet.

Jenže právě tady vzniká falešný pocit hotovosti.

Kód může být lokálně otestovaný a zároveň:

strukturálně nepřehledný,
plný pomocných vrstev jen kvůli testovatelnosti,
rozlámaný na rozhraní, která doménově nedávají smysl,
závislý na call-flow, které bude při příštím refaktoru překážet.

Zelené testy a dobrý návrh spolu mohou souviset. Ale jedno není důkazem druhého.

TDD zvýhodňuje to, co se dobře testuje jako první

A to je další problém.

Nejlépe se test-first stylem píše malá, izolovaná logika. Funkce. Transformace. Výpočet. Validace. Tam TDD dává smysl a je fér mu to přiznat.

Jenže běžný projekt se často nerozbíjí hlavně tam.

Rozbíjí se:

na rozhraních mezi vrstvami,
ve změně shape dat,
v implicitních očekáváních okolí,
v kontraktech mezi částmi systému,
v návaznostech, které lokální unit test nevidí.

A právě to se TDD test-first stylem chytá mnohem hůř.

TDD tedy často nevyrábí testy, které nejlépe chrání projekt. Vyrábí testy, které se nejlépe píšou před implementací.

To je zásadní rozdíl.

A potom už máme unittesty hotové?

Tohle se často uvádí jako výhoda TDD.

„Když píšeme testy předem, máme je pak automaticky hotové. Nemusíme je dopisovat.“

Jenže to je výhoda jen tehdy, pokud právě tyto testy mají dlouhodobou hodnotu.

A tady se vrací problém z předchozího článku: v běžných projektech bývá dlouhodobá hodnota mnoha unittestů systematicky přeceňovaná.

Jinými slovy: TDD nám skutečně pomáhá rychle vyrobit unittesty. Jenže pokud je právě dominance unittestů součást problému, pak to není automaticky výhoda. Je to spíš efektivnější výroba toho, čeho už máme příliš mnoho ve špatném poměru vůči zbytku testovací sady.

Získáváme tedy benefit, který v tom okamžiku už benefitem být nemusí.

Ano, máme testy hotové. Ale možná máme hotové hlavně ty testy, které projekt dlouhodobě chrání méně, než si myslíme.

TDD může deformovat i architekturu

Tohle bývá vidět méně, ale je to důležité.

Když je hlavní tlak na to, aby šel kód pohodlně testovat po malých izolovaných jednotkách, začne se architektura přizpůsobovat této potřebě.

Vznikají rozhraní, která nejsou doménově přirozená, ale dobře se mockují. Vznikají vrstvy, jejichž hlavní hodnotou je, že jdou v testu oddělit. Vznikají malé třídy a malé metody ne proto, že by to zlepšovalo model systému, ale proto, že se na ně dobře píše test-first.

Výsledkem pak může být architektura optimalizovaná na testovatelnost, ne na srozumitelnost nebo robustnost.

To je vysoká cena.

Protože systém nežijeme jen při psaní testů. Žijeme s ním při údržbě, čtení, refaktoru a změnách.

TDD je silné. Jen v užším prostoru, než se tvrdí.

Aby to bylo fér: TDD není nesmysl.

Je silné tam, kde člověk právě tvoří malou logiku a potřebuje rychlou zpětnou vazbu. Pro parser, výpočet, převod dat, hraniční podmínky nebo malé pravidlo to může být výborný nástroj.

Tam opravdu pomáhá.

Jenže z toho ještě neplyne, že je to dobrý obecný model pro návrh běžného projektu. Už vůbec z toho neplyne, že TDD automaticky produkuje lepší architekturu nebo lepší dlouhodobou ochranu systému.

TDD dobře pomáhá s lokální správností. To ale není totéž jako dobrý návrh. A už vůbec to není totéž jako ochrana proti regresím v systémových návaznostech.

Co je praktičtější přístup

Nepotřebujeme další ideologii. Potřebujeme lepší otázky.

Ne „jak to udělat test-first“. Spíš „co se tady může rozbít a jak to nejlépe odhalíme“.

Ne „už jsou testy zelené“. Spíš „je ten kód sám o sobě přesvědčivý, čitelný a zjevně správný“.

Ne „máme už unittesty hotové“. Spíš „chrání ty testy opravdu to, co bude při příští změně bolet“.

To znamená dvě věci najednou:

První: netlačit všechno do TDD rytmu jen proto, že to vypadá disciplinovaně. Druhá: neplést si průchod testy s kvalitou návrhu.

Testy jsou nástroj. Ne důkaz elegance. Ne důkaz správné architektury. Ne důkaz, že už nemusíme přemýšlet.

Závěr

TDD není problematické proto, že vede k testům. Je problematické tam, kde se průchod testy začne plést s důkazem dobrého návrhu.

Jeho nechtěný efekt je jednoduchý: mění definici hotovo. Místo zjevně správného a dobře navrženého kódu začíná stačit kód, který uspokojí testovací sadu.

A to je mnohem nižší laťka, než se tváří.

Pokud má mít software dlouhý život, nestačí, aby byl otestovaný. Musí být také čitelný, přesvědčivý a konstrukčně poctivý. Ve chvíli, kdy zelené testy začnou tyto vlastnosti nahrazovat, přestává být TDD disciplínou návrhu a stává se disciplínou uspokojování testů.

Komentář k draftu: Běžné projekty netrpí nedostatkem testů, ale dominancí unittestů

2026-06-12T00:00:00+01:00

Komentář k draftu o dominanci unittestů

Měl jsem příležitost konfrontovat draft s čerstvou zkušeností: vícedenní refaktor extrakční pipeline, při kterém se pod ~28 stagemi vyměnil celý storage engine (klíčované stores → append-only záznamy s meta adresováním), změnil se wire kontrakt API a přepsala se vnitřní choreografie tří stagí. Testovací sada ~650 testů, z toho silná vrstva e2e testů s nahranými HTTP kazetami (VCR), které porovnávají odchozí LLM requesty byte po bytu.

Hlavní zpráva: žádná teze článku se v praxi nevyvrátila. Skoro každá má z toho refaktoru konkrétní inkarnaci. Zároveň praxe dala čtyři jemnější rozlišení, která v textu chybí — a aspoň dvě z nich by myslím článek znatelně posílila.

Co refaktor potvrdil

„Změnil jsem něco lokálně správně, ale okolí čekalo něco jiného." Učebnicový exemplář: wire vstupy se překlopily z dictu na list záznamů a kód has_image = "image" in cascade_inputs.strings zůstal. Na listu je to validní Python, lokálně korektní — a tiše vždy False. Pipeline jen vynechala jednu stage, nic nespadlo. Žádná jednotka se nechovala špatně, systém ano. Chytil to přesně ten test, který článek doporučuje: e2e přes celý flow s nahranou hranicí — kazeta odmítla request, ve kterém chyběly čtyři řádky promptu. Je to mimochodem přesně položka „změní se shape dat" z tvého výčtu — kdyby článek chtěl jeden konkrétní příběh místo abstraktního výčtu, tenhle typ bugu je ideální kandidát.

„Nemockujte vnitřek, mockujte okolí" + „fake > mock". Sada měla typované fakes jen na hranicích (LLM služba, vyhledávač) a reálné vnitřní wiring. Výsledek za celý refaktor: na boundary fakes jsem nesáhl ani jednou a testy s reálným vnitřkem přežily výměnu celého úložiště. Rozbilo se v podstatě jen to, co znalo vnitřní strukturu.

Záporná hodnota testů znalých vnitřku. ~113 míst ve 14 souborech sahalo přímo na tvar úložiště (ctx.vars.string_outputs[(stage, key)] = ...). Při refaktoru se migrovala skriptem třikrát a nechytila přitom jedinou reálnou regresi. Tvoje formulace „implementace už nevypadá tak, jak jsem si ji představoval" je doslova to, co ty failury říkaly.

Poměr sady. Odhadem 90 % jistoty nesla hrstka kazetových e2e testů při zlomku údržbových nákladů; bez nich by refaktor téhle velikosti byl hazard. Projekt s opačným poměrem, než článek kritizuje, je zároveň důkaz, že doporučení funguje.

Čtyři místa k doostření

1. Coupling se schovává i ve fixtures, nejen v assertech

Článek míří na mocky a assert_called_once_with(...). Naše největší migrační zátěž ale měla behaviorální asserty a seed přes vnitřnosti: testy ověřovaly výsledek poctivě, jenže výchozí stav zakládaly přímými zápisy do úložiště, obcházením veřejného povrchu. Při změně úložiště se rozbily úplně stejně jako choreografické testy. „Seed-heavy" fixtures jsou tatáž nemoc jiným kanálem — test může mít čisté asserty a přesto být přibetonovaný k implementaci. Doporučil bych tomu věnovat odstavec vedle mock-heavy sekce: stav zakládej přes veřejné API (vstupní payload, veřejné operace), ne přes strukturu skladu.

2. Rozliš „rozbití na vnitřní změně" a „rozbití na změně kontraktu"

Při refaktoru spadlo dohromady ~350 testů. Z článku by čtenář mohl vyvodit „špatná sada". Jenže velká část byly contract testy padající na záměrném breaking change — testovaly wire tvar, který jsme měnili. To není křehkost; to je test dělající přesně svou práci. Užitečný indikátor z praxe: tyhle failury šly migrovat mechanicky skriptem, protože konzistentně testovaly tvar, který se konzistentně změnil. Křehké testy se poznají podle toho, že padají, aniž se změnil kontrakt. Věta „rozbije testy tehdy, když rozbije systém" to implikuje, ale explicitní rozlišení by čtenáře ochránilo před závěrem „testy, co se při refaktoru rozbily = špatné testy".

3. Šedá zóna: choreografie, která JE produkt

Měli jsme testy assertující tvar access-event logu (která operace zapíše Read, která Write, která nic). Podle taxonomie článku čistá choreografie → záporná hodnota. Jenže ten log je pozorovatelný kontrakt — konzumuje ho debugovací UI. Takže to jsou legitimní contract testy… a přesto se při každém vnitřním pivotu přepisovaly. Závěr z praxe: i legitimní choreografický kontrakt je drahý závazek a má se vědomě držet malý. Binární dělení „chování dobré / choreografie špatná" tenhle případ nezachytí — stačila by věta, že choreografie povýšená na produkt se testuje jako kontrakt, ale platí se jako choreografie.

4. Nika unittestů jde říct pozitivněji: jednotky s vlastním kontraktem

Sekce „hodnota v den vzniku" platí pro unittesty implementace. Při refaktoru ale vznikl klasický unittestový soubor na nový storage engine (match sémantika, last-write-wins, diagnostika chyb — deterministická logika bez závislostí): byl nepostradatelný při stavbě a pak přežil šest navazujících fází beze změny jediného řádku. Rozdíl není v izolovanosti, ale v tom, že ta jednotka má vlastní dokumentovatelný kontrakt. To je prakticky použitelné kritérium, které by sekci „Ano, unittesty mají své místo" dalo ostřejší hranu: pokud bys sémantiku jednotky dokázal sepsat jako dokumentaci pro cizího čtenáře, unittest na ni stárne dobře; pokud testuješ „co zrovna dělá můj kód", stárne jako pomníček.

Drobnost na závěr

Mentální experiment „jaký projekt bych chtěl převzít" je nejsilnější část textu — a dal by se uzavřít zpětným odkazem z praxe: projekt s tím správným poměrem se pozná podle toho, že velký refaktor je nudný. Failury jsou buď očekávané (kontrakt se měnil) nebo informativní (systém se rozbil), a ta jedna záludná regrese, kterou by nikdo nenapsal do unit testu, se chytí na hraně. Přesně tak to proběhlo.

Thread dump zaseknutého procesu přes signál SIGUSR1

2026-06-20T00:00:00+01:00

Když se produkční proces zasekne, nechcete ho restartovat ani připojovat debugger. Stačí mu poslat SIGUSR1 a nechat ho vysypat stacky všech vláken i asyncio tasků do souboru.

Problém

Worker v kontejneru přestane brát práci. CPU na nule, nic se neděje, žádná chyba v logu. Deadlock? Zaseknuté await? Čeká se na lock, který nikdo nepustí?

Restartem problém zameteete pod koberec a stav zmizí. Připojit gdb nebo py-spy do produkčního kontejneru často nejde — chybí nástroje, práva, nebo prostě nechcete sahat na běžící proces zvenčí. A standardní logy vám neřeknou, kde přesně proces stojí.

Chcete jednu věc: přimět běžící proces, aby sám řekl, co právě dělá každé jeho vlákno — bez restartu, bez externího nástroje.

Řešení: signal handler na SIGUSR1

Unixové procesy umí reagovat na signály. SIGUSR1 (a SIGUSR2) jsou k tomu přímo určené — systém je nijak nevyužívá, jsou „k volnému použití". Zaregistrujeme si na něj handler, který vysype thread dump:

import signal

def init_stack_dumps():
    signal.signal(signal.SIGUSR1, dump_stacks_sig_handle)

Tohle se zavolá jednou při startu aplikace. Od té chvíle stačí procesu poslat signál a on vyplivne dump.

Proč handler spouští nové vlákno

Signal handler v Pythonu má přísná omezení — běží mezi bajtkódy hlavního vlákna a neměl by dělat nic složitého. Proto handler sám jen odpálí daemon vlákno a hned se vrátí:

import threading

def dump_stacks_sig_handle(signal_number, frame):
    t = threading.Thread(target=dump_stacks, daemon=True)
    t.start()

Vlastní práci pak dělá dump_stacks() v klidu mimo handler. daemon=True zajistí, že dumpovací vlákno nebude bránit ukončení procesu.

Sběr stacků

Jádro je sys._current_frames() — vrátí aktuální frame každého běžícího vlákna. To projdeme a u každého vypíšeme formátovaný stack:

import sys, os, threading

def dump_stacks():
    time.sleep(0.1)
    pid = os.getpid()
    filename = f"/tmp/python_thread_dump_{pid}.log"
    with open(filename, "w") as f:
        f.write(f"Thread dump for PID {pid}\n")
        f.write(f"Parent PID {os.getppid()}\n")
        f.write(f"Process breadcrumbs: {", ".join(app_context.process_breadcrumbs)}\n")

        for thread_id, frame in sys._current_frames().items():
            thread_name = threading.current_thread().name
            f.write(f"\nThread {thread_id} ({thread_name}):\n")
            f.writelines(format_stack(frame))

Dump jde do /tmp/python_thread_dump_<pid>.log — soubor pojmenovaný podle PID, takže při více procesech (gunicorn, multiprocessing) se dumpy nepřepíšou navzájem.

Asyncio tasky, ne jen vlákna

V async aplikaci sys._current_frames() nestačí — uvidíte jen event loop vlákno, ale ne jednotlivé pozastavené coroutiny. Ty visí jako Task objekty na loopu a mají vlastní stack:

        try:
            loop = asyncio.get_running_loop()
            f.write("\n--- asyncio tasks ---\n")
            for task in asyncio.all_tasks(loop):
                f.write(f"Task: {task}\n")
                if task.get_coro():
                    f.write(f"Coro: {task.get_coro()}\n")
                if task.get_stack():
                    for frame in task.get_stack():
                        f.writelines(format_stack(frame))
        except RuntimeError:
            f.write("\nNo running asyncio loop detected.\n")

asyncio.all_tasks() vyjmenuje všechny živé tasky a task.get_stack() ukáže, na kterém await přesně každý stojí. Tohle je přesně to, co u zaseknuté async aplikace potřebujete vidět — který task čeká na čem. RuntimeError ošetřuje případ, kdy proces žádný loop neběží (čistě synchronní worker).

Vlastní kód zvýrazněný hvězdičkou

Stack zaseknutého procesu je dlouhý a většina řádků je šum z knihoven a stdlib. Trik: řádky, které vedou do vlastního kódu aplikace, dostanou prefix *:

def format_stack(frame):
    stack = traceback.format_stack(frame)
    formatted_stack = []
    for line in stack:
        if line.startswith('  File "' + app_root):
            formatted_stack.append(f"* {line[:-1]}".replace("\n", "\n* ") + "\n")
        else:
            formatted_stack.append(f"  {line[:-1]}".replace("\n", "\n  ") + "\n")
    return formatted_stack

app_root je kořen aplikace (odvozený z __file__). V dumpu pak stačí grepnout ^\* a vidíte jen své vlastní rámce — místo, kde se to ve vašem kódu zaseklo, bez prokousávání se stdlib.

K tomu se na začátku dumpu vypíšou breadcrumbs — krátká stopa posledních událostí, kterou si aplikace průběžně udržuje. Často hned napoví, co proces dělal těsně před zaseknutím.

Použití

Návod je ideální nechat rovnou v komentáři u zdrojáku. Přes Docker Compose to vypadá takhle:

# uklidit staré dumpy
docker compose exec service-process sh -c "rm /tmp/python_thread_dump_*"

# poslat signál všem python procesům v kontejneru
docker compose exec service-process pkill -SIGUSR1 -f python

# vytáhnout jen podstatné řádky — hlavičky a vlastní kód
docker compose exec service-process sh -c \
  "grep -e '^Thread' -e '^\*' -e '^Process breadcrumbs' /tmp/python_thread_dump_*"

pkill -SIGUSR1 -f python zasáhne všechny matchnuté procesy najednou — každý si zapíše vlastní soubor podle PID, takže u multiprocess setupu dostanete kompletní obrázek jedním příkazem.

Drobnost: vnořené uvozovky v f-stringu

Řádek s breadcrumbs používá uvozovky uvnitř f-stringu i kolem něj:

f.write(f"Process breadcrumbs: {", ".join(app_context.process_breadcrumbs)}\n")

", ".join(...) se stejnými uvozovkami jako celý f-string by před Pythonem 3.12 byla syntaktická chyba. Od PEP 701 (Python 3.12) to projde — f-stringy už používají plnohodnotný tokenizer a vnořování uvozovek je povolené.

Obecnější pozorování

SIGUSR1/SIGUSR2 jsou zdarma k dispozici pro vlastní ovládání běžícího procesu. Thread dump je nejtypičtější použití, ale stejně tak jde signálem přepnout log level nebo vyžádat metriky.
Signal handler musí být minimální — odpálit vlákno a vrátit se. Veškerou logiku dělejte mimo handler.
sys._current_frames() + asyncio.all_tasks() se doplňují. Jen vlákna vám u async aplikace ukážou prázdný event loop; teprve tasky řeknou, kde coroutiny stojí.
Soubor podle PID je nutnost u multiprocess služeb — jinak si procesy dumpy přepíšou.
Prefix vlastního kódu mění nepoužitelně dlouhý dump v něco, co přečtete jedním grepem. Drobnost s velkým dopadem.

Korelační log markery napříč async kontextem (a DelayedLogmarker)

2026-06-20T00:00:00+01:00

Jak nad standardním logging postavit korelační ID, která se sama propíšou do všech vnořených logů přes ContextVar, hashují citlivé hodnoty — a jak bufferovat logy, dokud ještě neznáte ID tasku.

Problém

V asynchronní aplikaci běží desítky tasků naráz a jejich logy se v jednom streamu prolínají. Bez korelačního ID nepoznáte, které řádky patří k sobě:

level=INFO message=Task started.
level=INFO message=Downloading source...
level=INFO message=Task started.
level=ERROR message=Download failed.

Které „started" patří k tomu „failed"? Klasické řešení je protáhnout task_id parametrem skrz každou funkci, která loguje. To je otrava a stejně to nevydrží — jakmile log vznikne o tři vrstvy hlouběji v knihovně, kontext je pryč.

K tomu dva přidružené požadavky:

Citlivá ID nechci v logu plaintextem (userId, e-mail) — ale chci je dohledat. Potřebuju stabilní pseudonym, ne čitelnou hodnotu.
Korelační ID někdy ještě neznám, když chci začít logovat. Na startu tasku zaloguju „task started", ale samotné ID tasku se přiřadí až o pár řádků níž.

Všechno tohle jde vyřešit bez externí knihovny (structlog, loguru) — stačí contextvars a vlastní logging.Filter.

Markery, které se nesou samy

Jádro je ContextVar se slovníkem markerů a context manager, který do něj přidává:

from contextvars import ContextVar

markers_var: ContextVar[dict] = ContextVar("markers", default={})

@contextmanager
def logmarker(**kwargs):
    old_markers = markers_var.get()
    new_markers = hashed_markers(**kwargs)
    token = markers_var.set({**old_markers, **new_markers})
    try:
        yield
    finally:
        markers_var.reset(token)

ContextVar je asyncio-aware — hodnota se izoluje per-task a automaticky se nese skrz await. Vnořené logmarker() bloky se slévají, takže markery z vnějšího kontextu zůstávají dostupné uvnitř:

with logmarker(process="extract", task=task_id):
    logger.info("Task started.")        # markers=[process=... task=...]
    with logmarker(source=source_id):
        logger.info("Downloading...")   # markers=[process=... task=... source=...]

Hashování citlivých hodnot

Hodnoty markerů se neukládají syrově. Projdou přes SHA256 → base32 → prvních 8 znaků:

def short_hash(obj, length=8):
    data = stable_string(obj).encode("utf-8")
    digest = hashlib.sha256(data).digest()
    b32 = base64.b32encode(digest).decode("ascii").rstrip("=")
    return b32[:length]

def hashed_markers(**kwargs):
    return {k: short_hash(v) if not k.startswith("_") else v for k, v in kwargs.items()}

Hash je stabilní — stejný userId dá vždycky stejný 8znakový kód, takže napříč logy (i napříč službami) půjde grepnout, ale samotnou hodnotu z něj nikdo nezíská.

Konvence: klíče začínající podtržítkem se nehashují. Slouží pro meta/vizuální pole, která nejsou citlivá (_cls_name, _visual) — tam chcete čitelnou hodnotu.

stable_string ještě řeší serializaci čehokoliv: nejdřív zkusí json.dumps(sort_keys=True), a když to neprojde, spadne na pickle + base85. Tím se hashování nikdy nerozbije na neserializovatelném vstupu.

Filtr, který markery vstříkne do každého logu

Markery se do log záznamu dostanou přes vlastní logging.Filter, který sedí na handleru. Filtr ze slovníku poskládá marker_str a přilepí ho na record:

class MarkerFilter(logging.Filter):
    def filter(self, record):
        markers = markers_var.get()
        record.marker_str = " ".join(
            f"{k}={v}" if not k.startswith("_") else v
            for k, v in markers.items()
        ) if markers else ""
        ...
        return True

Formatter pak marker_str jen vypíše:

class HumanReadableFormatter(logging.Formatter):
    def format(self, record):
        markers = getattr(record, "marker_str", "")
        return (
            f"timestamp={self.formatTime(record)} "
            f"logger={record.name} level={record.levelname} "
            f"markers=[{markers}] message={record.getMessage()}"
        )

Důležité je, že se MarkerFilter registruje na root handleru — funguje tedy i pro logy z knihoven třetích stran, aniž by o markerech cokoliv věděly.

DelayedLogmarker — bufferování, než znáte ID

Teď to zajímavé. Co když chcete logovat dřív, než znáte marker? Typicky na startu tasku: chcete zalogovat průběh inicializace, ale ID tasku se ustaví až někde v jejím průběhu.

DelayedLogmarker to řeší tak, že logy během bloku nezahazuje ani nevypisuje — pozdrží je, a vypíše je zpětně, jakmile markery doplníte. Funguje to přes druhý ContextVar, který drží buffer:

buffer_var: ContextVar[list | None] = ContextVar("buffer_var", default=None)

A MarkerFilter má kvůli tomu druhou půlku, kterou jsem výš vynechal:

    def filter(self, record):
        markers = markers_var.get()
        record.marker_str = ...  # jako výše

        buffer_list = buffer_var.get()
        if buffer_list is None:
            return True                  # běžný režim — log projde
        else:
            buffer_list.append(
                lambda: logging.getLogger(record.name).handle(record)
            )
            return False                 # buffer režim — log se pozdrží

Klíčový trik: v buffer režimu filtr vrátí False (log se hned nevypíše) a místo toho si uloží closure record.handle do bufferu. Záznam je zachycený celý — až ho později pustíte, projde znovu celou cestou formatterem, takže dostane i markery, které v té chvíli ještě neexistovaly.

Použití:

with DelayedLogmarker(process="extract") as delayed:
    logger.info("Initializing task...")      # pozdrženo
    task_id = await create_task()
    delayed.set_markers_and_flush(task=task_id)
    # ↑ teď se "Initializing task..." vypíše — už s task=<hash>
    logger.info("Task ready.")               # vypíše se rovnou

Když set_markers_and_flush nezavoláte, dotáhne ho __exit__ automaticky — buffer se vždycky vyprázdní a žádný log se neztratí. Opakované volání naopak hlídá a vyhodí RuntimeError, aby nedošlo k dvojímu flushnutí.

Napojení na Sentry zadarmo

Protože markery žijí v ContextVar, jdou přečíst odkudkoliv — třeba v Sentry before_send hooku, který je promítne jako tagy:

def get_sentry_logmarkers(event, hint):
    markers = {f"logmarker_{k}": str(v) for k, v in markers_var.get().items()}
    event.setdefault("tags", {}).update(markers)
    return event

V Sentry pak filtrujete chyby podle logmarker_task stejným hashem, jaký vidíte v logu. Korelace mezi logem a chybou je tím hotová bez jediného řádku navíc v aplikačním kódu.

Obecnější pozorování

ContextVar je správný nástroj pro per-task kontext v asyncio. Thread-local by selhal — coroutiny sdílejí vlákno. ContextVar se izoluje per-task a nese se skrz await automaticky.
Registrace filtru na root handleru dává markery i logům z knihoven, které o systému nevědí. Žádné protahování parametrů.
Bufferování přes uloženou closure record.handle je elegantní: nemusíte řešit re-formátování, stačí pozdržet volání. Záznam si pamatuje všechno sám.
Stabilní hash jako pseudonym je levný kompromis mezi „nelogovat citlivé hodnoty vůbec" a „logovat je plaintextem". Dohledatelnost zůstává, hodnota mizí.
Cena za eleganci je dvojí význam jednoho filtru — MarkerFilter zároveň vstřikuje markery i řídí bufferování. Bez znalosti DelayedLogmarker ten return False v filter() vypadá jako bug.