Datadog パートナー向けログインテグレーションガイドライン

概要

このガイドでは、Datadog パートナーがパートナーログインテグレーションを作成する方法について、次のステップを説明します。

  1. Datadog にログを送信する
  2. Datadog パートナーアカウントでログインテグレーションアセットを設定する
  3. インテグレーションのレビューとデプロイメント

ログを Datadog に送信する方法

ログ取り込み HTTP エンドポイントを使用して、Datadog にログを送信します。エンドポイントの詳細については、Send Logs API ドキュメントを参照してください。

以下は、インテグレーションを構築するためのガイドラインです。

  1. source と service タグは小文字で記述する必要があります。

  2. source タグにインテグレーション名を設定します。

     Datadog では、source タグを <integration_name> に設定し、service タグをテレメトリーを生成するサービスの名前に設定することを推奨しています。例えば、service タグは製品ラインによってログを区別するために使用することができます。

     異なるサービスが存在しない場合は、service に source と同じ値を設定します。source と service のタグは、インテグレーションパイプラインとダッシュボードを有効にするために使用されるので、ユーザーが編集できないようにする必要があります。タグはペイロードで設定するか、クエリパラメーターで設定することができます。例: ?ddsource=example&service=example

  3. インテグレーションは、すべての Datadog サイトをサポートする必要があります。

    ユーザーは、該当する場合はいつでも異なる Datadog サイトを選択できるようにする必要があります。サイトの違いについては、Datadog サイトの概要を参照してください。各サイトのエンドポイントは以下の通りです。

    サイトHTTP エンドポイント
    US1http-intake.logs.datadoghq.com
    US3http-intake.logs.us3.datadoghq.com
    US5http-intake.logs.us5.datadoghq.com
    US1-FEDhttp-intake.logs.ddog-gov.datadoghq.com
    EU1http-intake.logs.datadoghq.eu

  4. インテグレーションを設定する際に、ユーザーがカスタムタグをアタッチできるようにします。

     Datadog は、手動ユーザータグを JSON 本文の key-value 属性として送信することを推奨しています。ログに手動タグを追加できない場合は、ddtags=<TAGS> クエリパラメーターを使用してタグを送信することができます。例については、Send Logs API ドキュメントを参照してください。

  5. JSON 本文には可能な限り配列を入れずにデータを送信します。

    一部のデータをタグとして送信することは可能ですが、Datadog では、データを JSON 本文で送信し、配列を避けることを推奨しています。これにより、Datadog ログプラットフォーム内のデータに対して、ユーザーが実行できる演算子がより柔軟になります。

  6. Datadog API キーをログに記録しません。

    Datadog API キーは、ヘッダーで渡すか、HTTP パスの一部として渡すことができます。例については、Send Logs API ドキュメントを参照してください。Datadog は、セットアップで API キーをログに記録しないメソッドを使用することを推奨しています。

  7. Datadog アプリケーションキーを使用しません。

    Datadog アプリケーションキーは、API キーとは異なり、HTTP エンドポイントを使用してログを送信するためには必要ありません。

Datadog パートナーアカウントでログインテグレーションアセットを設定する

ログパイプラインの設定

Datadog に送信されたログは、ログパイプラインで処理され、検索や分析がしやすいように標準化されます。パイプラインを設定するには、

  1. ログパイプラインに移動します。
  2. Add a new pipeline をクリックします。
  3. Filter フィールドに、パートナーログのログソースを定義する一意の source を入力します。例えば、Okta インテグレーションでは、source:okta となります。注: インテグレーションを通じて送信されるログは、Datadog に送信される前に正しいソースタグでタグ付けされていることを確認してください。
  4. オプションで、タグと説明を追加します。
  5. 作成をクリックします。

パイプラインの中で、データを再構築し、属性を生成するプロセッサーを追加することができます。例:

  • 日付リマッパーを使用して、ログの正式なタイムスタンプを定義します。
  • 属性リマッパーを使用して、属性キーを Datadog 標準属性にリマップします。例えば、クライアント IP を含む属性キーは、Datadog がすぐに使えるダッシュボードでパートナーログを表示できるように、network.client.ip にリマップする必要があります。
  • サービスリマッパーを使って、service 属性をリマップするか、source 属性と同じ値に設定します。
  • grok プロセッサーを使用して、ログ内の値を抽出し、検索や分析に役立てることができます。
  • メッセージリマッパーを使って、ログの公式メッセージを定義し、特定の属性を全文検索できるようにします。

詳細と全ログプロセッサーの一覧は、プロセッサーを参照してください。

ログエクスプローラーにファセットを設定する

顧客がログの検索や分析に使用する可能性のあるフィールドは、すべてファセットとして追加する必要があります。ファセットは、ダッシュボードでも使用されます。

ファセットには 2 種類あります。

  • ファセットは、相対的な洞察を得たり、一意の値をカウントするために使用されます。
  • メジャーは、ある範囲での検索に使用されるファセットの一種です。 例えば、レイテンシー期間のメジャーを追加すると、特定のレイテンシー以上のすべてのログを検索することができます。注: メジャーファセットの単位は、属性が何を表すかに基づいて定義されます。

新しいファセットまたはメジャーを追加するには

  1. ファセットまたはメジャーを追加したい属性を含むログをクリックします。
  2. ログパネルで、属性の横にある歯車をクリックします。
  3. Create facet/measure for @attribute を選択します。
  4. メジャーの場合、単位を定義するには、Advanced options をクリックします。属性が表すものに基づいて、単位を選択します。
  5. Add をクリックします。

ファセットリストを簡単に移動できるように、類似のファセットをグループ化します。インテグレーションログに固有のフィールドについては、source タグと同じ名前のグループを作成します。

  1. ログパネルで、新しいグループに入れたい属性の横にある歯車をクリックします。
  2. Edit facet/measure for @attribute を選択します。属性のファセットがまだ存在しない場合は、Create facet/measure for @attribute を選択します。
  3. Advanced options をクリックします。
  4. Group フィールドに、新しいグループの名前を入力し、New group を選択します。
  5. Update をクリックします。

詳しくは、ログファセットドキュメントをご覧ください。

Datadog の標準的な属性で、特定のグループに属するものについては、デフォルト標準属性リストを参照してください。

インテグレーションのレビューとデプロイメント

Datadog は、パートナーのインテグレーションをレビューし、パートナーにフィードバックを提供します。一方、パートナーはレビューし、それに応じて変更を加えます。このレビュープロセスは、メールで行われます。

レビューが完了すると、Datadog は新しいログインテグレーションアセットを作成し、デプロイします。