可観測性スタックへのテレメトリプッシュ

​

事前準備

• Dify デプロイメントから到達できる OpenTelemetry Collector。選択する転送方式に対応する OTLP レシーバーを有効にしておきます（慣例として HTTP は 4318、gRPC は 4317）。出口接続は、プラットフォーム管理の Dify Enterprise 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 <token>）。Header を追加 で行を追加します。
   • 詳細設定（TLS エンドポイント向け）：Certificate File (CA) をアップロードします。Collector のサーバー証明書を発行した CA の証明書です（自己署名証明書の場合は自社の CA、公的 CA が発行した証明書の場合は Let’s Encrypt のルート証明書などの発行元 CA 証明書）。証明書検証をスキップ を有効にした場合のみ省略できます（本番環境ではスキップは非推奨）。相互 TLS (mTLS) では Client Key File と Client Certificate File もアップロードします。
5. 接続テスト をクリックします。接続を検証し、失敗の理由（到達不能なホスト、無効な証明書など）を報告します。
6. 設定を保存 をクリックし、確認ダイアログで 再起動して適用 をクリックします。稼働中に保存するとプッシュサービスが再起動し、データ転送が一時的に中断される可能性があります。

​

プッシュサービスの開始と停止

• 開始：停止中の場合、接続してデータをプッシュ をクリックして確認します。ステータスが サービス稼働中 に変わります。
• 停止：稼働中の場合、プッシュサービスを停止 をクリックして確認します。ステータスが サービス停止 に変わり、データ転送は中断されます。

​

セットアップの確認

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} に置き換えられることを確認します。対象フィールドは データプッシュデータ辞書 を参照してください。

​

プッシュサービスの監視

• ページに「未接続、パラメータを設定して接続してください。」と表示されます。
• 右側の 接続してデータをプッシュ をクリックして接続するか、右上の パラメータ設定 をクリックして設定を開始します。

• ステータスインジケーター：緑色のライト + サービス稼働中。
• 接続開始時刻：現在の接続の開始時刻（YYYY-MM-DD HH:mm:ss）。
• データ統計：プッシュ済みデータ量（リアルタイム、MB/GB）と 未プッシュまたはバッファデータ量。
• 最近のデータプッシュログ：OpenTelemetry から報告された例外やネットワークエラーのログ。

• ステータスインジケーター：オレンジ色のライト + サービスエラー。最近のデータプッシュログ を確認して例外を修正し、データ損失を回避してください。

​

Input/Output コンテンツの制御

• 無効（デフォルト）：コンテンツフィールドは ref:{id_type}={uuid} 形式の参照文字列に置き換えられます。Message ID、ユーザー ID、アプリケーション ID などのメタデータは引き続きプッシュされます。参照文字列の UUID を使い、Dify データベースで対応するレコード（ワークフロー実行、メッセージなど）を照会できます。
• 有効：リクエストの入力とモデルの出力がエクスポートデータに含まれます。

​

本番環境の計画

​

アーキテクチャと責任境界

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 ツールがこれらのバックエンドからデータをクエリして可視化します。

​

Collector のサイジング

1 日あたりの Trace 量
≈ 本番ワークフロー実行数 + 本番ノード実行数 + ドラフトノード実行数

1 日あたりのビジネスイベント量
≈ メッセージ数 + ツール呼び出し数 + モデレーションチェック数 + 検索数
  + 提案質問生成数 + 会話名生成数 + プロンプト生成数 + フィードバックイベント数

​

データ保持

• Metrics：最初は 15〜30 日。トレンド分析には 90 日以上に延長できます。
• Traces：最初は 3〜7 日。

​

トラブルシューティング

• OpenTelemetry Collector に接続できない：Endpoint URL が正しく、ネットワークが到達可能であることを確認します。TLS エンドポイントの場合、CA 証明書、クライアントキー、クライアント証明書が有効で正しい形式であることを確認します。接続テスト で具体的なエラーを確認します。
• データプッシュが中断される：最近のデータプッシュログ でネットワークの不安定さや Collector のエラーを確認します。Collector が稼働中で、受信上限に達していないことを確認します。
• バックログが増え続ける：Collector の消費速度がデータの到着に追いつかないか、ネットワークレイテンシが高いことが原因です。バックログはバッファに保持され、接続回復後に転送されます。バッファが満杯になると新しいデータが破棄されます。Collector のリソースを増やすか、スケールアウトします。
• 設定の保存に失敗する：必須フィールドがすべて入力されていることを確認します。TLS エンドポイントの場合、証明書ファイルが正常にアップロードされていることを確認します。
• データ損失：サービスエラー、バッファオーバーフロー、システム再起動時に発生する可能性があります。メインリクエストパスを保護する意図的なデグレードです。許容できない場合は、Collector の処理能力を高めて継続的なバックログを避けてください。