属性とエイリアス設定

概要

さまざまなテクノロジーやアプリケーションから取得されるログを一元化すると、ログ管理環境に数十個から数百個の属性が生成されます。特に多数のチームのユーザーが同じ環境内で作業している場合は、その傾向が顕著です。

たとえば、クライアントの IP も、clientIP、client_ip_address、remote_address、client.ip など、さまざまなログ属性が存在します。リクエストの実行時間の場合は exec_time、request_latency、request.time_elapsed などのようになります。

属性 と エイリアスを使用して、ログ環境を統一します、

属性の種類とエイリアス設定

属性は、ログエクスプローラーでのフィルタリングと検索に使用されるログファセットとタグを規定します。

  • 予約済み属性は自動的に取り込まれます。

  • 標準属性は、組織で使用する命名規則の基盤となる存在です。アプリに標準的な属性のデフォルトセットが用意されていますが、このリストをカスタマイズしてチームの命名規則を作ることがきます。

  • 標準属性で命名規則を実装した場合や、複数のログソースから一意の標準ファセットを作成する場合、エイリアス設定を使用します。たとえば、ハイブリッド Apache および Amazon Cloud Front インフラストラクチャーの場合、標準の Network Client IP ファセットと標準の duration を使用して、レイテンシーに最も影響を受けるクライアントを追跡できます。エイリアス設定によりチームの技術スタックを変更することなく命名規則を実装できます。

予約済み属性

以下は、ログとともに自動的に取り込まれる予約済みの属性の一覧です。

注: トレースまたはメトリクスも収集している場合は、統合サービスタグ付けを構成することをお勧めします。このコンフィギュレーションは、env、service、version の 3 つの標準タグを使用して、Datadog テレメトリを結び付けます。詳細については、専用の統合サービスタグ付けドキュメントを参照してください。

属性説明
hostメトリクスで定義された送信元ホストの名前。Datadog で一致したホストから、対応するホストタグが自動的に取得され、ログに適用されます。Agent では、この値が自動的に設定されます。
sourceこれは、インテグレーション名 (ログの生成元) に対応します。インテグレーション名と一致する場合、対応するパーサーとファセットが自動的にインストールされます。たとえば、nginx、postgresql などです。
statusこれは、ログのレベル/セキュリティに対応します。パターン の定義に使用され、Datadog Logs UI に専用のレイアウトがあります。
serviceログイベントを生成するアプリケーションまたはサービスの名前。Logs から APM への切り替えに使用されます。このため、両方の製品を使用する際には必ず同じ値を定義してください。
trace_idこれは、トレースに使用されるトレース ID に対応します。ログとそのトレースを関連付けるために使用されます。
messageデフォルトでは、message 属性の値はログエントリの本文として収集されます。Live Tail では、この値はハイライトされて表示され、全文検索用にインデックス化されます。

標準属性

ログのインテグレーションは標準属性のデフォルトセットに依存します。

リストはオーガニゼーションの管理者が作成できます。

標準属性

標準属性テーブルには、定義済み標準属性セットが付属しています。このリストに独自の属性を追加したり、既存の標準属性を編集または削除することができます。

標準属性を編集

標準属性は以下によって定義されます。

  • Path: 標準属性として格上げされる属性のパス。JSON で定義されます (例: network.client.ip) 。
  • Type: (string, integer, double, boolean): 属性の型。再マップリストの要素をキャストするために使用されます。
  • Aliasing list: エイリアス設定対象となる属性のカンマ区切りリスト。
  • Description: 属性のわかりやすい説明。

新しい標準属性を追加したり、既存の標準属性を編集する際は、標準属性パネルが表示されます。

標準属性を定義

デフォルトの標準属性リスト

デフォルトの標準属性リストは機能領域に分かれています。

Web アクセス

以下は、ネットワーク通信で使用されるデータに関連する属性です。すべてのフィールドとメトリクスに network というプレフィックスが付きます。

完全名型説明
network.client.ipstringTCP 接続を開始したクライアントの IP アドレス。
network.destination.ipstringクライアントが接続した先の IP アドレス。
network.client.portnumber接続を開始したクライアントのポート。
network.destination.portnumberクライアントが接続した先の TCP ポート。
network.bytes_readnumberログの送信時にクライアントからサーバーに転送された合計バイト数。
network.bytes_writtennumberログの送信時にサーバーからクライアントに転送された合計バイト数。

これらの属性に依存する代表的なインテグレーションには、Apache、Varnish、AWS ELB、Nginx、HAProxy などがあります。

位置情報

以下は、ネットワーク通信で使用される IP アドレスの位置情報に関連する属性です。すべてのフィールドに network.client.geoip または network.destination.geoip というプレフィックスが付きます。

network.client.geoip.country.name
タイプ: string
国の名前。
network.client.geoip.country.iso_code
タイプ: string
国の ISO コード (例えば、アメリカなら US、フランスなら FR)。
network.client.geoip.continent.code
タイプ: string
大陸の ISO コード (EU、AS、NA、AF、AN、SA、OC)。
network.client.geoip.continent.name
タイプ: string
大陸名 (Europe、Australia、North America、Africa、Antartica、South America、Oceania)。
network.client.geoip.subdivision.name
タイプ: string
国の第一小区分レベルの名称 (米国は California 州、フランスは Sarthe 県など)。
network.client.geoip.subdivision.iso_code
タイプ: string
国の第一小区分レベルの ISO コード (米国は CA 州、フランスは SA 県など)。
network.client.geoip.city.name
タイプ: string
都市名 (例: Paris、New York)。

HTTP リクエスト

以下は、HTTP リクエストおよびアクセスで一般に使用されるデータに関連する属性です。すべての属性に http というプレフィックスが付きます。

これらの属性に依存する代表的なインテグレーションには、Apache、Rails、AWS CloudFront、Web アプリケーションサーバーなどがあります。

共通属性
完全名型説明
http.urlstringHTTP リクエストの URL。
http.status_codenumberHTTP 応答ステータスコード。
http.methodstringリソースに対して行われるアクションを示します。
http.refererstringリクエスト中のリソースにリンクした Web ページのアドレスを識別する HTTP ヘッダーフィールド。
http.request_idstringHTTP リクエストの ID。
http.useragentstring送信されたままの User-Agent (未加工の形式)。詳細については下記を参照してください。
http.versionstringリクエストに使用された HTTP のバージョン。
URL 詳細属性

これらの属性は、HTTP URL のパースされた各部に関する詳細を提供します。URL パーサーによって生成されます。すべての属性に http.url_details というプレフィックスが付きます。

完全名型説明
http.url_details.hoststringURL の HTTP ホスト部分。
http.url_details.portnumberURL の HTTP ポート部分。
http.url_details.pathstringURL の HTTP パス部分。
http.url_details.queryStringobjectクエリパラメーターの key/value 属性として分解された、URL の HTTP クエリ文字列部分。
http.url_details.schemestringURL のプロトコル名 (HTTP または HTTPS)。
User-Agent 属性

これらの属性は、ユーザーエージェント属性の意味に関する詳細を示すものです。ユーザーエージェントパーサーによって生成されます。すべての属性に http.useragent_details というプレフィックスが付きます。

完全名型説明
http.useragent_details.os.familystringUser-Agent によって報告された OS ファミリー。
http.useragent_details.browser.familystringUser-Agent によって報告されたブラウザファミリー。
http.useragent_details.device.familystringUser-Agent によって報告されたデバイスファミリー。

ソースコード

以下は、カスタムアプリケーションのロガーを使用してログまたはエラーを生成する際に使用されるデータに関係する属性です。すべての属性に logger または error というプレフィックスが付きます。

完全名型説明
logger.namestringロガーの名前。
logger.thread_namestringログの生成時の現在のスレッドの名前。
logger.method_namestringクラスメソッド名。
logger.versionstringロガーのバージョン。
error.kindstringエラーのタイプまたは種類 (場合によってはコード)。
error.messagestringイベントについて簡潔にわかりやすく説明する 1 行メッセージ。
error.stackstringスタックトレースまたはエラーに関する補足情報。

これらの属性に依存する代表的なインテグレーションには、Java、NodeJs、.NET、Golang、Python などがあります。

データベース

データベース関連の属性には db というプレフィックスが付いています。

db.instance
タイプ: string
データベースインスタンス名。たとえば、Java で jdbc.url="jdbc:mysql://127.0.0.1:3306/customers" の場合、インスタンス名は customers です。

db.statement :タイプ: string
指定されたデータベースタイプのデータベースステートメント。たとえば、mySQL の場合は "SELECT * FROM wuser_table";、Redis の場合は "SET mykey 'WuValue'" です。

db.operation
タイプ: string
実行された操作 (“query”、“update”、“delete” など)。
db.user
タイプ: string
操作を行うユーザー。

これらの属性に依存する代表的なインテグレーションには、Cassandra、MySQL、RDS、Elasticsearch などがあります。

パフォーマンス

パフォーマンスメトリクス属性。

完全名型説明
durationnumbernanoseconds 単位の任意の種類の時間。HTTP 応答時間、データベースクエリ時間、レイテンシーなどがあります。

Datadog ではこの属性をトレース検索のデフォルトのメジャーとして表示および使用するため、この属性に関するログ内で処理時間を再マップすることを推奨しています。

ユーザー関連の属性

すべての属性とメジャーに usr というプレフィックスが付きます。

完全名型説明
usr.idstringユーザーの識別子。
usr.namestringわかりやすいユーザー名。
usr.emailstringユーザーの電子メール。

Syslog とログシッパー

以下は、syslog またはログシッパーエージェントによって追加されるデータに関連する属性です。すべてのフィールドとメトリクスに syslog というプレフィックスが付きます。

完全名型説明
syslog.hostnamestringホスト名。
syslog.appnamestringアプリケーション名。通常は、予約済み属性 service に再マップされます。
syslog.severitynumberログの重大度。通常は、予約済み属性 status に再マップされます。
syslog.timestampstringログのタイムスタンプ。通常は、予約済み属性 date に再マップされます。
syslog.envstringログのソースが由来する環境名。

これらに依存するインテグレーションには、Rsyslog、NxLog、Syslog-ng、Fluentd、Logstash があります。

DNS

すべての属性とメジャーに dns というプレフィックスが付きます。

完全名型説明
dns.idstringDNS のクエリ識別子。
dns.question.namestringクエリ対象のドメイン名。
dns.question.typestringDNS の質問の種類を指定する 2 オクテットのコード。
dns.question.classstringDNS の質問で検索されるクラス (インターネットを使用する場合は IP など) 。
dns.question.sizenumberDNS 質問のバイトサイズ。
dns.answer.namestringDNS で回答する際の IP アドレス。
dns.answer.typestringDNS の回答の種類を指定する 2 オクテットのコード。
dns.answer.classstringDNS によって回答されるクラス。
dns.answer.sizenumberDNS 回答のバイトサイズ。
dns.flags.rcodestringDNS の返答コード。

イベント

すべての属性に evt というプレフィックスが付きます。

完全名型説明
evt.namestring同じアクティビティ (例: 認証) によって生成されたイベント間での共有名。
evt.outcomestringイベントの結果 (例: success、failure)。

エイリアス設定

宛先属性にマップされるソース属性のエイリアスを作成することで、ログにソースと宛先の両方の属性が含まれるようにできます。

ユーザーはエイリアス設定された (ソース) または標準 (宛先) ファセット属性のいずれかを利用することができますが、推奨されるのは、エイリアス設定されたファセットではなく標準ファセットです。これにより命名規則に従う必要性が強調され、非標準のコンテンツに基づくアセットの構築 (保存済みのビューやダッシュボードなど) を回避することができます。

エイリアス設定に関する確認事項:

  • エイリアス設定はパイプラインによってログが処理された後に実行されます。抽出済みまたは処理済みの属性は、エイリアス設定時のソースとして利用可能です。
  • Datadog ではエイリアス設定済みの属性の型が適用されます。これが不可能な場合、エイリアス設定はスキップされます。
  • ログに既に宛先属性が含まれている場合、エイリアス設定によりその値が上書きされます。
  • ひとつの標準属性で複数の属性をエイリアス化する場合、ログにこれらのソース属性が複数含まれているケースでは、そのうち 1 つのソース属性のみエイリアス設定が可能です。
  • 更新または追加された標準属性データは、新しく収集されるログにのみ適用されます。
  • 標準属性をエイリアス化することはできません。
  • 属性は標準属性に対してのみエイリアス設定が可能です。
  • ログの JSON 構造を尊重するため、ある標準属性を別の標準属性の子とすることはできません (user と user.name の両方を標準属性にすることは不可) 。

詳しくは、ファセットのエイリアス設定 を参照してください。

その他の参考資料

お役に立つドキュメント、リンクや記事:

Datadog のパイプラインドキュメント more more 使用可能なプロセッサーのリストドキュメント more more 無制限のログドキュメント more more ログの調査方法ドキュメント more more