Contracts / Observability

In het kort

Het observability-domein definieert de contracten waarmee de engine zijn runtimetoestand blootstelt: ContextAwareExceptionInterface voor gestructureerde foutcontext, SpectrumInterface voor de optionele versnellings-sidecar, JobNotificationInterface voor gestreamde taakvoortgang, en de DegradationPolicy-enum voor gedrag bij verlies van functionaliteit.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

ContextAwareExceptionInterface is het diagnostische contract. Elke domeinexception van NextPDF implementeert dit. Je kunt elke opgevangen NextPDF-exception als dit contract behandelen en gestructureerde context ophalen voor een Application Performance Monitoring-tool (APM), een loggingpipeline of een foutrapporteur. De context is een associatieve array met snake_case-sleutels en uitsluitend primitieve waarden. Deze bevat geen geneste objecten. Daardoor serialiseert deze voorspelbaar naar een JavaScript Object Notation-payload (JSON) of een APM-payload. Je hoeft geen exceptionbericht te parsen om diagnostische gegevens op te halen. Het is stable sinds 3.1.0.

SpectrumInterface is het contract voor de optionele versnellings-sidecar. Spectrum voert werk parallel uit op de central processing unit (CPU) en verplaatst hardwaredetectie, het parsen van Portable Document Format (PDF) en beeldcompressie naar een lokaal sidecar-proces. Het contract rapporteert de beschikbaarheid achter een circuit breaker, zodat frequente health checks een storing niet versterken wanneer de sidecar is uitgevallen. Het peilt de hardwaremogelijkheden en slaat het resultaat in cache op. Het stelt het actieve resourcebudget bloot. Het biedt ook algemeen requesttransport voor modules op hoger niveau. De engine werkt zonder de sidecar. Het contract maakt van versnelling een injecteerbare optie, geen harde afhankelijkheid. JobNotificationInterface streamt getypeerde taakgebeurtenissen vanaf het server-sent-events-endpoint van de sidecar als generator. De generator stopt wanneer een afsluitende gebeurtenis binnenkomt of de stream wordt gesloten.

DegradationPolicy is de enum voor gedrag bij verlies van functionaliteit. Wanneer functionaliteit degradeert, bepaalt het beleid op basis van de impact of er een exception wordt geworpen, een waarschuwing wordt gegeven of de gebeurtenis stilzwijgend wordt verzameld. Strict werpt een exception wanneer de impact een nalevingsrisico vormt, semantisch verlies veroorzaakt of blokkerend is. Gebruik dit in een gereguleerde omgeving waar correctheid van de uitvoer verplicht is. Balanced, de standaardwaarde, geeft gestructureerde waarschuwingen en gaat door bij begrensde degradatie, en werpt alleen een exception bij blokkerende impact. Gebruik dit voor de meeste productie-implementaties. Permissive verzamelt elke gebeurtenis stilzwijgend en werpt nooit een exception. Gebruik dit voor preview- of conceptmodus waar best-effort-uitvoer aanvaardbaar is. De typen SpectrumInterface, JobNotificationInterface en DegradationPolicy zijn experimental. Hun compatibiliteitsbelofte is zwakker dan die van ContextAwareExceptionInterface.

API-oppervlak

Type	Soort	Belangrijkste members	Stabiliteit	Sinds
ContextAwareExceptionInterface	interface	getContext(): array<string, mixed>	stable	3.1.0
SpectrumInterface	interface	isAvailable(), probe(), getBudget(), request()	experimental	2.1.0
JobNotificationInterface	interface	streamEvents(string): Generator<int, JobEvent>	experimental	2.2.0
DegradationPolicy	enum (string)	Strict, Balanced, Permissive	experimental	2.3.0

getContext() retourneert uitsluitend primitieven of lijsten van primitieven. streamEvents() levert JobEvent-objecten op totdat een afsluitende gebeurtenis binnenkomt. SpectrumInterface::request() retourneert de ruwe response-body als een string. probe() retourneert een HardwareReport, en getBudget() retourneert een SpectrumBudget.

Codevoorbeeld — Snelstart

examples/contracts/observability-quickstart.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\ContextAwareExceptionInterface;
use Psr\Log\LoggerInterface;

/**
 * Log a NextPDF exception with its structured context.
 *
 * @param \Throwable      $e      A caught exception.
 * @param LoggerInterface $logger A PSR-3 logger.
 */
function logWithContext(\Throwable $e, LoggerInterface $logger): void
{
    if ($e instanceof ContextAwareExceptionInterface) {
        $logger->error($e->getMessage(), $e->getContext());

        return;
    }

    $logger->error($e->getMessage());
}

Gestructureerde context komt in het logrecord terecht zonder dat je het bericht hoeft te parsen.

Codevoorbeeld — Productie

examples/contracts/observability-production.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\DegradationPolicy;
use NextPDF\Contracts\SpectrumInterface;
use Psr\Log\LoggerInterface;

final readonly class AcceleratedParseService
{
    public function __construct(
        private ?SpectrumInterface $spectrum,
        private DegradationPolicy $policy,
        private LoggerInterface $logger,
    ) {}

    /**
     * Send a parse batch to the sidecar when healthy, otherwise fall back.
     *
     * @param list<array{id: string, data: string}> $documents PDF binaries with caller IDs.
     *
     * @return string Raw sidecar response body; decode with a batch-result parser.
     */
    public function parse(array $documents): string
    {
        if ($this->spectrum?->isAvailable() === true) {
            return $this->spectrum->request(
                'POST',
                '/v1/parse',
                json: ['documents' => $documents],
                scope: ['parse'],
            );
        }

        if ($this->policy === DegradationPolicy::Strict) {
            throw new \RuntimeException('Accelerator required under strict policy.');
        }

        $this->logger->info('Accelerator unavailable; using PHP fallback.');

        return $this->phpFallback($documents);
    }

    /** @param list<array{id: string, data: string}> $documents @return string */
    private function phpFallback(array $documents): string
    {
        // Pure-PHP parse path omitted for brevity.
        return '';
    }
}

De nullable SpectrumInterface maakt versnelling optioneel. Het contract biedt één transportmethode, request(), die de ruwe response-body als een string retourneert. Een parser op hoger niveau zet die body om in een NextPDF\Accelerator\BatchResult. De concrete SpectrumClient voegt getypeerde helpers toe, zoals parseBatch(), die request() omhullen en direct BatchResult retourneren. Die helpers maken geen deel uit van het vastgelegde contract. Het degradatiebeleid bepaalt of een ontbrekende sidecar fataal is.

Randgevallen en valkuilen

• Niet elke \Throwable is een NextPDF-exception. Bescherm de aanroep met instanceof ContextAwareExceptionInterface voordat je getContext() aanroept.
• getContext() retourneert volgens het contract uitsluitend primitieven. Als je geneste objecten verwacht, klopt die aanname niet; het contract garandeert JSON-veilige waarden.
• SpectrumInterface::isAvailable() draait achter een circuit breaker en kan veilig vaak worden aangeroepen, maar een resultaat true is een momentopname. Houd er rekening mee dat een sidecar tussen de controle en de aanroep kan wegvallen.
• JobNotificationInterface::streamEvents() is een generator. Twee keer itereren speelt de gebeurtenissen niet opnieuw af. Verbruik de generator één keer.
• DegradationPolicy::Permissive werpt nooit een exception. In die modus gaat een degradatie die de naleving beïnvloedt stilzwijgend voorbij. Gebruik deze modus niet voor gereguleerde uitvoer.

Performance

De observability-contracten voegen verwaarloosbare overhead toe. getContext() retourneert een vooraf opgebouwde array. isAvailable() is een gecachete healthprobe met circuit breaker. Het contract vereist dat implementaties het peilingsresultaat ten minste 30 seconden cachen, zodat een hot path de sidecar niet herhaaldelijk aanroept. streamEvents() wordt begrensd door de gebeurtenissnelheid van de sidecar, niet door de engine. Het performance_budget van 1500 ms wandkloktijd en 64 MB piek wordt bepaald door het onderliggende werk dat de contracten observeren, niet door de contracten zelf. Het reproduceerbaarheidsprofiel is structural. Gebeurtenisstreams en exception-contexten bevatten tijdstempels. Twee runs verschillen in die velden terwijl de structuur identiek blijft.

Beveiligingsopmerkingen

Gestructureerde exception-context is een aanvalsoppervlak voor data-exfiltratie als deze geheimen bevat. Het contract beperkt de context tot primitieven, wat onbedoelde objectlekkage beperkt. Je moet gevoelige waarden nog steeds verwijderen voordat de context een log-sink bereikt. Dit is de safe-telemetry-verplichting in het loggingbeleid van het project. De versnellings-sidecar is een afzonderlijk proces dat via een transport wordt bereikt. De requestmethode draagt scope-claims voor autorisatie. Je moet de grens van de sidecar behandelen als een vertrouwensgrens. Een degradatiebeleid dat op Permissive staat, kan een beveiligingsrelevant verlies van functionaliteit maskeren. Gebruik Strict waar correctheid van de uitvoer een control is. Behandel exception-context, taakgebeurtenissen en sidecar-responses als gegevens die gelogd kunnen worden, en verwijder gevoelige gegevens dienovereenkomstig.

Conformiteit

Deze pagina doet geen directe normatieve bewering. De observability-contracten stellen de enginetoestand bloot en implementeren geen gestandaardiseerd protocol waarvan de engine de clausules moet citeren. De hierboven genoemde verplichtingen voor safe telemetry en log-scrubbing zijn afgeleid van het interne loggingbeleid van het project, niet van een externe standaard. Wanneer een geobserveerde bewerking zelf gestandaardiseerd is — een handtekening, een PDF/A-document — dan wordt de conformiteit ervan op de pagina voor ondertekening of extractie gedocumenteerd.

Zie ook

• Contracts: 41 publieke interfaces (SPI) — het SPI-overzicht en de stabiliteitsniveaus.
• Observability — de module voor runtimetoestand die deze contracten blootstelt.
• Accelerator — de Spectrum-sidecarclient achter SpectrumInterface.
• Exception — exceptions die ContextAwareExceptionInterface implementeren.
• Performance — de budgetten waartegen het geobserveerde werk wordt uitgevoerd.