Enterprise รุ่น

การวัดปริมาณการใช้งาน

ภาพรวมโดยสังเขป

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

ความพร้อมใช้งานและการให้สิทธิ์

ความสามารถนี้จัดส่งใน NextPDF Enterprise ( nextpdf/enterprise ) และเปิดใช้งานด้วยซองสิทธิ์การใช้งานระดับ Enterprise การปรับใช้ที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ Metering เป็นความสามารถพื้นฐานของ Enterprise โดยไม่มีแฟล็กต่อฟีเจอร์แยกต่างหาก เปรียบเทียบรุ่นและรับสิทธิ์การใช้งาน

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

ตัวรวบรวมการวัดบันทึกหนึ่งรายการที่ไม่เปลี่ยนแปลงได้ต่อการดำเนินการ ได้แก่ ชนิดของการดำเนินการ จำนวนหน่วย การประทับเวลา ตัวระบุ tenant และสิทธิ์การใช้งาน จำนวนหน้าที่ประมวลผล ระยะเวลาของการดำเนินการ และข้อมูลเมตาแบบอิสระ รายการสะสมในบัฟเฟอร์ในหน่วยความจำ เมื่อบัฟเฟอร์ถึงขนาดที่กำหนดค่าไว้มันจะ flush อัตโนมัติ คุณยังสามารถ flush อย่างชัดเจนได้ และสามารถลงทะเบียน shutdown handler เพื่อให้ worker ของ PHP-FPM flush ส่วนที่เหลือเมื่อสิ้นสุดคำขอ worker ที่ทำงานยาวนาน (เช่น worker ของ Octane หรือ Symfony) ควร flush ด้วยตัวจับเวลาเป็นระยะแทน

ตัวรายงานกระจายชุดหนึ่งออกไปยังแบ็กเอนด์หนึ่งรายการหรือมากกว่า แบ็กเอนด์ถูกแยกออกจากกัน คือ ความล้มเหลวในแบ็กเอนด์หนึ่งไม่หยุดแบ็กเอนด์อื่นจากการรับชุดนั้น การส่งมอบแต่ละแบ็กเอนด์ถูกลองใหม่ได้สูงสุดตามจำนวนครั้งที่กำหนดค่าไว้ หากความพยายามทั้งหมดล้มเหลว ชุดสำหรับแบ็กเอนด์นั้นจะถูกบันทึกและทิ้ง — การวัดเป็นแบบ best-effort และไม่ร้ายแรงตามการออกแบบ ดังนั้นการขัดข้องของการวัดจึงไม่เคยลดทอนการประมวลผลเอกสาร แบ็กเอนด์คือการนำไปใช้ใด ๆ ของอินเทอร์เฟซแบ็กเอนด์การวัด ไม่ว่าจะเป็นเป้าหมาย push ของ Prometheus, billing API, ฐานข้อมูล หรือคิว และการนำไปใช้ต้องเป็นแบบ idempotent เพื่อให้ชุดที่ซ้ำกันถูกจัดการอย่างเหมาะสม

การวัดในระดับการประสานนี้มีไว้สำหรับการมองเห็นเรื่องการออกใบเรียกเก็บเงินและการตรวจสอบ มันไม่ใช่แหล่งที่มาที่เชื่อถือได้สำหรับการบังคับใช้โควตาโดยเจตนา การตัดสินใจเรื่องโควตาทำที่อื่นในการปรับใช้จากตัวเลขการใช้งานที่เชื่อถือได้

เหตุใดจึงทำงานเช่นนี้

การวัดอยู่บนเส้นทางการออกใบเรียกเก็บเงินและการตรวจสอบ ไม่ใช่เส้นทางการประมวลผลเอกสาร และการแยกนั้นเป็นไปตามเจตนา การเรียก record แต่ละครั้งต่อท้ายหนึ่ง MeterEntry ที่ไม่เปลี่ยนแปลงได้ลงในบัฟเฟอร์ในหน่วยความจำ ดังนั้นการเก็บข้อมูลการใช้งานจึงยังคงเป็นการดำเนินการ O(1) การ flush เกิดขึ้นเป็นชุด กระจายออกไปยังแบ็กเอนด์ที่ถูกแยกออกจากกันภายใต้สัญญา MeteringBackendInterface เมื่อนั้นปลายทางการเรียกเก็บเงินที่ช้าหรือหยุดทำงานจะลดทอนอย่างนุ่มนวล และชุดที่หมดความพยายามจะถูกบันทึกและทิ้งแทนที่จะถูก throw ดังนั้นการขัดข้องของการวัดจึงไม่เคยหยุดชะงักงานปริมาณสูงหรือแย่งทรัพยากรกับปริมาณงานเอกสาร ข้อแลกเปลี่ยนคือการวัดในระดับการประสานเป็นแบบ best-effort และไม่เชื่อถือได้แบบสมบูรณ์ — ดังนั้นการบังคับใช้โควตาจึงถูกตัดสินที่อื่นจากตัวเลขที่เชื่อถือได้

พื้นหลังการออกแบบ: การสร้างเอกสารปริมาณสูง

พื้นผิว API สาธารณะ

composer require nextpdf/enterprise:^3

จุดผสานการทำงานที่รองรับ ได้แก่ ตัวรวบรวมการวัด (record, flush, bufferCount, registerShutdownFlush) ตัวรายงานการวัด (report) อินเทอร์เฟซแบ็กเอนด์การวัด (report, isHealthy, backendName) และอ็อบเจกต์ค่าของรายการการวัดที่ไม่เปลี่ยนแปลงได้ การนำแบ็กเอนด์ที่ปลอดภัยต่อการไม่ลองใหม่และเป็น idempotent ไปใช้เป็นความรับผิดชอบของคุณในการจัดหาเพื่อความคงทนในการใช้งานจริง

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

use NextPDF\Enterprise\Metering\MeterCollector;
use NextPDF\Enterprise\Metering\MeteringReporter;

$collector = new MeterCollector(new MeteringReporter([$backend]), bufferSize: 100);
$collector->registerShutdownFlush(); // PHP-FPM: flush remainder at request end

$collector->record(
    operation: 'parse',
    count: 1,
    tenantId: $tenantId,
    licenseId: $licenseId,
    pagesProcessed: 12,
    durationMs: 84.0,
);

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

use NextPDF\Enterprise\Metering\MeteringReporter;

// Multi-backend fan-out with retry and failure isolation.
$reporter = new MeteringReporter(
    backends: [$prometheusBackend, $billingApiBackend],
    maxRetries: 3,
    logger: $logger,
);

// A failing billing API does not stop Prometheus from receiving the batch;
// exhausted retries are logged and the batch is dropped — never thrown.
$collector = new MeterCollector($reporter, bufferSize: 500);

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

Flush เป็น idempotent การเรียก flush บนบัฟเฟอร์ที่ว่างเปล่าเป็น no-op การ flush ซ้ำสองครั้งปลอดภัย
ความล้มเหลวของแบ็กเอนด์ไม่ร้ายแรง การลองใหม่ที่หมดลงจะบันทึกข้อผิดพลาดและทิ้งชุดของแบ็กเอนด์นั้น ส่วนการเรียกใช้ยังคงคืนค่าตามปกติ อย่าพึ่งพาการวัดสำหรับการบังคับใช้โควตาแบบเข้มงวด
ต้องมีแบ็กเอนด์อย่างน้อยหนึ่งรายการ การสร้างตัวรายงานด้วยรายการแบ็กเอนด์ที่ว่างเปล่าจะถูกปฏิเสธ
Idempotency เป็นหน้าที่ของแบ็กเอนด์ สัญญาของอินเทอร์เฟซกำหนดให้แบ็กเอนด์ dedupe (ตามการประทับเวลา การดำเนินการ และ tenant) — ชุดที่ลองใหม่หรือซ้ำกันต้องไม่นับซ้ำ
โมเดล worker มีความสำคัญ ใช้ shutdown handler สำหรับ PHP-FPM ใช้การ flush ด้วยตัวจับเวลาเป็นระยะสำหรับ worker ที่ทำงานยาวนาน มิฉะนั้นรายการจะบัฟเฟอร์จนกว่า worker จะออก

ประสิทธิภาพ

record เป็นการต่อท้ายบัฟเฟอร์แบบ O(1) ต้นทุนการ flush เป็นสัดส่วนกับขนาดชุดและจำนวนแบ็กเอนด์ มันถูกย้ายออกจากเส้นทางคำขอด้วยการบัฟเฟอร์และ shutdown handler การลองใหม่มีผลต่อแบ็กเอนด์ โดยมีขอบเขตตามจำนวนครั้งที่กำหนดค่าไว้

บันทึกด้านความปลอดภัย

รายการการวัดพกพาตัวระบุ tenant และสิทธิ์การใช้งานและข้อมูลเมตาของการดำเนินการ ให้ปฏิบัติต่อข้อมูลเมตาเสมือนอาจเป็นข้อมูลอ่อนไหว และกำหนดขอบเขตการจัดเก็บและการเก็บรักษาของแบ็กเอนด์ของคุณให้ตรงกับข้อกำหนดการปฏิบัติตามกฎของคุณ ตัวระบุ tenant และสิทธิ์การใช้งานต้องมาจากบริบทที่ผ่านการตรวจสอบสิทธิ์

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

การวัดไม่ได้กำหนดรูปแบบ wire ของตนเองที่ขอบเขตสาธารณะ — อินเทอร์เฟซแบ็กเอนด์มอบหมายการ serialize ให้แต่ละการนำแบ็กเอนด์ไปใช้ (ตัวอย่างเช่น เป้าหมาย push ของ Prometheus เป็นไปตามแบบแผน exposition ของ Prometheus) ไม่มีมาตรฐานภายนอกที่ถูกยืนยันที่พื้นผิวนี้ ไม่มี RAG citation สำหรับหน้านี้เพราะไม่มีข้อกำหนดเชิงบรรทัดฐานที่ควบคุมสัญญาตัวรวบรวมในกระบวนการ

สัญญาด้านพฤติกรรม

ตัวรวบรวมบันทึกหนึ่งรายการที่ไม่เปลี่ยนแปลงได้ต่อการดำเนินการและสะสมรายการในบัฟเฟอร์ในหน่วยความจำที่ flush อัตโนมัติที่ขนาดที่กำหนดค่าไว้ การ flush อย่างชัดเจนและ shutdown-flush handler ก็มีให้ใช้ด้วย
Flush เป็น idempotent คือ การ flush บัฟเฟอร์ที่ว่างเปล่าเป็น no-op และการ flush ซ้ำสองครั้งปลอดภัย
ตัวรายงานกระจายชุดหนึ่งออกไปยังแบ็กเอนด์หนึ่งรายการหรือมากกว่าโดยมีการแยกต่อแบ็กเอนด์ ความล้มเหลวของแบ็กเอนด์หนึ่งไม่หยุดแบ็กเอนด์อื่น
การส่งมอบแต่ละแบ็กเอนด์ถูกลองใหม่ได้สูงสุดตามจำนวนครั้งที่กำหนดค่าไว้ การลองใหม่ที่หมดลงจะถูกบันทึกและทิ้ง — การวัดเป็นแบบ best-effort และไม่เคย throw เข้าสู่เส้นทางการประมวลผล
การสร้างตัวรายงานด้วยรายการแบ็กเอนด์ที่ว่างเปล่าจะถูกปฏิเสธ แบ็กเอนด์ต้องเป็น idempotent เพื่อให้ชุดที่ซ้ำกันไม่นับซ้ำ
record เป็นการต่อท้ายบัฟเฟอร์แบบ O(1) ต้นทุนการ flush เป็นสัดส่วนกับขนาดชุดและจำนวนแบ็กเอนด์ และถูกเก็บไว้นอกเส้นทางคำขอ

ขอบเขตการเผยแพร่

หน้านี้อธิบายเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

การถอยกลับไปใช้ Core

NextPDF Core (Apache-2.0) ไม่มีตัวรวบรวม ตัวรายงาน หรือพื้นผิวแบ็กเอนด์การวัด — ไม่มีเลย ความสามารถนี้ไม่มีสิ่งเทียบเท่าในระดับ Core การประมวลผลของ Core ไม่ได้ถูกวัดโดย NextPDF

การถอยกลับไปใช้ Pro

NextPDF Pro ไม่มีพื้นผิวการวัด — ไม่มีเลย ความสามารถนี้ไม่มีสิ่งเทียบเท่าในระดับ Pro ตัวรวบรวม ตัวรายงาน และอินเทอร์เฟซแบ็กเอนด์การวัดจัดส่งในแพ็กเกจ nextpdf/enterprise เท่านั้น

บันทึกขอบเขตของ Enterprise

วงจรชีวิตของบัฟเฟอร์ fan-out การลองใหม่ และการแยกถูกอธิบายในระดับพฤติกรรม อินเทอร์เฟซแบ็กเอนด์มอบหมายการ serialize ให้แต่ละการนำแบ็กเอนด์ไปใช้ รายละเอียดภายในของการบัฟเฟอร์และรายละเอียด fan-out ภายในใด ๆ อยู่นอกขอบเขตของพื้นผิวสาธารณะ

ขอบเขตการปรับใช้

ผู้ดำเนินการเป็นเจ้าของการนำแบ็กเอนด์ไปใช้ ความคงทนและ idempotency ของมัน ขอบเขตการเก็บรักษาและการจัดเก็บข้อมูลเมตาของการวัด และกลยุทธ์การ flush ตามโมเดล worker (shutdown handler สำหรับ PHP-FPM ตัวจับเวลาเป็นระยะสำหรับ worker ที่ทำงานยาวนาน) การขัดข้องของแบ็กเอนด์การวัดไม่เคยลดทอนการประมวลผลเอกสาร ตัวระบุ tenant และสิทธิ์การใช้งานต้องมาจากบริบทที่ผ่านการตรวจสอบสิทธิ์ซึ่งผู้ดำเนินการกำหนดค่า

ขอบเขตการปฏิบัติตามกฎหมาย

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