Enterprise エディション

計測

概要

NextPDF Enterprise は、課金と監査のために、利用状況の計測 — 操作、処理ページ数、所要時間 — を PHP オーケストレーションレイヤーで収集します。エントリはメモリ内にバッファリングされ、バッチで 1 つ以上のバックエンドへフラッシュされます。バックエンドの失敗が処理をブロックすることは決してありません。このページでは、観測可能な計測の挙動とパブリックコントラクトについて説明します。

提供とライセンス

この機能は NextPDF Enterprise（nextpdf/enterprise）で提供され、Enterprise ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントでは、この機能のクラスはロードされません。計測は Enterprise の基本機能であり、機能ごとの個別フラグはありません。エディションを比較してライセンスを取得する。

概念の概要

計測コレクターは、操作ごとに 1 つの不変のエントリ — 操作の種類、ユニット数、タイムスタンプ、テナントおよびライセンス識別子、処理ページ数、操作の所要時間、自由形式のメタデータ — を記録します。エントリはメモリ内バッファに蓄積されます。バッファが構成済みのサイズに達すると自動フラッシュされます。明示的にフラッシュすることもでき、シャットダウンハンドラーを登録すれば、PHP-FPM ワーカーがリクエスト終了時に残りをフラッシュできます。長時間実行されるワーカー（たとえば Octane または Symfony のワーカー）では、代わりに定期タイマーでフラッシュすべきです。

レポーターは、バッチを 1 つ以上のバックエンドへファンアウトします。バックエンドは分離されています。1 つのバックエンドの失敗が、他のバックエンドのバッチ受信を止めることはありません。各バックエンドへの配信は、構成済みの試行回数まで再試行されます。すべての試行が失敗した場合、そのバックエンドのバッチはログに記録されて破棄されます。計測は設計上ベストエフォートかつ非致命的であるため、計測の障害がドキュメント処理を低下させることは決してありません。バックエンドは、計測バックエンドインターフェイスの任意の実装 — Prometheus のプッシュターゲット、課金 API、データベース、キュー — であり、重複したバッチが適切に処理されるよう、実装は冪等であることが要求されます。

このオーケストレーションレベルの計測は、課金と監査の可視性のためのものです。これは意図的に、クォータ強制の権威あるソースではありません。クォータの決定は、デプロイメント内の別の場所で、権威ある利用状況の数値に基づいて行われます。

なぜこの仕組みなのか

計測は、ドキュメント処理のパスではなく、課金と監査のパス上に位置しており、その分離は意図的なものです。各 record 呼び出しは、1 つの不変の MeterEntry をメモリ内バッファに追加するため、利用状況の捕捉は O(1) の操作にとどまります。フラッシュはバッチで行われ、MeteringBackendInterface コントラクトの背後で分離されたバックエンドへファンアウトされます。そのため、低速または停止した課金エンドポイントは適切に劣化し、使い果たされたバッチはスローされるのではなくログに記録されて破棄されます。したがって、計測の障害が大量処理を停止させたり、ドキュメントのスループットと競合したりすることは決してありません。トレードオフとして、オーケストレーション計測はベストエフォートかつ非権威的です。そのため、クォータ強制は権威ある数値に基づいて別の場所で決定されます。

設計背景: 大量ドキュメント生成。

パブリック API サーフェス

composer require nextpdf/enterprise:^3

サポートされる統合ポイントは、メーターコレクター（record、flush、bufferCount、registerShutdownFlush）、計測レポーター（report）、計測バックエンドインターフェイス（report、isHealthy、backendName）、そして不変のメーターエントリ値オブジェクトです。本番の耐久性のために、再試行に安全で冪等なバックエンド実装を提供するのはご自身の責任です。

コードサンプル — クイックスタート

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 を呼び出すのは no-op であり、二重フラッシュは安全です。
バックエンドの失敗は非致命的です。 試行を使い果たすとエラーがログに記録され、そのバックエンドのバッチが破棄されます。呼び出し自体は正常に戻ります。ハードなクォータ強制を計測に依存しないでください。
少なくとも 1 つのバックエンドが必要です。 空のバックエンドリストでレポーターを構築することは拒否されます。
冪等性はバックエンドの役割です。 インターフェイスのコントラクトは、バックエンドが（タイムスタンプ、操作、テナントによって）重複排除することを要求します。再試行または重複したバッチが二重カウントされてはなりません。
ワーカーモデルが重要です。 PHP-FPM にはシャットダウンハンドラーを使用し、長時間実行されるワーカーには定期タイマーによるフラッシュを使用してください。さもなければ、ワーカーが終了するまでエントリがバッファに溜まります。

パフォーマンス

record は O(1) のバッファ追加です。フラッシュコストはバッチサイズとバックエンド数に比例します。バッファリングとシャットダウンハンドラーによって、リクエストパスから外されます。再試行はバックエンドごとに適用され、構成済みの試行回数によって制限されます。

セキュリティに関する注意

計測エントリは、テナントおよびライセンス識別子と操作メタデータを運びます。メタデータは機微である可能性があるものとして扱い、バックエンドのストレージと保持をご自身のコンプライアンス要件に合わせてスコープしてください。テナントおよびライセンス識別子は、認証済みのコンテキストから発生しなければなりません。

適合性

計測はパブリックな境界において独自のワイヤーフォーマットを定義しません。バックエンドインターフェイスは、シリアライゼーションを各バックエンド実装に委譲します（たとえば、Prometheus のプッシュターゲットは Prometheus の exposition 規約に従います）。このサーフェスでは外部標準は主張されません。インプロセスコレクターのコントラクトを規定する規範的な仕様が存在しないため、このページには RAG 引用はありません。

挙動コントラクト

コレクターは操作ごとに 1 つの不変のエントリを記録し、構成済みのサイズで自動フラッシュするメモリ内バッファにエントリを蓄積します。明示的なフラッシュとシャットダウンフラッシュハンドラーも利用できます。
フラッシュは冪等です。空のバッファのフラッシュは no-op であり、二重フラッシュは安全です。
レポーターは、バックエンドごとの分離を伴って、バッチを 1 つ以上のバックエンドへファンアウトします。1 つのバックエンドの失敗が、他のバックエンドを止めることはありません。
各バックエンドへの配信は、構成済みの試行回数まで再試行されます。試行を使い果たすとログに記録されて破棄されます。計測はベストエフォートであり、処理パスにスローすることは決してありません。
空のバックエンドリストでレポーターを構築することは拒否されます。重複したバッチが二重カウントされないよう、バックエンドは冪等であることが要求されます。
record は O(1) のバッファ追加です。フラッシュコストはバッチサイズとバックエンド数に比例し、リクエストパスから外されます。

公開の境界

このページは、外部から観測可能な挙動とサポートされるパブリック API サーフェスのみを説明します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットプレフィックスは範囲外です。

Core フォールバック

NextPDF Core (Apache-2.0) には、計測コレクター、レポーター、バックエンドのサーフェスがありません。一切ありません。この機能には Core ティア相当のものが存在しません。Core の処理は NextPDF によって計測されません。

Pro フォールバック

NextPDF Pro には計測サーフェスがありません。一切ありません。この機能には Pro ティア相当のものが存在しません。メーターコレクター、レポーター、バックエンドインターフェイスは nextpdf/enterprise パッケージにのみ含まれます。

Enterprise の境界に関する注記

バッファのライフサイクル、ファンアウト、再試行、分離は、挙動レベルで説明しています。バックエンドインターフェイスは、シリアライゼーションを各バックエンド実装に委譲します。内部のバッファリングの内部や、内部のファンアウトの詳細は、パブリックサーフェスの範囲外です。

デプロイの境界

オペレーターは、バックエンド実装、その耐久性と冪等性、計測メタデータの保持とストレージのスコープ、そしてワーカーモデルのフラッシュ戦略（PHP-FPM にはシャットダウンハンドラー、長時間実行されるワーカーには定期タイマー）を所有します。計測バックエンドの障害がドキュメント処理を低下させることは決してありません。テナントおよびライセンス識別子は、オペレーターが構成する認証済みのコンテキストから発生しなければなりません。

法令遵守の境界

計測サーフェスには輸出管理上の制限は適用されません。計測メタデータは機微である場合があります。保持とストレージのスコープは、オペレーターのコンプライアンス上の責任です。このドキュメントは法的見解ではありません。ご自身のコンプライアンスおよび法務の助言者にご相談ください。