Sentry PHP 4.32 dovolí běhovému prostředí dodat vlastní úložiště kontextu

Knihovna Sentry PHP posílá z aplikace chyby, logy a metriky. Dlouho počítala s tím, že proces PHP obsluhuje jeden požadavek za druhým: na začátku se nastaví vlastnosti, na konci se vyprázdní vyrovnávací paměti a proces skončí. Verze 4.21.0 z 24. února 2026 k tomu přidala runtime context, tedy schránku na stav jedné jednotky práce. Důvodem byly dlouho žijící workery FrankenPHP a RoadRunner, které drží paměť mezi požadavky, takže data z jednoho uměla prosáknout do dalšího.

Klíč, který byl vždycky stejný

Ve verzi 4.31.0 vypadala vnitřní správa těch schránek obecně: třída RuntimeContextManager vedla dvě mapy, jednu s aktivními kontexty a druhou s přiřazením klíče běhu ke kontextu. Jenže ten klíč vracela metoda getExecutionContextKey() a v jejím těle stál jediný řádek: konstanta PROCESS_EXECUTION_CONTEXT_KEY s hodnotou process. Komentář nad ní říkal, že všechny podporované režimy zatím používají klíč vázaný na proces.

Pro PHP-FPM i pro FrankenPHP to sedí, protože worker obsluhuje jeden požadavek v jednu chvíli. V serveru, kde se požadavky překrývají, to sedět přestane. Druhý požadavek si pod týmž klíčem najde schránku toho prvního, oba pak sdílejí stav, logy i metriky a jeden z nich může vyprázdnit nebo odebrat data toho druhého. Přesně takhle to popisuje žádost o začlenění číslo 2190, ze které změna vzešla.

Co ve 4.32.0 přibylo

Nové rozhraní Sentry\State\RuntimeContextStorageInterface má tři metody. get() vrátí kontext právě běžící úlohy, set() ho uloží, remove() ho odebere a vrátí. Nic dalšího SDK po běhovém prostředí nechce: schránku pořád vyrábí, plní a vyprazdňuje samo, jen se přestalo starat o to, kde leží. Úložiště se zapisuje jednou při startu aplikace a drží se i přes další inicializaci SDK.

// jednou při startu, dřív než se rozběhnou úlohy
SentrySdk::setRuntimeContextStorage($storage);

// na začátku jedné úlohy
SentrySdk::startContext($hub);
// ... obsluha požadavku ...
SentrySdk::endContext();

Druhá změna s tou první souvisí: startContext() bere nepovinný HubInterface. Frameworky, které si zásobník scope drží ve vlastním úložišti vázaném na korutinu, tak předají rovnou svůj hub. Dosud jim SDK vyrobilo hub i kopii scope, které vzápětí zahodily. Vyžádal si to druhý, kratší patch číslo 2191.

Co musí běhové prostředí dodržet

Dokumentace rozhraní vyjmenovává podmínky a je jich víc, než vypadá ze tří metod. Úložiště musí být vázané na běh, ne na proces. Kontext se musí založit dřív, než se vymění hub, jinak úloha přepíše společný základ, ze kterého vycházejí ostatní. endContext() se musí zavolat dřív, než se uvolní stav vázaný na běh, protože teprve on odešle nasbíranou telemetrii. A když úloha skončí nečekaně a k tomu volání nedojde, musí kontext uklidit samo úložiště. Sdílí-li potomek kontext rodiče, drží se ten kontext tak dlouho, dokud ho nepustí poslední vlastník.

Jedna podmínka je tvrdší, než by člověk čekal. Nová inicializace SDK i změna zapsaného úložiště zahodí kontext aktuální úlohy bez vyprázdnění, takže souběžný běh nesmí ani jedno udělat, dokud jsou jiné úlohy živé. Důvod stojí v dokumentaci natvrdo: SDK nemá jak cizí úložiště projít.

Podnět přišel z korutinového frameworku

Patch poslal vývojář vystupující jako binaryfire, spoluautor frameworku Hypervel a přispěvatel do rozšíření Swoole. Hypervel je framework psaný v duchu Laravelu nad korutinami; jeho dokumentace popisuje, že každý worker obsluhuje víc požadavků naráz a operace vstupu a výstupu přitom neblokují. Autor v žádosti píše, že chtěl do frameworku přidat integraci Sentry, ale SDK to bezpečně nedovolovalo. Projekt je malý, hlavní repozitář má na GitHubu 33 hvězdiček. Změna sama na Swoole vázaná není a sáhnout po ní můžou i Amp nebo ReactPHP.

V žádosti zůstala i otevřená pochybnost o pojmenování. Uložená hodnota se jmenuje Sentry\State\RuntimeContext, kdežto Sentry\Context\RuntimeContext ve stejném SDK znamená údaje o prostředí připojené k události. Autor sám navrhl srozumitelnější ExecutionContext, jméno ale zůstalo.

Bez vlastního úložiště se nemění nic

Aplikace, která žádné úložiště nezapíše, jede dál po staru a kontext jí zůstává vázaný na proces. Výchozí cesta se dokonce zjednodušila: místo dvou map a jejich úklidu drží manažer jednu položku a soubor RuntimeContextManager.php zhubl z 9 342 na 7 630 bajtů. Vzory pro FrankenPHP a RoadRunner v testech dál používají obal withContext() a měnit se nemusely.

Vedle kontextů přibyly ve 4.32.0 přílohy k událostem, přenesené z připravované řady 5, a ošetření výjimek z uživatelských funkcí, které dosud uměly shodit celou aplikaci. Podporované verze jazyka se nemění, balíček dál žádá PHP 7.2 nebo 8.x. Vydání nese datum 24. září 2026 na GitHubu i v registru Packagist, kde je zapsané šest minut před tím na GitHubu.

Zdroje: vydání Sentry PHP 4.32.0 a seznam změn v repozitáři, žádosti o začlenění 2190 a 2191, zdrojové soubory rozhraní úložiště a manažeru kontextů ve verzi 4.31.0, data vydání z registru Packagist a dokumentace frameworku Hypervel.