> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 可観測性スタックへのテレメトリプッシュ
> OpenTelemetry プロトコルで Dify の指標、トークン消費、ユーザー行動を自社の可観測性スタックにプッシュする
アプリケーション指標、トークン消費、ユーザー行動などのデータを、自社の監視システム、BI プラットフォーム、データウェアハウスにストリーミングできます。転送には OpenTelemetry（OTel）オープン標準を使用します。
ワークスペースを横断してデータを集約すると、運用分析、コスト配分、コンプライアンスレポートに活用できます。
設定は、エンタープライズ ダッシュボードのサイドバーにある **データプッシュ** から行います。エクスポートされる各シグナルのフィールド定義は [データプッシュデータ辞書](/ja/3.13.x/administer/data-push-data-dictionary) を参照してください。
## 事前準備
* Dify デプロイメントから到達できる OpenTelemetry Collector。選択する転送方式に対応する OTLP レシーバーを有効にしておきます（慣例として HTTP は `4318`、gRPC は `4317`）。出口接続は、プラットフォーム管理の Dify Enterprise Collector から発信されます。
* エンタープライズ ダッシュボードへのアクセス権限。
## プッシュされるデータ
| シグナル | カバレッジ | 回答できる質問の例 |
| :- | :- | :- |
| **Metrics** | リクエスト数、エラー率、トークン消費、レイテンシ分布、フィードバック数、検索数、アプリケーションライフサイクル | 使用量はどのように増加しているか？障害率は異常か？どのアプリケーションのコストが最も高いか？ |
| **Traces** | `dify.workflow.run`、`dify.node.execution`、`dify.node.execution.draft` | なぜワークフローが遅くなったか？どのノードがレイテンシのボトルネックか？どこでエラーが発生したか？ |
| **Logs**（独立パイプライン） | メッセージ実行、ツール呼び出し、コンテンツモデレーション、ナレッジ検索、提案質問、プロンプト生成の詳細 | 特定のビジネス操作の入力、出力、コンテキストは何か？ |
データプッシュが OTLP で送信するのは Metrics と Traces です。Logs はプッシュされません。構造化イベントログは JSON として API/Worker Pod の標準出力に書き込まれます。
検索するには、Promtail、Fluent Bit、Vector などのログコレクターを別途導入し、Loki または OpenSearch に取り込みます。このログパイプラインは、本ページで設定する OTel Collector とは別系統です。
## 接続の設定
1. エンタープライズ ダッシュボードのサイドバーで **データプッシュ** を開きます。
2. 右上の **パラメータ設定** をクリックし、設定ダイアログを開きます。
3. **設定モード** を選択します。**統一設定** は Metrics と Traces を同じエンドポイントにプッシュします（OTel Collector の使用時に推奨）。**個別設定** は **Traces** と **Metrics** のタブで個別に設定します。
4. 接続パラメータを入力します：
* **Endpoint URL**：OpenTelemetry Collector のアドレス。スキームは `http://`、`https://`、`grpc://`、`grpcs://` のいずれかです（例：`http://otel-collector:4318`）。`https://` または `grpcs://` のエンドポイントで TLS が有効になります。スキームは転送形式を決めません。**Transport Protocol** を Collector のレシーバーに合わせて選択します。
* **Transport Protocol**：`http/protobuf`（推奨）、`grpc`（高スループット、安定した内部ネットワーク向け）、`http/json`（デバッグ専用）。
* **Compression**：`gzip`（推奨）または `none`。
* **Timeout**：プッシュタイムアウト。秒単位の時間表記で入力します（例：`5s`）。
* **Headers**：認証などに使うキーと値のペア（例：`Authorization: Bearer `）。**Header を追加** で行を追加します。
* **詳細設定**（TLS エンドポイント向け）：**Certificate File (CA)** をアップロードします。Collector のサーバー証明書を発行した CA の証明書です（自己署名証明書の場合は自社の CA、公的 CA が発行した証明書の場合は Let's Encrypt のルート証明書などの発行元 CA 証明書）。**証明書検証をスキップ** を有効にした場合のみ省略できます（本番環境ではスキップは非推奨）。**相互 TLS (mTLS)** では **Client Key File** と **Client Certificate File** もアップロードします。
5. **接続テスト** をクリックします。接続を検証し、失敗の理由（到達不能なホスト、無効な証明書など）を報告します。
6. **設定を保存** をクリックし、確認ダイアログで **再起動して適用** をクリックします。稼働中に保存するとプッシュサービスが再起動し、データ転送が一時的に中断される可能性があります。
本番環境では TLS エンドポイントを使用し、認証ヘッダーを設定します。
## プッシュサービスの開始と停止
* **開始**：停止中の場合、**接続してデータをプッシュ** をクリックして確認します。ステータスが **サービス稼働中** に変わります。
* **停止**：稼働中の場合、**プッシュサービスを停止** をクリックして確認します。ステータスが **サービス停止** に変わり、データ転送は中断されます。
## セットアップの確認
以下のチェックは、Collector が指標を Prometheus に、トレースを Jaeger にルーティング済みであることが前提です。クエリ結果が空の場合、まずこのルーティングを確認してください。Prometheus の指標名はアンダースコア形式です（`dify.requests.total` は `dify_requests_total`）。
1. **データプッシュ設定** ページで、ステータスが **サービス稼働中** と表示されることを確認します。
2. 公開済みのワークフローを実行し、`dify_requests_total{type="workflow"}` が Prometheus でクエリできることを確認します。
3. マルチノードのワークフローを実行し、完全な `dify.workflow.run` と `dify.node.execution` のトレースが Jaeger で確認できることを確認します。
4. Studio（Dify のアプリ構築画面）でワークフローをデバッグします。Prometheus では `dify_requests_total{type="draft_node"}` を、Jaeger では `dify.node.execution.draft` スパン名を確認します。
5. ツール呼び出し、ナレッジ検索、コンテンツモデレーションのイベントがログプラットフォームに正しく表示されることを確認します。「プッシュされるデータ」の標準出力ログパイプラインが前提です。
6. コンテンツプッシュが無効（デフォルト。「Input/Output コンテンツの制御」を参照）の状態で、機密フィールドが `ref:{id_type}={uuid}` に置き換えられることを確認します。対象フィールドは [データプッシュデータ辞書](/ja/3.13.x/administer/data-push-data-dictionary) を参照してください。
Trace プラットフォームの Operation Name ドロップダウンに表示されるのは、受信済みのスパン名のみです。製品がサポートするすべてのスパン名が事前に表示されるわけではありません。
## プッシュサービスの監視
**データプッシュ設定** ページ（サイドバーの **データプッシュ** で開くページ）には、デフォルトでリアルタイムのサービスステータスが表示されます。
**ステータス 1：サービス停止**
* ページに「未接続、パラメータを設定して接続してください。」と表示されます。
* 右側の **接続してデータをプッシュ** をクリックして接続するか、右上の **パラメータ設定** をクリックして設定を開始します。
**ステータス 2：サービス稼働中**
ページに以下が表示されます：
* **ステータスインジケーター**：緑色のライト + **サービス稼働中**。
* **接続開始時刻**：現在の接続の開始時刻（YYYY-MM-DD HH:mm:ss）。
* **データ統計**：**プッシュ済みデータ量**（リアルタイム、MB/GB）と **未プッシュまたはバッファデータ量**。
* **最近のデータプッシュログ**：OpenTelemetry から報告された例外やネットワークエラーのログ。
**ステータス 3：サービスエラー**
* **ステータスインジケーター**：オレンジ色のライト + **サービスエラー**。**最近のデータプッシュログ** を確認して例外を修正し、データ損失を回避してください。
プッシュは非同期メカニズムを使用しており、**メインリクエストパスに影響しません**。プッシュの失敗や接続の切断時、データは FIFO バッファに保持され、接続回復後に転送されます。内蔵 Span キューの容量は **2,048 Span** で、5 秒ごとにバッチでフラッシュされます。バッファが満杯になると、最新のデータが破棄されます。Metrics と構造化イベントログは独立したパスを使用し、このキュー容量の制限を受けません。
ページには、データ損失につながるシナリオが表示されます：プッシュサービスのエラー、下流の処理遅延によるバッファオーバーフロー、サービスの再起動。
ステータスとログはここで定期的に確認します。あわせて、自社の Collector サイドでアラート（接続の切断、バックログのしきい値超過など）を設定してください。
## Input/Output コンテンツの制御
Input/Output コンテンツを含めるかどうかは、Dify API サービスの環境変数 `ENTERPRISE_INCLUDE_CONTENT` で制御します（デフォルト `false`）。変更は再デプロイ後に有効になります。[環境変数リファレンス](/ja/3.13.x/deploy/advanced-configuration/environment-variables) を参照してください。
* **無効（デフォルト）**：コンテンツフィールドは `ref:{id_type}={uuid}` 形式の参照文字列に置き換えられます。Message ID、ユーザー ID、アプリケーション ID などのメタデータは引き続きプッシュされます。参照文字列の UUID を使い、Dify データベースで対応するレコード（ワークフロー実行、メッセージなど）を照会できます。
* **有効**：リクエストの入力とモデルの出力がエクスポートデータに含まれます。
厳格なデータプライバシー要件がある環境では、コンテンツプッシュを無効のままにします。
## 本番環境の計画
### アーキテクチャと責任境界
以下の図は、Dify Enterprise テレメトリエンジンと自社の可観測性スタックの接続方法と責任境界を示しています：
```text theme={null}
Dify API/Worker
↓ OTLP gRPC（非同期、内蔵バッファ）
Dify Enterprise Collector（プラットフォーム管理、受信と転送）
↓ OTLP（カスタマーが設定したエンドポイント）
カスタマー OTel Collector（カスタマー管理）
├──► Prometheus（/metrics をスクレイプ）→ Grafana
└──► Jaeger / Tempo（Traces）
Dify API/Worker 標準出力（JSON イベントログ）
└──► 独自のログコレクター（Promtail / Fluent Bit / Vector）──► Loki / OpenSearch
```
1. **Dify API** はビジネス指標、トレース、イベントを生成します。これらはまず内部バッファに書き込まれ、OTel SDK によって非同期に転送されます。
2. **Dify Enterprise Collector** は OTLP gRPC でデータを受信し、バッチと集約プロセッサを適用します。あわせて、プッシュサービスのランタイムステータス（接続時間、プッシュバイト数など）を Enterprise DB に書き込みます。エンタープライズ ダッシュボードはこのステータスを表示します。
3. その **Exporter** はデータをカスタマー提供の OpenTelemetry Collector に送信します。宛先エンドポイント、プロトコル、TLS、認証はデータプッシュ設定によって決定されます。
4. カスタマー Collector はデータを Prometheus/Thanos や Jaeger/Tempo などのバックエンドにルーティングします。Grafana またはエンタープライズ BI ツールがこれらのバックエンドからデータをクエリして可視化します。
**責任境界**：Dify 内部のバッファ、OTel SDK、Enterprise Collector プロセッサ、Enterprise DB の変更は不要です。
自社側では、出口 Collector、バックエンドストレージ、クエリと可視化、アラート、アクセス制御、データ保持ポリシーを計画します。
### Collector のサイジング
まず 1 日あたりのデータ量を見積もります：
```text theme={null}
1 日あたりの Trace 量
≈ 本番ワークフロー実行数 + 本番ノード実行数 + ドラフトノード実行数
1 日あたりのビジネスイベント量
≈ メッセージ数 + ツール呼び出し数 + モデレーションチェック数 + 検索数
+ 提案質問生成数 + 会話名生成数 + プロンプト生成数 + フィードバックイベント数
```
以下のサイジング目標は、Dify Enterprise Collector ではなく、**カスタマーサイドの OTel Collector** に適用されます。
| 同時接続規模 | 推奨カスタマー Collector 構成 | 主要な考慮事項 |
| :- | :- | :- |
| POC / 小規模本番 | 1 レプリカ（2 vCPU、4 GB） | 出口エンドポイント、データルーティング、ダッシュボードの整合性を検証します。 |
| 部門規模の本番 | 2 レプリカ（4 vCPU、8 GB）、HA フェイルオーバーあり | ピークキューの深さ、エクスポートタイムアウト、ローリングアップグレード時の確実な復旧。 |
| エンタープライズ高同時接続 | Kafka/RabbitMQ メッセージバッファリングを使用した水平スケールクラスター | パーティションルーティング、レート制限、クロスリージョンフェイルオーバー、永続キュー。 |
高同時接続のデプロイメントでは `grpc` プロトコルを優先します。Collector のリソースも十分に確保してください。下流の消費が追いつかないと、プラットフォーム側のバッファオーバーフローとデータ損失につながります。
同時実行のしきい値は、Workflow の複雑さ、ノード数、メッセージ頻度によって大きく異なります。上記の仕様は開始時の目安として扱い、導入前に実際のピークトラフィックを使った負荷テストで検証してください。
### データ保持
以下は、自社の可観測性プラットフォームの推奨開始保持期間です（Dify はストレージを管理しません。ストレージコストは自社で計画します）：
* Metrics：最初は 15〜30 日。トレンド分析には 90 日以上に延長できます。
* Traces：最初は 3〜7 日。
## トラブルシューティング
* **OpenTelemetry Collector に接続できない**：Endpoint URL が正しく、ネットワークが到達可能であることを確認します。TLS エンドポイントの場合、CA 証明書、クライアントキー、クライアント証明書が有効で正しい形式であることを確認します。**接続テスト** で具体的なエラーを確認します。
* **データプッシュが中断される**：**最近のデータプッシュログ** でネットワークの不安定さや Collector のエラーを確認します。Collector が稼働中で、受信上限に達していないことを確認します。
* **バックログが増え続ける**：Collector の消費速度がデータの到着に追いつかないか、ネットワークレイテンシが高いことが原因です。バックログはバッファに保持され、接続回復後に転送されます。バッファが満杯になると新しいデータが破棄されます。Collector のリソースを増やすか、スケールアウトします。
* **設定の保存に失敗する**：必須フィールドがすべて入力されていることを確認します。TLS エンドポイントの場合、証明書ファイルが正常にアップロードされていることを確認します。
* **データ損失**：サービスエラー、バッファオーバーフロー、システム再起動時に発生する可能性があります。メインリクエストパスを保護する意図的なデグレードです。許容できない場合は、Collector の処理能力を高めて継続的なバックログを避けてください。