Performance: ตัววิเคราะห์การกระจัดกระจายของหน่วยความจำ

ภาพรวมโดยย่อ

โมดูล Performance มีขอบเขตจำกัด โมดูลนี้มีเครื่องมือสำหรับการสังเกตการณ์เท่านั้นหนึ่งรายการคือ MemoryFragmentationAnalyzer ซึ่งวัดหน่วยความจำสูงสุดและหน่วยความจำคงค้างตลอดหน้าต่างการทำงานของเอนจินที่ทำเครื่องหมายไว้ พื้นผิวสาธารณะของโมดูลยังรวมถึงสแนปช็อตแบบไม่เปลี่ยนแปลงได้ที่เครื่องมือนี้สร้างขึ้น โมดูลนี้ไม่บังคับใช้งบประมาณ ไม่จำกัดอัตราการทำงาน และไม่เปลี่ยนพฤติกรรมของเอนจิน

ขอบเขตและความเสถียร พื้นผิวที่แท้จริงของโมดูลนี้คือสองคลาส (MemoryFragmentationAnalyzer, MemoryFragmentationSnapshot) โมดูลนี้ไม่ใช่ ชุดเครื่องมือสำหรับบังคับใช้งบประมาณแบบรายการดำเนินการ ค่า performance_budget ใน frontmatter ของทุกโมดูลเป็นข้อตกลงทางเอกสาร ไม่ใช่ค่าที่ โมดูลนี้บังคับใช้ พื้นผิวนี้อยู่ในระดับ experimental โดยเป็นเครื่องมือวินิจฉัย ที่เริ่มมีใน @since 3.2.0 รูปแบบสแนปช็อตของโมดูลอาจมีการเปลี่ยนแปลง

การติดตั้ง

composer require nextpdf/core:^3

ภาพรวมเชิงแนวคิด

การใช้ทรัพยากรเป็นประเด็นด้านคุณภาพระดับแรกสำหรับเอนจิน Portable Document Format (PDF) สิ่งที่ต้องสังเกตอย่างน้อยคือความแตกต่างระหว่างหน่วยความจำ สูงสุด (จุดสูงสุดระหว่างหน้าต่างการทำงาน) และหน่วยความจำ คงค้าง (ส่วนที่ยังถูกยึดไว้หลังจบหน้าต่างการทำงาน) โมดูลนี้วัดเฉพาะจุดดังกล่าว

MemoryFragmentationAnalyzer ทำหน้าที่สังเกตการณ์เท่านั้น โดยไม่เปลี่ยนสถานะของ writer หรือเอกสาร reset() จะรันรอบการเก็บขยะ (GC) และรีเซ็ตตัวนับค่าสูงสุดของ PHP เพื่อให้การวัดหลังจากนั้นอยู่ในหน้าต่างที่นับจากการรีเซ็ต mark(string $label) จะจับ MemoryFragmentationSnapshot ณ จุดที่มีป้ายกำกับ snapshots() จะคืนชุดข้อมูลที่จับไว้ peakDelta() และ retainedDelta() จะรายงานการเปลี่ยนแปลงของค่าสูงสุดและค่าคงค้างตลอดการรัน

MemoryFragmentationSnapshot เป็น value object แบบ final readonly ที่แทนจุดซึ่งมีป้ายกำกับ พร้อม transientBytes() (ค่าสูงสุดลบด้วยค่าคงค้าง ซึ่งคือหน่วยความจำที่ถูกใช้แล้วปล่อยไป) retentionRatio() (ค่าคงค้างหารด้วยค่าสูงสุด) และ toArray() สำหรับการส่งออก ค่า transient-bytes ที่สูงพร้อมอัตราการคงค้างต่ำบ่งชี้ถึงการหมุนเวียนที่กลยุทธ์การใช้บัฟเฟอร์ซ้ำอาจช่วยลดได้ ทั้งสองคลาสเป็น @since 3.2.0

พื้นผิว API

คลาส	สมาชิกหลัก	บทบาท
MemoryFragmentationAnalyzer	reset(), mark(string $label), snapshots(), peakDelta(), retainedDelta()	ตัววิเคราะห์หน่วยความจำสำหรับการสังเกตการณ์เท่านั้น (@since 3.2.0)
MemoryFragmentationSnapshot	transientBytes(), retentionRatio(), toArray()	การวัดแบบมีป้ายกำกับและไม่เปลี่ยนแปลงได้ (@since 3.2.0)

รัน composer docs:generate-api-php -- --module=Performance เพื่อสร้างตาราง PHPDoc ฉบับเต็ม

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

ใส่เครื่องมือวัดในเส้นทางที่มีภาระงานสูง แล้วอ่านค่าเดลตา

<?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());

ตัวอย่างโค้ด — การใช้งานจริง

ห่อหุ้มการเรนเดอร์และส่งสแนปช็อตการกระจัดกระจายไปยังปลายทางที่เก็บเมตริก ให้ถืออัตราการคงค้างต่ำภายใต้ transient bytes ที่สูงเป็นสัญญาณของการหมุนเวียน

<?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());
        }
    }
}

กรณีขอบและข้อควรระวัง

• reset() จะเรียก gc_collect_cycles() และ memory_reset_peak_usage() การเรียกนี้มีผลแบบ process-global ต่อตัวนับค่าสูงสุดของ PHP อย่าสลับการเรียกนี้กับคอมโพเนนต์อื่นที่อ่านตัวนับเดียวกันภายในคำขอเดียวกัน
• การวัดเป็นของหน้าต่างที่นับจาก reset() ครั้งล่าสุด การเรียก mark() โดยไม่มี reset() มาก่อนจะวัดนับจากจุดเริ่มต้นกระบวนการ ซึ่งโดยปกติไม่ใช่สิ่งที่ต้องการ
• นี่คือเครื่องมือวินิจฉัย ไม่ใช่กลไกควบคุม เครื่องมือนี้ไม่เคยจำกัดอัตราหรือยกเลิกการทำงาน อย่าสร้างกลไก back pressure บนเครื่องมือนี้
• โปรไฟล์ความสามารถในการทำซ้ำเป็นแบบ structural ตัวเลขไบต์ขึ้นอยู่กับรันไทม์ ตัวจัดสรร และสถานะของ GC การรันสองครั้งอาจให้ตัวเลขต่างกันแม้เป็นงานเชิงตรรกะเดียวกัน

ประสิทธิภาพ

โอเวอร์เฮดของตัววิเคราะห์เองคือรอบการเก็บขยะที่ reset() และการอ่าน hrtime() / memory_get_* หนึ่งครั้งต่อ mark() ซึ่งน้อยมากเมื่อเทียบกับงานที่สังเกตการณ์ โมดูลนี้จัดสรรสแนปช็อตขนาดเล็กหนึ่งรายการต่อ mark() ค่า performance_budget ใน frontmatter นี้เป็นตัวเลขอ้างอิงสำหรับเอกสารทั้งหน้า โมดูลนี้ไม่บังคับใช้ค่าดังกล่าว

หมายเหตุด้านความปลอดภัย

ตัวเลขหน่วยความจำเป็นข้อมูลเชิงวินิจฉัย ตัวเลขเหล่านี้ไม่มีเนื้อหาของเอกสาร แต่โปรไฟล์หน่วยความจำที่ละเอียดอาจเปิดเผยขนาดและรูปแบบของอินพุตได้ ให้ถือการส่งออกสแนปช็อตเป็นเทเลเมทรีภายใน และดำเนินการตามข้อกำหนดการล้างข้อมูลในล็อกของโปรเจกต์ก่อนแบ่งปันออกไปภายนอก โมดูลนี้ไม่ทำ input/output (I/O) ใด ๆ และไม่ฝังข้อมูลภายนอก ดูที่ /modules/core/security/ สำหรับแบบจำลองภัยคุกคามของเอนจิน

ความสอดคล้อง

โมดูลนี้ไม่กล่าวอ้างเชิงบรรทัดฐานใด ๆ เกี่ยวกับข้อกำหนด PDF โมดูลนี้เป็นเครื่องมือวินิจฉัยหน่วยความจำ และไม่ได้นำโปรโตคอลมาตรฐานที่มีข้อกำหนดให้อ้างอิงมาใช้ เหตุผลเชิงสถาปัตยกรรมของโมดูลอ้างอิงมุมมองด้านคุณภาพการใช้ทรัพยากรจากกรอบการบรรยายสถาปัตยกรรม ISO/IEC/IEEE 42010 การอ้างอิงดังกล่าวเป็นความสอดคล้องกับแนวปฏิบัติด้านสถาปัตยกรรม ไม่ใช่การอ้างอิง PDF ความสอดคล้องของเอนจินได้รับการตรวจสอบโดยชุด oracle และ golden ที่อธิบายไว้ใน /modules/core/conformance/ แล้ว

ดูเพิ่มเติม

• โมดูล Observability — พื้นผิวสถานะขณะรันไทม์ที่ครอบคลุมกว่า
• โมดูล Telemetry — ส่งเมตริกไปยังแบ็กเอนด์ภายนอก
• โมดูล Writer — หัวข้อที่มักถูกสังเกตการณ์ด้านหน่วยความจำ
• แบบจำลองความปลอดภัยของเอนจิน