概要

Observability Pipelines の Google Pub/Sub 送信先を使用してログを Google Pub/Sub メッセージングシステムに公開し、ログを下流のサービス、データレイク、またはカスタムアプリケーションに送信できるようにします。

この送信先を使用する場合

この送信先を使用する一般的なシナリオは以下のとおりです。

• 分析パイプラインの場合: ログを下流の Google BigQuery、データレイク、またはカスタム機械学習ワークフローにルーティングします。
• イベント駆動型処理の場合: ログを Pub/Sub トピックに公開して、Google Cloud Functions、Cloud Run functions、および Dataflow ジョブがログデータに基づいてリアルタイムでアクションを実行できるようにします。

前提条件

この送信先を設定する前に以下が必要です。

• Pub/Sub サブスクリプション: Pub/Sub トピックと、メッセージを消費するサブスクリプションを少なくとも 1 つ作成します。
• 認証: 標準の Google Cloud 認証方法を設定します。以下のオプションがあります。
  • サービスアカウントキー (JSON ファイル)
  • Workload Identity (Google Kubernetes Engine (GKE))
• IAM ロール:
  • roles/pubsub.publisher は、イベントを公開するために必要です。
  • roles/pubsub.viewerは、ヘルスチェックに推奨されます。
    • このロールがない場合、エラー Healthcheck endpoint forbidden がログに記録されますが、Worker は通常通り処理を続行します。
  • 詳細については、利用可能な Pub/Sub のロールを参照してください。

Worker 用のサービスアカウントを設定する

Google Cloud のサービスアカウントは、アプリケーションやサービスのみが使用するアカウントの一種です。

• 独自の ID と認証情報 (JSON キーファイル) を持っています。
• 特定のリソースにアクセスできるように IAM ロールを割り当てます。
• この場合、Observability Pipelines Worker はサービスアカウントを使用して、ユーザーに代わって認証を行い、Pub/Sub にログを送信します。

サービスアカウントを使用して認証するには:

1. Google Cloud コンソールで、[IAM と管理] > [サービスアカウント] に移動します。
2. [+ サービスアカウントを作成] をクリックします。
3. 名前を入力し、[作成して続行] をクリックします。
4. ロールを割り当てます。
   • Pub/Sub パブリッシャー
   • Pub/Sub 閲覧者
5. [完了] をクリックします。

認証方法

適切なロールを持つサービスアカウントを作成した後、以下のいずれかの認証方法を設定します。

オプション A: Workload Identity の方法 (GKE の場合、推奨)

1. サービスアカウントを Kubernetes サービスアカウント (KSA) にバインドします。
2. その KSA がサービスアカウントになりすますことを許可します。
3. 使用するサービスアカウントを GKE が認識できるように、KSA にアノテーションを付けます。
4. 認証は、GCP のメタデータサーバーから行われます。

オプション B: GSA を VM に直接アタッチする (Google Compute Engine の場合)

Observability Pipelines Worker を Google Compute Engine (GCE) VM 上で実行している場合は、この認証方法を使用してください。

• VM を作成または編集する際に、[ID と API へのアクセス] > [サービスアカウント] で Google サービスアカウントを指定します。

オプション C: GSA としてサービスを実行する (Cloud Run または Cloud Functions の場合)

Worker を Cloud Run サービスまたは Cloud Function としてデプロイする場合は、この認証方法を使用してください。

• Cloud Run または Cloud Functions のデプロイ設定で、作成した Google サービスアカウントを [実行サービスアカウント] に設定します。

オプションD: JSON キーの方法 (ID バインディングのない環境)

1. 新しいサービスアカウントを開き、[キー] > [キーを追加] > [新しいキーを作成] に移動します。
2. JSON 形式を選択します。
3. ダウンロードした JSON ファイルを安全な場所に保存します。
4. Worker をインストールした後、その JSON ファイルを DD_OP_DATA_DIR/config/ にコピーまたはマウントします。 Pipelines UI で送信先を設定する際に、Google Pub/Sub 送信先の [Credentials path] (認証情報パス) フィールドでこのファイルを参照します。

セットアップ

パイプラインをセットアップする際に、Google Pub/Sub 送信先を設定します。パイプラインは、UI、API、または Terraform を使用してセットアップできます。このセクションの手順では、UI で設定します。

パイプラインの UI で Google Pub/Sub 送信先を選択した後:

1. 送信先プロジェクト名を入力します。
   • これは、Pub/Sub トピックが存在する GCP プロジェクトです。
2. トピックを入力します。
   • これは、ログの公開先となる Pub/Sub トピックです。
3. [Encoding] (エンコーディング) ドロップダウンメニューで、パイプラインの出力を [JSON] または [Raw message] (生のメッセージ) のどちらでエンコードするかを選択します。
   • JSON: ログは JSON として構造化されます (ダウンストリームツールで構造化データが必要な場合に推奨)。
   • Raw: ログは生の文字列として送信されます (元の形式が保持されます)。
4. 認証情報 JSON ファイルがある場合は、その認証情報 JSON ファイルへのパスを入力します。
   • サービスアカウント JSON を使用している場合は、パス DD_OP_DATA_DIR/config/<your-service-account>.json を入力します。
   • または、GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定します。
   • GKE で Workload Identity を使用している場合、認証情報は自動的に管理されます。

オプション設定

Enable TLS (TLS を有効にする)

Toggle the switch to Enable TLS.

• If you are using Secrets Management, enter the identifier for the key pass. See Secret defaults for the default used if the field is left blank.
• Enter the following certificate and key files:
  • Server Certificate Path: The path to the certificate file that has been signed by your Certificate Authority (CA) root file in DER, PEM, or CRT (X.509).
  • (Optional) CA Certificate Path: The path to the certificate file that is your Certificate Authority (CA) root file in DER, PEM, or CRT (X.509).
  • (Optional) Private Key Path: The path to the .key private key file that belongs to your Server Certificate Path in DER, PEM, or CRT (PKCS #8) format.
  • Notes:
    • The configuration data directory /var/lib/observability-pipelines-worker/config/ is automatically appended to the file paths. See Advanced Worker Configurations for more information.
    • The file must be readable by the observability-pipelines-worker group and user.

バッファリング

Toggle the switch to enable Buffering Options. Enable a configurable buffer on your destination to ensure intermittent latency or an outage at the destination doesn’t create immediate backpressure, and allow events to continue to be ingested from your source. Disk buffers can also increase pipeline durability by writing data to disk, ensuring buffered data persists through a Worker restart. See Destination buffers for more information.

• If left unconfigured, your destination uses a memory buffer with a capacity of 500 events.
• To configure a buffer on your destination:
  1. Select the buffer type you want to set (Memory or Disk).
  2. Enter the buffer size and select the unit.
     1. Maximum memory buffer size is 128 GB.
     2. Maximum disk buffer size is 5 TB.
        • Note: For Worker versions 2.20.x and older, the maximum disk buffer size is 500 GB.
  3. In the Behavior on full buffer dropdown menu, select whether you want to block events or drop new events when the buffer is full.

シークレットのデフォルト値

These are the defaults used for secret identifiers and environment variables.

• (オプション) Google Pub/Sub エンドポイント URL の識別子:
  • デフォルトでは、Worker はデータをグローバルエンドポイント (https://pubsub.googleapis.com) に送信します。
  • Pub/Sub トピックがリージョン固有の場合は、Google Pub/Sub の代替エンドポイント URL をリージョンエンドポイントで構成してください。詳細については、About Pub/Sub endpoints を参照してください。設定したエンドポイント URL をシークレットマネージャーに入力します。
  • デフォルトの識別子は DESTINATION_GCP_PUBSUB_ENDPOINT_URL です。
• Google Pub/Sub TLS パスフレーズの識別子 (TLS が有効な場合):
  • デフォルトの識別子は DESTINATION_GCP_PUBSUB_KEY_PASS です。

オプションの代替 Pub/Sub エンドポイント

By default the Worker sends data to the global endpoint: https://pubsub.googleapis.com.

If your Pub/Sub topic is region-specific, configure the Google Pub/Sub alternative endpoint URL with the regional endpoint. See About Pub/Sub endpoints for more information.

The default environment variable is DD_OP_DESTINATION_GCP_PUBSUB_ENDPOINT_URL.

TLS (when enabled)

• Google Pub/Sub TLS passphrase:
  • The default environment variable is DD_OP_DESTINATION_GCP_PUBSUB_KEY_PASS.

トラブルシューティング

一般的な問題と解決策:

• ヘルスチェックが禁止されています
  • roles/pubsub.viewer IAM ロールを確認してください。
• 権限がありません
  • サービスアカウントに roles/pubsub.publisher があることを確認してください。
• 認証エラー
  • 認証情報 JSON のパスまたは GKE Workload Identity の設定を確認してください。
• ドロップされたイベント
  • pipelines.component_discarded_events_total および pipelines.buffer_discarded_events_total のメトリクスをチェックしてください。
  • 問題を解決するために、必要に応じてバッファサイズを増やすか、誤って設定されたフィルターを修正してください。
• 高レイテンシ
  • バッファサイズとタイムアウトを減らすか、Worker をスケールしてください。
• ログが届いていません
  • Google Pub/Sub 送信先の設定で、トピック名、プロジェクト、Pub/Sub エンドポイント (グローバルかリージョンか) を再確認してください。

ヘルスメトリクス

すべての送信先から出力されるコンポーネントメトリクスおよび送信先バッファメトリクスについては、パイプライン使用状況メトリクスのドキュメントを参照してください。Google Pub/Sub 送信先のメトリクスでフィルタリングまたはグループ化するには、タグ component_type:gcp_pubsub を使用します。

イベントバッチ処理

イベントのバッチは、これらのパラメーターのいずれかが満たされたときにフラッシュされます。詳細については、送信先のイベントのバッチ処理を参照してください。