Performance: geheugenfragmentatie-analyzer

In het kort

De Performance-module heeft een afgebakend bereik. De module biedt één uitsluitend observerend hulpmiddel, MemoryFragmentationAnalyzer, dat piekgeheugen en vastgehouden geheugen meet in gemarkeerde vensters van engine-werk. Het publieke oppervlak omvat ook de onveranderlijke snapshot die dit hulpmiddel produceert. De module dwingt geen budgetten af, begrenst geen werk en wijzigt het gedrag van de engine niet.

Bereik en stabiliteit. Het daadwerkelijke oppervlak van deze module bestaat uit twee klassen (MemoryFragmentationAnalyzer, MemoryFragmentationSnapshot). Het is geen mechanisme voor budgethandhaving per bewerking. De waarde performance_budget in de frontmatter van elke module is een documentatieconventie, geen waarde die deze module afdwingt. Het oppervlak is experimental: het is een diagnostisch hulpmiddel dat is geïntroduceerd in @since 3.2.0. De vorm van de snapshot kan zich nog ontwikkelen.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Resourcegebruik is een primair kwaliteitsaspect voor een Portable Document Format-engine (PDF). De minimale observatie is het onderscheid tussen piekgeheugen (de hoogste waarde tijdens een venster) en vastgehouden geheugen (wat na het venster nog in gebruik is). Deze module meet uitsluitend dat.

MemoryFragmentationAnalyzer observeert uitsluitend; de klasse wijzigt de status van de writer of het document niet. reset() voert een garbagecollectiecyclus (GC) uit en stelt de piekteller van PHP opnieuw in, zodat latere metingen bij het venster sinds de reset horen. mark(string $label) legt op een gelabeld punt een MemoryFragmentationSnapshot vast. snapshots() retourneert de vastgelegde reeks. peakDelta() en retainedDelta() rapporteren de verandering in piek- en vastgehouden geheugen over de hele run.

MemoryFragmentationSnapshot is een final readonly waardeobject: een gelabeld punt met transientBytes() (piek minus vastgehouden, dus geheugen dat is gebruikt en weer vrijgegeven), retentionRatio() (vastgehouden ten opzichte van piek) en toArray() voor export. Een hoge transient-bytes-waarde met een lage retentieverhouding wijst op churn die met een strategie voor bufferhergebruik kan worden weggenomen. Beide klassen zijn @since 3.2.0.

API-oppervlak

Klasse	Belangrijkste leden	Rol
MemoryFragmentationAnalyzer	reset(), mark(string $label), snapshots(), peakDelta(), retainedDelta()	Geheugenanalyzer die uitsluitend observeert (@since 3.2.0)
MemoryFragmentationSnapshot	transientBytes(), retentionRatio(), toArray()	Onveranderlijke, gelabelde meting (@since 3.2.0)

Voer composer docs:generate-api-php -- --module=Performance uit om de volledige PHPDoc-tabel te genereren.

Codevoorbeeld — Snelle start

Instrumenteer een kritiek pad en lees daarna de delta’s uit.

<?php

declare(strict_types=1);

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

use NextPDF\Performance\MemoryFragmentationAnalyzer;

$analyzer = new MemoryFragmentationAnalyzer();
$analyzer->reset();

$analyzer->mark('before-write');
// ... engine work under observation ...
$analyzer->mark('after-write');

printf("Peak delta: %d B, retained delta: %d B\n", $analyzer->peakDelta(), $analyzer->retainedDelta());

Codevoorbeeld — Productie

Wikkel een render in en stuur de fragmentatiesnapshot naar een metrics-sink. Beschouw een lage retentieverhouding met veel transient bytes als een churn-signaal.

<?php

declare(strict_types=1);

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

use NextPDF\Performance\MemoryFragmentationAnalyzer;
use Psr\Log\LoggerInterface;

final readonly class RenderMemoryProbe
{
    public function __construct(private LoggerInterface $logger) {}

    /** @param callable():void $render The render closure to observe. */
    public function observe(callable $render): void
    {
        $analyzer = new MemoryFragmentationAnalyzer();
        $analyzer->reset();

        $analyzer->mark('start');
        $render();
        $analyzer->mark('end');

        foreach ($analyzer->snapshots() as $snapshot) {
            $this->logger->info('mem-frag', $snapshot->toArray());
        }
    }
}

Randgevallen en valkuilen

• reset() roept gc_collect_cycles() en memory_reset_peak_usage() aan. Dit heeft een procesbreed effect op de piekteller van PHP. Combineer dit niet met een andere component die binnen dezelfde request dezelfde teller uitleest.
• Metingen behoren tot het venster sinds de laatste reset(). Een mark() zonder voorafgaande reset() meet vanaf de start van het proces, wat doorgaans niet de bedoeling is.
• Dit is een diagnostisch hulpmiddel, geen sturingsmechanisme. Het beperkt of onderbreekt nooit werk. Baseer er geen tegendruk op.
• Het reproduceerbaarheidsprofiel is structural: bytewaarden hangen af van de runtime, de allocator en de GC-status. Twee runs kunnen numeriek verschillen, zelfs bij hetzelfde logische werk.

Prestaties

De overhead van de analyzer zelf bestaat uit één garbagecollectiecyclus bij reset() en één hrtime()- / memory_get_*-uitlezing per mark(), wat verwaarloosbaar is ten opzichte van het werk dat de analyzer observeert. De analyzer alloceert één kleine snapshot per mark(). De waarde performance_budget in deze frontmatter is de documentatiebrede referentiewaarde; deze module dwingt die niet af.

Opmerkingen over beveiliging

Geheugenmetingen zijn diagnostische gegevens. Ze bevatten geen documentinhoud, maar een fijnmazig geheugenprofiel kan de grootte en vorm van de invoer onthullen. Behandel snapshot-exports als interne telemetrie en pas de log-scrubbingverplichting van het project toe voordat ze extern worden gedeeld. De module voert geen input/output (I/O) uit en bevat geen ingebedde externe gegevens. Zie het dreigingsmodel van de engine in /modules/core/security/.

Conformiteit

Deze module doet geen normatieve uitspraak over de PDF-specificatie. Het is een geheugendiagnose en implementeert geen gestandaardiseerd protocol met clausules om naar te verwijzen. De architecturale onderbouwing verwijst naar de kwaliteitsview voor resourcegebruik uit het ISO/IEC/IEEE 42010-framework voor architectuurbeschrijving. Die verwijzing stemt af op architectuurpraktijk en is geen PDF-citaat. De conformiteit van de engine wordt gevalideerd door de oracle- en golden-suites die worden beschreven in /modules/core/conformance/.

Zie ook

• Observability-module — het bredere oppervlak voor runtime-status.
• Telemetry-module — stuurt metrics naar een externe backend.
• Writer-module — een veelvoorkomend onderwerp van geheugenobservatie.
• Beveiligingsmodel van de engine