リファレンステーブル

概要

リファレンステーブルを使用すると、Datadog にすでにある情報にメタデータを結合することができます。情報のテーブルを含む CSV ファイルをアップロードすることで、顧客の詳細、サービス名と情報、または IP アドレスなどの新しいエンティティを定義することができます。エンティティは、リファレンステーブルの主キーと関連するメタデータによって表現されます。

org id、org name、parent org、account owner、csm の列にデータが格納されたリファレンステーブル

たとえば、次のようなことができます。

迅速な調査のためにログとセキュリティデータを強化する: 顧客名、アカウントオーナー、脅威インテリジェンス、エラーコードの説明など、最新のビジネスコンテキストでログ、トレース、およびセキュリティイベントを相関させて、トラブルシューティングと分析を加速します。
ターゲット分析やコスト管理のためにユーザーとリソースをセグメント化する: ユーザー層、チーム、ビジネスユニットなどの意味のあるセグメントにユーザー、顧客、またはクラウドリソースをグループ化し、Tag Pipelines などのツールを使用して、より深い製品分析と正確なコスト帰属を実現します。
高度なクエリとレポートのためにデータを強化する: Sheets、DDSQL エディター、または Notebooks でリファレンステーブルから外部データを結合して、技術的な専門知識なしで複雑なクエリ、集約を実行し、カスタムレポートを作成します。

リファレンステーブルを作成する

Datadog は、インテグレーションや手動 CSV アップロードを含む次のデータソースをサポートしています。

[New Reference Table +] (新規リファレンステーブル +) をクリックしてから、CSV ファイルをアップロードし、適切な列に名前を付けて、ルックアップのプライマリキーを定義します。

Define the Schema セクションで、org_id を主キーとするテーブルと、org id、org name、parent org、account owner、および csm のデータを持つ列を表示しています

注: CSV の手動アップロードは、4MB までのファイルをサポートしています。

Amazon S3

リファレンステーブルは、Amazon S3 バケットから CSV ファイルを自動的にプルして、データを最新の状態に保つことができます。インテグレーションでは、S3 で CSV ファイルへの変更が検索され、ファイルが更新されると、リファレンステーブルが新しいデータに置き換えられます。初期リファレンステーブルを一度構成しておけば、S3 API を使用した API での更新も可能です。注: CSV ファイルの内容に変更がない場合は、リファレンステーブルは置き換えられません。

S3 からリファレンステーブルを更新するために、Datadog は AWS インテグレーション用に構成した AWS アカウントの IAM ロールを使用します。このロールをまだ作成していない場合は、こちらの手順で作成してください。このロールがリファレンステーブルを更新できるようにするには、次のアクセス許可ステートメントを IAM ポリシーに追加します。バケット名は、環境に合わせて編集します。

注: サーバーサイド暗号化を使用する場合、Amazon S3 管理キー (SSE-S3) または AWS Key Management Service キー (SSE-KMS) で暗号化されたリファレンステーブルをアップロードできます。

{
	"Statement": [
		{
			"Sid": "EnrichmentTablesS3",
			"Effect": "Allow",
			"Action": [
				"s3:GetObject",
				// Grant KMS decrypt permissions if uploading KMS-encrypted object
				// "kms:Decrypt",
				"s3:ListBucket"
			],
			"Resource": [
				"arn:aws:s3:::<MY_BUCKET_NAME_1/*>",
				"arn:aws:s3:::<MY_BUCKET_NAME_2>"
			]
		}
	],
	"Version": "2012-10-17"
}

テーブルを定義する

[New Reference Table +] をクリックしてから、名前を追加し、[Amazon S3] を選択し、すべてのフィールドに入力し、インポートをクリックして、ルックアップのプライマリキーを定義します。

Amazon S3 タイルを選択し、AWS Account、Bucket、Path のデータを記入した upload your data セクション

注: S3 バケットからのアップロードは、200MB までのファイルをサポートしています。

Azure Storage

まだの場合は、リファレンステーブルをインポートするストレージアカウントを保持するサブスクリプション内で、Azure インテグレーションをセットアップしてください。これには、Datadog がインテグレーションできるアプリ登録の作成を伴います。
Azure Portal で、リファレンステーブルファイルを保存するストレージアカウントを選択します。
ストレージアカウント内で、[Access Control (IAM)] に移動し、[Add] (追加) > [Add Role Assignment] (ロールの割り当ての追加) を選択します。
Storage Blob Data Reader ロールを入力して選択します。Storage Blob Data Reader ロールは、Datadog がストレージコンテナや Blob を読み込んで一覧表示できるようにするものです。
[Members] (メンバー) タブで、[

Select members

] (+ メンバーを選択) をクリックします。ステップ 1 で作成したアプリ登録を選択します。

 <div class="shortcode-wrapper shortcode-img expand"><figure class="text-center"><a href="https://docs.dd-static.net/images/reference_tables/add_members.bbbaf670376f94f45cde38445df6bebd.png?fit=max&amp;auto=format" class="pop" data-bs-toggle="modal" data-bs-target="#popupImageModal"><picture class=""  style="width:85%;"  >
         <img 
             class="img-fluid" 
             srcset="https://docs.dd-static.net/images/reference_tables/add_members.bbbaf670376f94f45cde38445df6bebd.png?auto=format&amp;fit=max&amp;w=850 1x, https://docs.dd-static.net/images/reference_tables/add_members.bbbaf670376f94f45cde38445df6bebd.png?auto=format&amp;fit=max&amp;w=850&amp;dpr=2 2x"
             style="width:85%;"  alt="Azure Portal の Members セクションで、メンバーが選択され、Name、Object ID、Type にデータが入力された状態"  />
       </picture></a></figure>
 </div>

ロールの確認と割り当てが完了したら、Azure からリファレンステーブルにインポートすることができます。Datadog で Azure の構成が更新されるまで、数分かかる場合があります。

新規リファレンステーブルのワークフローの Upload or import data セクションにある Azure Storage タイル

詳しくは、Azure インテグレーションドキュメントを参照してください。

注: クラウドオブジェクトストレージからのアップロードは、200MB までのファイルをサポートしています。

Google Cloud Storage

Datadog で Google Cloud インテグレーションをセットアップしていない場合、またはレガシー Google プロジェクト ID ファイル (レガシープロジェクトであることは GCP インテグレーションタイルに表示されています) を使用している場合は、Google Cloud Platform インテグレーションのセットアップ手順に従ってください。これには、Google Cloud サービスアカウントを作成する必要があります。
Google Cloud コンソールから、[Cloud Storage] ページに移動します。
アクセス権を与えたいバケットを見つけてクリックします。
[Permissions] (権限) タブをクリックします。[View By Principals] (プリンシパル別に表示) の下にある [Grant Access] (アクセスを許可) ボタンをクリックします。
表示されるウィンドウで、[New principals] (新しいプリンシパル) フィールドの下に、ステップ 1 で作成して GCP タイルに追加したサービスアカウントのメールアドレスを入力します。[Assign roles] (ロールを割り当てる) の下で、[Storage Object Viewer] (Storage オブジェクト閲覧者) ロールを選択します。[Save] (保存) をクリックします。

ロールの確認と割り当てが完了したら、Google Cloud からリファレンステーブルにインポートすることができます。Datadog で構成が更新されるまで、数分かかる場合があります。

新しいリファレンステーブルを作成する際に、データのアップロードまたはインポートで GCP ストレージを選択します

注: クラウドオブジェクトストレージからのアップロードは、200MB までのファイルをサポートしています。

Terraform

datadog_reference_table リソースを使用して、Infrastructure as Code としてリファレンステーブルを管理します。テーブルスキーマ、プライマリキー、およびクラウドストレージアクセスの詳細でリソースを構成します。

注: Terraform はクラウドストレージのアップロードと同じファイルサイズ制限をサポートしています。詳細については、リファレンステーブルの制限を参照してください。

Datadog API を使用して、プログラムでリファレンステーブルを作成します。

Create リファレンステーブルエンドポイントを使用して、クラウドストレージまたはローカルファイルからリファレンステーブルを作成します。

クラウドストレージソース (S3、Azure、GCS) の場合、クラウドストレージ内の CSV ファイルを指す access_details を file_metadata で指定します。
ローカルファイルの場合、POST /api/latest/reference-tables/uploads を呼び出してアップロード ID を取得し、CSV データをアップロードします。その後、upload_id を file_metadata で指定して Create リファレンステーブルエンドポイントを呼び出します。

注: API はクラウドストレージのアップロードと同じファイルサイズ制限をサポートしています。詳細については、リファレンステーブルの制限を参照してください。

ローカル CSV ファイルをバックエンドとするリファレンステーブルを API で管理する詳細な手順については、API を使用したリファレンステーブルの作成、更新、削除を参照してください。

このリファレンステーブルを使用して、ルックアッププロセッサーでログに属性を追加できます。

検証ルール

リファレンステーブルの名前と列のヘッダーは、以下の命名規則で検証され、必要に応じて自動的に更新または正規化されます。

ルール	正規化
名前とヘッダーは重複できません。	重複した名前は列挙されます。たとえば、`fileid` が名前として 2 回使用された場合、最初のインスタンスは `fileid1` に、2 番目のインスタンスは `fileid2` になります。名前またはヘッダーを列挙した際に、56 文字を超える場合は拒否され、名前を変更する必要があります。
名前とヘッダーに大文字を含めることはできません。	大文字で書かれた名前は、小文字に変換されます。この変換の結果、名前が重複することがありますが、その場合は列挙されます。たとえば、`Fileid` と `FileID` は両方とも `fileid` となり、それぞれ `fileid1` と `fileid2` に列挙されます。
名前とヘッダーにスペースを含めることはできません。	先頭と末尾のスペース以外のスペースは、アンダースコア `_` 文字に置き換えられます。先頭および末尾のスペースは削除されます。たとえば、`customer names` は `customer_names` に置き換えられます。
名前とヘッダーは小文字で始める必要があります。	大文字は小文字に変換されます。文字以外の先頭の文字は削除されます。たとえば、`23Two_three` は `two_three` になります。
名前とヘッダーは、小文字のアルファベット、数字、および `_` 文字のみをサポートします。	サポートされていない文字はアンダースコア (`_`) に置き換えられます。ただし、上記のルールのいずれかに違反する場合は、その文字は該当するルールに従って正規化されます。
名前とヘッダーは 56 文字以内にする必要があります。	正規化は行われません。56 文字を超える名前とヘッダーは拒否され、名前を変更する必要があります。

リファレンステーブルを変更する

既存のリファレンステーブルを新しいデータで変更するには、テーブルを選択し、右上の [Update Config] (構成を更新) をクリックします。選択した CSV がテーブルにアップサートされます。つまり、次のようになります。

同じ主キーを持つ既存の行はすべて更新される
すべての新しい行が追加される
新しいファイルに含まれない古い行はすべて削除される

テーブルが保存されると、アップサートされた行は非同期で処理され、プレビューで更新されます。更新が完了するまでには、最大で 10 分かかる場合があります。

リファレンステーブルをエクスポートする

リファレンステーブルをエクスポートするには、テーブルを選択し、[Query in DDSQL Editor] (DDSQL エディターでクエリ) をクリックします。そこから、DDSQL エディターを使用して CSV、Dashboard などにエクスポートできます。

Table Preview の結果の上に Query in DDSQL Editor というラベルの青いボタンが表示されます

リファレンステーブルを削除する

リファレンステーブルを削除するには、テーブルを選択し、右上の歯車アイコンをクリックし、[Delete Table] (テーブルを削除) をクリックします。テーブルと関連するすべての行が削除されます。

リファレンステーブルを使用しているルックアッププロセッサーがある場合、ログエンリッチメントが停止します。エンリッチメントが停止するまで、最大で 10 分かかる場合があります。

リファレンステーブルアクティビティの監視

監査証跡または変更イベントでリファレンステーブルのアクティビティを監視することができます。特定のリファレンステーブルの監査証跡と変更イベントを表示するには、そのテーブルを選択し、[Update Config] の隣にある設定アイコンをクリックします。監査証跡を表示するには、組織の管理権限が必要です。

監査証跡

リファレンステーブルの監査証跡を使用して、ユーザーをトリガーとするアクションを追跡することができます。監査証跡イベントは、ユーザーが最初に CSV ファイルをアップロードまたはインポートしたとき、またはユーザーがリファレンステーブルを作成、変更、または削除したときに送信されます。

reference_table_file アセットタイプはインポート/アップロードのイベントを表示し、reference_table アセットタイプはリファレンステーブルのイベントを表示します。監査証跡は、リファレンステーブルの内容の観測可能性を提供します。

変更イベント

リファレンステーブルの変更イベントを使用して、自動化またはユーザートリガーによるアクションを追跡します。イベントは、クラウドファイルがユーザーまたは自動更新からインポートされたときに送信されます(ローカルファイルのアップロード時は変更イベントは生成されません)。イベントはユーザートリガーのアクションを追跡できますが、主にリファレンステーブルが自動的に新しい CSV ファイルを取り込む際のトリガーインポートを追跡するために使用されます。

イベントには、インポートの成功ステータス、パス、テーブル名に関する情報が含まれます。エラーが発生した場合は、エラーの種類に関する情報が提供されます。