概要

このドキュメントで説明しているパイプラインとプロセッサーは、クラウドベースのログ環境に特化しています。オンプレミスのログの集約、処理、ルーティングには、Observability Pipelines を参照してください。

Datadog は自動的に JSON 形式のログをパースします。その後、処理パイプラインを通じて、すべてのログ (生ログおよび JSON) に追加情報を付与できます。パイプラインはさまざまな形式のログを受け取り、それらを Datadog の共通形式に翻訳します。ログパイプラインと処理戦略の実装には、組織への属性命名規則の導入という利点があります。

パイプラインでは、ログはプロセッサーを順番にチェーンしてパースされ、追加情報が付与されます。これにより、半構造化テキストから意味のある情報や属性を抽出し、ファセットとして再利用できます。パイプラインを通過する各ログは、すべてのパイプラインフィルターに対して評価されます。フィルターに一致する場合、次のパイプラインに移動する前に、すべてのプロセッサーが順次適用されます。

パイプラインとプロセッサーは、あらゆる種類のログに適用できます。ログ構成を変更したり、サーバー側の処理ルールの変更をデプロイしたりする必要はありません。すべてはパイプライン構成ページで構成できます。

注: ログ管理ソリューションを最適にご利用いただくため、Datadog では Grok プロセッサー内でパイプラインごとに最大 20 件のプロセッサーおよび 10 個のパース規則を使用することをお勧めします。Datadog はサービスのパフォーマンスに悪影響を与える可能性のあるパース規則、プロセッサー、パイプラインを無効化する権利を有しています。

パイプラインの権限

パイプラインは、きめ細かなアクセス制御を使用して、パイプラインおよびプロセッサー構成を編集できるユーザーを管理します。これは、ロール、個人ユーザー、およびチームに権限を割り当てることができ、パイプラインリソースに対するきめ細かな制御を実現できることを意味します。制限のないパイプラインは無制限と見なされ、logs_write_pipelines 権限を持つすべてのユーザーがパイプラインおよびそのプロセッサーを変更できます。

Datadog におけるパイプライン権限の設定

各パイプラインについて、管理者は次の編集スコープを選択できます。

  • Editor: 指定されたユーザー、チーム、またはロールのみがパイプライン構成およびプロセッサーを編集できます。
  • Processor Editor: 指定されたユーザー、チーム、またはロールのみがプロセッサー (ネストされたパイプラインを含む) を編集できます。誰もパイプラインの属性 (フィルタークエリやグローバルパイプラインリスト内の順序など) を変更できません。
ユーザーにパイプラインの制限リストへのアクセス権を付与しても、自動的に logs_write_pipelines または logs_write_processors 権限が付与されるわけではありません。管理者はこれらの権限を個別に付与する必要があります。

これらの権限は、API および Terraform を通じてプログラムで管理できます。

前処理

JSON ログの前処理は、ログがパイプライン処理に入る前に実行されます。前処理は、timestamp、status、host、service、および message などの予約済み属性に基づいて一連の操作を実行します。JSON ログに異なる属性名がある場合は、前処理を使用してログ属性名を予約済み属性リストの属性名にマッピングします。

JSON ログの前処理には、標準的なログフォワーダーで動作するデフォルト構成が用意されています。この構成を編集して、カスタムまたは特定のログ転送アプローチに適応させるには、以下の手順を実行します。

  1. Datadog の Pipelines に移動し、Preprocessing for JSON logs を選択します。

    注: JSON ログの前処理は、ログ属性の 1 つをログの host として定義する唯一の方法です。

  2. 予約済み属性に基づき、デフォルトのマッピングを変更します。

ソース属性

JSON 形式のログファイルに ddsource 属性が含まれている場合、Datadog はその値をログのソースとして解釈します。Datadog が使用するのと同じソース名を使用するには、インテグレーションパイプラインライブラリを参照してください。

注: コンテナ化環境から取得したログの場合、環境変数を使用してデフォルトのソース値とサービス値をオーバーライドする必要があります。

ホスト属性

Datadog Agent または RFC5424 形式を使用すると、ログのホスト値が自動的に設定されます。ただし、JSON 形式のログファイルに次の属性が含まれている場合、Datadog はその値をログのホストとして解釈します。

  • host
  • hostname
  • syslog.hostname

注: Kubernetes では、Datadog Agent によって取り込まれた JSON ログに host、hostname、または syslog.hostname キー属性が含まれている場合、その値はログのデフォルトの Agent ホスト名をオーバーライドします。その結果、ログは正しいホストに設定されている期待されるホストレベルタグを継承しません。この場合、Datadog はこれらの属性をクリアして、ログが正しいホストに関連付けられるようにすることを推奨します。

日付属性

デフォルトでは、Datadog はタイムスタンプを生成し、ログ受信時に日付属性に追加します。ただし、JSON 形式のログファイルに次のいずれかの属性が含まれている場合、Datadog はその値をログの公式の日付として解釈します。

  • @timestamp
  • timestamp
  • _timestamp
  • Timestamp
  • eventTime
  • date
  • published_date
  • syslog.timestamp

ログ日付リマッパープロセッサーを設定し、別の属性を指定してログの日付のソースとして使用します。

注: ログエントリの正式な日付が 18 時間以上前だった場合、Datadog はそのエントリを拒否します。

認識された日付形式は、ISO8601、UNIX (ミリ秒 EPOCH 形式)、および RFC3164 です。

メッセージ属性

デフォルトでは、Datadog はメッセージ値をログエントリの本文として取り込みます。その値はハイライトされ、ログエクスプローラーに表示され、全文検索用にインデックス化されます。ただし、JSON 形式のログファイルに次のいずれかの属性が含まれている場合、Datadog はその値をログの公式のメッセージとして解釈します。

  • message
  • msg
  • log

ログメッセージリマッパープロセッサーを設定し、別の属性を指定してログのメッセージのソースとして使用します。

ステータス属性

各ログエントリは、Datadog 内でファセット検索に利用可能なステータスレベルを指定できます。ただし、JSON 形式のログファイルに次のいずれかの属性が含まれている場合、Datadog はその値をログの公式のステータスとして解釈します。

  • status
  • severity
  • level
  • syslog.severity

ログステータスリマッパープロセッサーを設定し、別の属性を指定してログのステータスのソースとして使用します。

サービス属性

Datadog Agent または RFC5424 形式を使用すると、ログのサービス値が自動的に設定されます。ただし、JSON 形式のログファイルに次の属性が含まれている場合、Datadog はその値をログのサービスとして解釈します。

  • service
  • syslog.appname
  • dd.service

ログサービスリマッパープロセッサーを設定し、別の属性を指定してログのサービスのソースとして使用します。

トレース ID 属性

デフォルトでは、Datadog SDK はトレース ID とスパン ID をログに自動的に挿入できます。ただし、JSON 形式のログに以下の属性が含まれている場合、Datadog はその値をログの trace_id として解釈します。

  • dd.trace_id
  • contextMap.dd.trace_id
  • named_tags.dd.trace_id
  • trace_id

トレース ID リマッパープロセッサーを設定し、別の属性を指定してログのトレース ID のソースとして使用します。

スパン ID 属性

デフォルトでは、Datadog SDK は スパン ID をログに自動的に挿入できます。ただし、JSON 形式のログに以下の属性が含まれている場合、Datadog はその値をログの span_id として解釈します。

  • dd.span_id
  • contextMap.dd.span_id
  • named_tags.dd.span_id
  • span_id

パイプラインを作成する

  1. Datadog のパイプラインに移動します。

  2. New Pipeline を選択します。

  3. ライブテールプレビューからログを選択してフィルターを適用するか、独自のフィルターを適用します。ドロップダウンメニューからフィルターを選択するか、</> アイコンを選択して独自のフィルタークエリを作成します。フィルターを使用すると、パイプラインを適用するログの種類を制限できます。

    注: パイプラインのフィルタリングは、パイプライン内のプロセッサーより前に適用されます。このため、パイプライン自体で抽出された属性ではフィルタリングできません。

  4. パイプラインに名前を付けます。

  5. (オプション) パイプラインに説明とタグを追加して、目的と所有者を示します。パイプラインタグはログに影響を与えませんが、パイプラインページ内でフィルタリングや検索に使用できます。

  6. Create を押します。

パイプラインによって変換されたログの例:

パイプラインによって変換されたログの例

インテグレーションパイプライン

インテグレーション処理パイプラインは、ログ収集が設定されている特定のソースで利用できます。これらのパイプラインは読み取り専用であり、各ソースに適した方法でログをパースします。インテグレーションログに対しては、インテグレーションパイプラインが自動的にインストールされます。ログをパースし、対応するファセットをログエクスプローラーに追加します。

インテグレーションパイプラインを表示するには、パイプラインページに移動します。インテグレーションパイプラインを編集するには、それをクローンし、そのクローンを編集します。

パイプラインのクローン作成

以下の ELB ログの例を参照してください。

ELB ログの後処理

注: インテグレーションパイプラインは削除できず、無効化のみ可能です。

インテグレーションパイプラインライブラリ

Datadog が提供するインテグレーションパイプラインの完全なリストを表示するには、インテグレーションパイプラインライブラリを参照してください。パイプラインライブラリは、Datadog がデフォルトで異なるログフォーマットをどのように処理するかを示しています。

インテグレーションパイプラインを使用するには、Datadog は対応するログ source を構成してインテグレーションをインストールすることを推奨します。Datadog がこのソースの最初のログを受信すると、インストールが自動的にトリガーされ、インテグレーションパイプラインが処理パイプラインのリストに追加されます。ログソースを構成するには、対応するインテグレーションドキュメントを参照してください。

クローンボタンをクリックしてインテグレーションパイプラインをコピーすることもできます。

プロセッサーまたはネストされたパイプラインを追加する

  1. Datadog のパイプラインに移動します。
  2. パイプラインにカーソルを合わせ、表示される矢印をクリックしてプロセッサーおよびネストされたパイプラインを展開します。
  3. Add Processor または Add Nested Pipeline を選択します。

プロセッサー

プロセッサーはパイプライン内で実行され、データ構造化アクションを完了します。アプリ内または API を使用して、プロセッサーの種類ごとにプロセッサーを追加および構成する方法については、プロセッサーに関するドキュメントを参照してください。

カスタムの日付および時刻の形式と、非 UTC タイムスタンプに必要な timezone パラメーターについては、日付のパースを参照してください。

複数のプロセッサーが一致する場合の属性の優先順位

一致するパイプライン内の複数のプロセッサーが同じ属性を設定する場合、結果はプロセッサーのタイプによって異なります。動作は 3 種類あります。

動作説明プロセッサー
後勝ち後のプロセッサー (順序の後方) によって設定された値が、前の値を上書きします。Grok パーサー、カテゴリプロセッサー、算術プロセッサー、文字列ビルダープロセッサー、ルックアッププロセッサー、URL パーサー、ユーザー Agent パーサー、GeoIP パーサー、デコーダープロセッサー
依存: override_on_conflictoverride_on_conflict パラメーターに従います。デフォルトでは (false)、ターゲット要素がすでに設定されている場合、上書きされません。リマッパー、配列マッププロセッサー
先勝ち最初のプロセッサーのみが適用されます (ログ日付リマッパーを除き、最後のものが使用されます)。単一のパイプライン内では最初のプロセッサーの値が使用され、複数の一致するパイプライン間では最初に検出されたものが適用されます。ログステータスリマッパー、サービスリマッパー、ログメッセージリマッパー、トレースリマッパー、スパンリマッパー

各プロセッサーの詳細については、プロセッサーを参照してください。

ネストされたパイプライン

ネストされたパイプラインは、パイプライン内のパイプラインです。ネストされたパイプラインを使用して、処理を 2 つのステップに分割します。たとえば、最初にチームなどの高レベルフィルターを使用し、次にインテグレーション、サービス、またはその他のタグや属性に基づいて二次フィルタリングを行います。

パイプラインは、ネストされたパイプラインとプロセッサーを持つことができます。一方、ネストされたパイプラインは、プロセッサーしか持つことができません。

ネストされたパイプライン

パイプラインを別のパイプラインに移動して、ネストされたパイプラインにします。

  1. 移動したいパイプラインにカーソルを合わせ、Move to アイコンをクリックします。
  2. 元のパイプラインの移動先となるパイプラインを選択します。注: ネストされたパイプラインを含むパイプラインは、トップレベルの別の位置にのみ移動できます。別のパイプラインに移動することはできません。
  3. Move をクリックします。

パイプラインの変更内容をプレビュー

パイプラインやそのプロセッサーを作成または編集する際、変更を適用する前に、その変更がログにどのような影響を与えるかをプレビューできます。プレビューでは、提案された変更を適用して処理されたログのライブテールが使用されます。

左側にパイプラインのプロセッサー、右側に選択したログの差分が表示されるパイプラインシミュレーションビュー

各ログについて、変更前と変更後の状態を比較します。比較対象の変更を選択します。

  • 自分の変更: パイプラインの現在デプロイされているバージョンと、変更を加えたバージョンを比較します。
  • パイプライン全体: パイプラインに入るログと、パイプライン全体の実行後のログを比較します。

ログリストを絞り込むには、クエリフィルターを使用するか、影響度でフィルタリングします。

  • すべてのログ: ライブテール内のすべてのログ。
  • 影響を受けたログ: このセッションでの編集によって変更されたログのみ。
  • 影響を受けていないログ: 編集によって変更されなかったログのみ。

パイプラインの管理

パイプラインの変更情報を使用して、パイプラインまたはプロセッサーへの最後の変更がいつ行われたか、およびどのユーザーが変更を行ったかを特定します。この変更情報や、パイプラインが有効か読み取り専用かといった他のファセットプロパティを使用して、パイプラインをフィルタリングします。

ファセット検索、パイプライン変更情報、および再配置モーダルを使用してパイプラインを管理する方法

スライディングオプションパネルの Move to オプションを使用して、パイプラインを正確に再配置します。Move to モーダルを使用して、選択したパイプラインの移動先となる正確な位置までスクロールし、クリックします。パイプラインは他の読み取り専用パイプラインには移動できません。ネストされたパイプラインを含むパイプラインは、トップレベルの別の位置にのみ移動できます。別のパイプラインに移動することはできません。

Move to モーダルを使用してパイプラインを正確に再配置する方法

既存のルールやプロセッサーを再利用するためにパイプラインをクローンし、最初からやり直す必要をなくします。パイプラインをクローンすると、Datadog はクローン元のパイプラインを自動的に無効化します。トグルをクリックして有効化します。

推定使用量メトリクス

各パイプラインの推定使用量メトリクスが表示されます。これにより、各パイプラインで取り込まれ、変換されるログのボリュームと件数が表示されます。すべてのパイプラインには、標準のログ推定使用量ダッシュボードへのリンクが含まれています。このダッシュボードは、パイプラインの使用量メトリクスの詳細なチャートを提供します。

パイプラインの使用量メトリクスを素早く確認する方法

自動処理

自動処理はプレビュー版です

アクセスをリクエストするにはフォームに入力します。

Request Access

自動処理は、カスタムアプリケーションログをパースし、タイムスタンプ、ステータス、サービス、トレース ID、スパン ID などの主要な属性を抽出します。これにより、パースを手動で設定することなく、ログの検索、フィルタリング、相関付けが可能になります。

自動処理は、既存のインテグレーションやカスタムパイプラインのフィルターに一致しないログのみを処理します。ログが既存のパイプラインのフィルターに一致する場合、そのパイプラインがログを変更しない場合でも自動処理はそのログを処理しません。既存のパイプライン構成は変更されません。

仕組み

Datadog は、サポートされているログをソースおよびサービスごとにグループ化し、それらの自動処理エントリを作成します。Datadog は、以前からサポートされているパターンのパース方法を変更することなく、新しいログパターンをサポートするようにエントリを自動的に更新します。

変換を確認し、ログを処理するエントリを制御します。エントリを手動のパイプラインに切り替えて、その構成をカスタマイズします。

自動処理を構成する

Processing ページに移動し、Auto-Processing タブを選択します。

自動処理のオン/オフを切り替える

機能トグルを使用して、組織の自動処理をオンまたはオフにします。

新しいエントリを有効にする方法を選択する

自動処理がオンの場合、新しいエントリを自動的に有効にするかどうかを選択します。

  • 新しいエントリを自動的に有効にする: 新しいエントリは作成時に有効になり、一致する受信ログの処理を開始します。
  • 有効にする前に新しいエントリを確認する: 新しいエントリは作成時に無効になります。変換を確認し、使用するエントリを有効にします。

変換を確認する

  1. Auto-Processing タブで、確認するソースとサービスを見つけます。
  2. View Transformations を選択します。
  3. ログパターンを選択し、ログの例を調べて、元の属性と処理後の属性を比較します。

エントリを有効または無効にする

Auto-Processing タブで、エントリのトグルを使用して、そのソースとサービスの処理を有効または無効にします。エントリを無効にすると、今後のログにのみ影響します。すでに処理済みのログは変更されません。

手動のパイプラインに切り替える

パースや属性名をカスタマイズするには、View Transformations ページで Switch to manual pipeline をクリックします。

切り替え後は、パイプラインの構成と今後の更新を自分で管理します。

制限事項

  • 各組織は最大 100 個の自動処理エントリを作成できます。
  • 自動処理ですでに対象となっているソースやサービスであっても、新しいログパターンの一部がパースされない場合があります。
  • 自動処理エントリ内では、パースのカスタマイズや属性名の変更はできません。これらの変更を行うには、手動のパイプラインに切り替えてください。

参考資料


*Logging without Limits は Datadog, Inc. の商標です。