OpenTelemetry で NextPDF Connect を観測する
OpenTelemetry で NextPDF Connect を観測する
「OpenTelemetry で NextPDF Connect を観測する」という見出しのセクションNextPDF には、PDF 生成ライフサイクル全体にわたってトレーススパンとメトリクスを発行する組み込みの OpenTelemetry インストルメンテーションが備わっています。クラスパス上に OpenTelemetry SDK が存在しない場合、インストルメンテーションは不活性のままです。パフォーマンスへのペナルティも、オートロードの失敗も、追加設定もありません。これはトランスポート非依存のコンセプトページであるため、PDF がインプロセス呼び出し、MCP の tools/call、REST リクエスト、または NextPDF Connect に対する gRPC 呼び出しのいずれで生成される場合でも、同じインストルメンテーションが適用されます。
このページは、実行可能なレシピというより、説明として読んでください。OpenTelemetry SDK とエクスポーターは NextPDF ではなくホストアプリケーションが提供するため、このページには、再現可能なハッシュを固定できる自己完結型の例はありません。
インストール
「インストール」という見出しのセクションホストアプリケーションが OpenTelemetry SDK と 1 つのエクスポーターを選択し、インストールします。NextPDF はグローバルに登録されたトレーサープロバイダーを読み取り、独自の SDK はバンドルしません。トレースを前提にする前に、バンドルされている可用性プローブを実行し、NextPDF が SDK を認識できることを確認してください。プローブが true を返すのは、OpenTelemetry API がクラスパス上にある場合に限られます。
概念的な概要
「概念的な概要」という見出しのセクションNextPDF は、ドキュメントビルドのライフサイクルに関するスパンと、少数のカウンターおよびヒストグラムを発行します。スパンは、ルートのビルドスパンに加えて、フォント解決、HTML パース、レイアウト、画像デコード、シリアライズ、およびオプションのバーコード、フォーム、ナビゲーション、添付の各フェーズを対象とします。メトリクスは、レンダリング時間、ページ数、警告数、ピークメモリ、出力サイズ、フォント数、画像数を対象とします。正確なスパンとメトリクスの一覧は、インストールされている NextPDF バージョンに依存します。古い記述にある固定の個数はバージョン依存として扱ってください。数値を暗記するのではなく、実行中のビルドに照らして確認してください。
NextPDF Connect が Web フレームワークの背後で動作する場合、Connect 呼び出しは受信リクエストのトレースの子として表示されます。これにより、1 つの分散トレースが HTTP エントリ、アプリケーション、PDF ビルドにまたがります。
API サーフェス
「API サーフェス」という見出しのセクションこのページは、どの Connect ツールも宣言するものではありません。代わりに、横断的なインストルメンテーションについて説明します。ツールサーフェスについては /connect/tool-catalog/ を参照してください。トランスポートについては /transports/mcp/、/transports/rest/、/transports/grpc/. を参照してください。
コードサンプル — クイックスタート
「コードサンプル — クイックスタート」という見出しのセクションPDF を生成する前にトレーサープロバイダーを構築してグローバルに登録し、その後は通常どおり生成します。NextPDF の内部インストルメンテーションは、呼び出しごとにコードを書かなくても、スパンとメトリクスを自動的に発行します。バッファされたスパンが失われないよう、プロセス終了時にプロバイダーをフラッシュしてください。具体的なプロバイダーとエクスポーターの配線方法は、ホストアプリケーションの選択に委ねられます。その内容は OpenTelemetry PHP プロジェクトで文書化されているため、このページでは再掲しません。
コードサンプル — 本番環境
「コードサンプル — 本番環境」という見出しのセクションHTTP でエクスポートするコレクターの場合、ホストは PSR-18 HTTP クライアントを提供します。トランスポートの失敗と、非成功の HTTP ステータスは、2 つの別個のケースとして扱ってください。PSR-18 クライアントが型付きのクライアント例外を送出するのは、リクエストをまったく送信できない場合に限られます（PSR-18 §4）。これに対し、4xx/5xx のレスポンスは呼び出し元に通常どおり返され、例外ではありません（PSR-18 §4）。コレクターのエクスポートパスと Connect ツールのトランスポートは独立しているため、コレクターのエクスポートが失敗しても、PDF 生成そのものを失敗させてはなりません。
エッジケースと落とし穴
「エッジケースと落とし穴」という見出しのセクション- 最初の生成後にプロバイダーを登録した場合。 登録前に作成されたスパンは no-op トレーサーを使用し、バックエンドには決して到達しません。プロバイダーはアプリケーションのブート時に登録してください。
- 終了時のフラッシュがない場合。 バッチプロセッサーはスパンをバッファし、プロバイダーをシャットダウンせずにプロセスが終了すると、そのスパンは失われます。シャットダウン処理をワーカーまたはカーネルの terminate フックに組み込んでください。
- gRPC エクスポートには gRPC PHP 拡張が必要です。 HTTP エクスポートには拡張が不要なため、拡張を利用できない場合は HTTP を選択してください。
- W3C Trace Context の伝播。 受信リクエストに
traceparent/tracestateが含まれる場合、SDK はそのコンテキストを NextPDF のスパンへ自動的に伝播し、Connect 呼び出しは呼び出し元のトレースに参加します。
パフォーマンス
「パフォーマンス」という見出しのセクションインストルメンテーションのオーバーヘッドは、PDF 生成時間に比べてごく小さいものです。フロントマターのバジェットは保証ではなく、ドキュメント上の上限です。リクエストレートが高い場合は、ヘッドベースまたはコレクター側のサンプリングを使用して、エクスポート量とコストを抑えてください。
セキュリティに関する注意
「セキュリティに関する注意」という見出しのセクション安全なテレメトリーとログのスクラビング
「安全なテレメトリーとログのスクラビング」という見出しのセクションNextPDF は、迂回できない厳格なテレメトリーデータポリシーを強制します。固定の属性許可リストは、構造的なメタデータとパフォーマンスメトリクスのみをエクスポートします。具体的には、ページ数、フォント数、画像数、ファイルサイズ、出力プロファイル名、ブール値フラグ、所要時間、メモリ、バージョンおよびティアの識別子です。ドキュメントの内容、ファイルパス、生のストリームバイト、base64 ペイロード、個人データ、認証情報は決してエクスポートされません。許可リストにない属性はすべて破棄され、キー自体が許可されている場合でも、ペイロードのパターンに一致する値も破棄されます。この性質により、ドキュメントデータを漏らすことなく、トレースを共有の可観測性パイプラインに流せます。これはライブラリの振る舞いであって、トレースを受信するバックエンドに関するデプロイメントレベルの保証ではありません。
| 主張 | 条項 | reference_id |
|---|---|---|
| トランスポートの失敗が、PSR-18 のクライアント例外となる唯一のケース | PSR-18 §4 | |
| 4xx/5xx のレスポンスは通常の戻り値であり、例外ではない | PSR-18 §4 |
OpenTelemetry プロトコルと W3C Trace Context フォーマットは外部仕様であり、それぞれの団体によって維持管理されています。このページはそれらへの適合を主張せず、本文を再掲することもしません。正式な定義は、公開された OpenTelemetry 仕様（https://opentelemetry.io/docs/specs/otel/）および W3C Trace Context 勧告（https://www.w3.org/TR/trace-context/）に存在します。
商用コンテキスト
「商用コンテキスト」という見出しのセクション該当なし。インストルメンテーションはコア機能であり、ゲートされません。
Connect 固有の事項
「Connect 固有の事項」という見出しのセクショントランスポートの可用性（MCP / REST / gRPC）
「トランスポートの可用性（MCP / REST / gRPC）」という見出しのセクションインストルメンテーションはトランスポート非依存です。どのトランスポートで実行される Connect 呼び出しも同じビルドライフサイクルのスパンを生成し、ホストがトランスポート層をインストルメント化している場合、トランスポートはそれを囲む独自のスパンを追加します。
HITL リスクティア
「HITL リスクティア」という見出しのセクション可観測性はリスクモデルと直交します。テレメトリーの発行はツールのリスクレベルを変更せず、ConfirmationGate によってゲートされることも決してありません。
確認ゲートの JSON エンベロープ
「確認ゲートの JSON エンベロープ」という見出しのセクション該当なし。テレメトリーの発行はツールの呼び出しではないため、ゲートを通過しません。
- /connect/tool-catalog/：観測対象となるツールサーフェス。
- /transports/mcp/ / /transports/rest/ / /transports/grpc/：トレース対象の Connect 呼び出しが到達しうるトランスポート。