Enterprise phiên bản

Đo lường sử dụng

Tổng quan nhanh

NextPDF Enterprise thu thập đo lường sử dụng — số thao tác, số trang đã xử lý, thời lượng — tại lớp điều phối PHP để phục vụ lập hóa đơn và kiểm toán. Các mục được đệm trong bộ nhớ, được xả ra một hoặc nhiều backend theo lô, và một backend thất bại không bao giờ chặn việc xử lý. Trang này mô tả hành vi đo lường quan sát được và contract công khai.

Tính khả dụng và cấp phép

Năng lực này được phát hành trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt cùng một envelope giấy phép bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. Đo lường là một năng lực Enterprise nền tảng, không có cờ riêng cho từng tính năng. So sánh các phiên bản và lấy giấy phép.

Tổng quan khái niệm

Collector đo lường ghi một mục bất biến cho mỗi thao tác: một loại thao tác, một số lượng đơn vị, một dấu thời gian, các định danh tenant và license, số trang đã xử lý, thời lượng thao tác, và metadata dạng tự do. Các mục tích lũy trong một bộ đệm trong bộ nhớ. Khi bộ đệm đạt kích thước được cấu hình, nó tự xả; bạn cũng có thể xả tường minh, và một shutdown handler có thể được đăng ký để một worker PHP-FPM xả phần còn lại vào cuối request. Một worker chạy lâu (ví dụ một worker Octane hoặc Symfony) nên xả theo một bộ định thời định kỳ thay vì cách đó.

Reporter phân phát một lô ra một hoặc nhiều backend. Các backend được cô lập: một thất bại ở một backend không ngăn các backend khác nhận lô. Mỗi lần gửi tới backend được thử lại tối đa một số lần được cấu hình; nếu mọi lần thử đều thất bại, lô cho backend đó được ghi nhật ký và bị loại bỏ — đo lường là best-effort và không gây lỗi nghiêm trọng theo thiết kế, nên một sự cố đo lường không bao giờ làm suy giảm việc xử lý tài liệu. Một backend là bất kỳ hiện thực nào của interface backend đo lường — một đích push Prometheus, một billing API, một cơ sở dữ liệu, hay một hàng đợi — và các hiện thực bắt buộc phải lũy đẳng (idempotent) để một lô bị lặp được xử lý một cách nhẹ nhàng.

Đo lường ở mức điều phối này nhằm phục vụ khả năng quan sát cho lập hóa đơn và kiểm toán. Nó chủ ý không phải là nguồn có thẩm quyền để thực thi hạn mức; các quyết định về hạn mức được đưa ra ở nơi khác trong triển khai từ một con số sử dụng có thẩm quyền.

Vì sao nó hoạt động theo cách này

Đo lường nằm trên đường lập-hóa-đơn-và-kiểm-toán, không phải đường xử lý tài liệu, và sự tách biệt đó là có chủ ý. Mỗi lời gọi record nối thêm một MeterEntry bất biến vào một bộ đệm trong bộ nhớ, nên việc ghi nhận sử dụng vẫn là một thao tác O(1). Việc xả diễn ra theo lô, phân phát ra các backend được cô lập sau contract MeteringBackendInterface. Một endpoint lập hóa đơn chậm hoặc chết khi đó sẽ suy giảm một cách nhẹ nhàng, và một lô đã cạn kiệt lần thử được ghi nhật ký và bị loại bỏ thay vì bị ném lỗi. Nhờ vậy một sự cố đo lường không bao giờ làm đình trệ công việc khối lượng lớn hay cạnh tranh với thông lượng tài liệu. Đánh đổi là đo lường điều phối mang tính best-effort và không có thẩm quyền — nên việc thực thi hạn mức được quyết định ở nơi khác từ một con số có thẩm quyền.

Bối cảnh thiết kế: Tạo tài liệu khối lượng lớn.

Bề mặt Public API

composer require nextpdf/enterprise:^3

Các điểm tích hợp được hỗ trợ là meter collector (record, flush, bufferCount, registerShutdownFlush), reporter đo lường (report), interface backend đo lường (report, isHealthy, backendName), và đối tượng giá trị meter entry bất biến. Việc cung cấp một hiện thực backend an toàn khi không thử lại, lũy đẳng, cho độ bền production là trách nhiệm của bạn.

Mẫu mã — bắt đầu nhanh

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,
);

Mẫu mã — production

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

Trường hợp biên và lưu ý

Xả là lũy đẳng. Gọi flush trên một bộ đệm rỗng là một no-op; xả hai lần là an toàn.
Backend thất bại không gây lỗi nghiêm trọng. Các lần thử lại cạn kiệt sẽ ghi một lỗi và loại bỏ lô của backend đó; lời gọi vẫn trả về bình thường. Đừng dựa vào đo lường để thực thi hạn mức cứng.
Cần ít nhất một backend. Việc khởi tạo một reporter với danh sách backend rỗng sẽ bị từ chối.
Tính lũy đẳng là việc của backend. Contract của interface yêu cầu các backend khử trùng lặp (theo dấu thời gian, thao tác và tenant) — một lô bị thử lại hoặc bị lặp không được tính trùng.
Mô hình worker quan trọng. Dùng shutdown handler cho PHP-FPM; dùng xả theo bộ định thời định kỳ cho các worker chạy lâu, nếu không các mục sẽ đệm lại cho tới khi worker thoát.

Hiệu năng

record là một thao tác append vào bộ đệm O(1). Chi phí xả tỷ lệ thuận với kích thước lô và số lượng backend; nó được đưa ra khỏi đường request nhờ việc đệm và nhờ shutdown handler. Các lần thử lại áp dụng cho từng backend, bị giới hạn bởi số lần thử được cấu hình.

Ghi chú bảo mật

Các mục đo lường mang theo các định danh tenant và license cùng metadata thao tác. Hãy coi metadata là có khả năng nhạy cảm và giới hạn phạm vi lưu trữ và lưu giữ backend của bạn theo các yêu cầu tuân thủ của bạn. Các định danh tenant và license phải bắt nguồn từ một ngữ cảnh đã xác thực.

Phù hợp tiêu chuẩn

Đo lường không định nghĩa định dạng truyền (wire format) riêng nào tại ranh giới công khai — interface backend ủy thác việc tuần tự hóa cho từng hiện thực backend (ví dụ, một đích push Prometheus tuân theo các quy ước exposition của Prometheus). Không có tiêu chuẩn bên ngoài nào được khẳng định tại bề mặt này; không có trích dẫn RAG cho trang này vì không có đặc tả quy phạm nào chi phối contract của collector trong tiến trình.

Hợp đồng hành vi

Collector ghi một mục bất biến cho mỗi thao tác và tích lũy các mục trong một bộ đệm trong bộ nhớ tự xả ở kích thước được cấu hình; xả tường minh và một shutdown-flush handler cũng có sẵn.
Xả là lũy đẳng: xả một bộ đệm rỗng là một no-op và xả hai lần là an toàn.
Reporter phân phát một lô ra một hoặc nhiều backend với sự cô lập từng backend; thất bại của một backend không ngăn các backend khác.
Mỗi lần gửi tới backend được thử lại tối đa số lần được cấu hình; các lần thử lại cạn kiệt được ghi nhật ký và bị loại bỏ — đo lường là best-effort và không bao giờ gây lỗi vào đường xử lý.
Việc khởi tạo một reporter với danh sách backend rỗng bị từ chối; các backend bắt buộc phải lũy đẳng để một lô bị lặp không bị tính trùng.
record là một thao tác append vào bộ đệm O(1); chi phí xả tỷ lệ thuận với kích thước lô và số lượng backend và được giữ ngoài đường request.

Ranh giới công bố

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt Public API được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Phương án dự phòng Core

NextPDF Core (Apache-2.0) không có collector, reporter, hay bề mặt backend đo lường nào — không hề có; năng lực này không có bản tương đương ở bậc Core. Việc xử lý của Core không được NextPDF đo lường.

Phương án dự phòng Pro

NextPDF Pro không có bề mặt đo lường nào — không hề có; năng lực này không có bản tương đương ở bậc Pro. Meter collector, reporter và interface backend chỉ được phát hành trong gói nextpdf/enterprise.

Ghi chú ranh giới Enterprise

Vòng đời bộ đệm, fan-out, thử lại và cô lập được mô tả ở mức hành vi. Interface backend ủy thác việc tuần tự hóa cho từng hiện thực backend; các chi tiết bộ đệm nội bộ và bất kỳ chi tiết fan-out nội bộ nào nằm ngoài phạm vi của bề mặt công khai.

Ranh giới triển khai

Người vận hành sở hữu các hiện thực backend, độ bền và tính lũy đẳng của chúng, phạm vi lưu giữ và lưu trữ của metadata đo lường, và chiến lược xả theo mô hình worker (shutdown handler cho PHP-FPM, bộ định thời định kỳ cho các worker chạy lâu). Một sự cố backend đo lường không bao giờ làm suy giảm việc xử lý tài liệu. Các định danh tenant và license phải bắt nguồn từ một ngữ cảnh đã xác thực mà người vận hành cấu hình.

Ranh giới tuân thủ pháp lý

Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt đo lường. Metadata đo lường có thể nhạy cảm; phạm vi lưu giữ và lưu trữ là trách nhiệm tuân thủ của người vận hành. Tài liệu này không phải là một ý kiến pháp lý; hãy tham vấn các cố vấn tuân thủ và pháp lý của riêng bạn.