ログ検索 API を使用してログデータにプログラマティックにアクセスする
概要
ログ検索 API を使用してログデータにプログラマティックにアクセスし、クエリを実行します。
このガイドでは、以下の例についてご説明します、
前提条件
ログ検索 API の使用には、API キーとアプリケーションキーが必要です。アプリケーションキーを作成したユーザーは、データにアクセスするための適切な権限を所有する必要があります。以下の例を使用する場合は、<DATADOG_API_KEY> および <DATADOG_APP_KEY> を、それぞれご使用中の Datadog API キーおよび Datadog アプリケーションキーに置き換えます。
このガイドでは curl の例を解説しています。curl をまだインストールしていない場合はインストールするか、ログ APIでこの API エンドポイントについての他言語の例を参照してください。
例
基本検索
特定の期間内のすべてのログイベントを取得するには、以下の検索構文を使用して API コールを完了します。
from はログデータの start time を、to は end time を表します。query は実行すべき検索クエリを示します。
API call:
curl -L -X POST "https://api.
Response:
結果のデータセットは、以下の応答サンプルに示されるように data オブジェクトで構成されます。
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIn0"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?filter%5Bquery%5D=%2A&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIn0&page%5Blimit%5D=3&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00"
}
}
ファセットまたはタイムスタンプでの並べ替え
ファセット
以下の API コールで、取得したログイベントを pageViews などのファセットで昇順に並べ替えます。ファセットには @ を含めるようにしてください。降順に並べ替える場合はファセット名の前にハイフン - を追加し、-@pageViews のような形で使用します。デフォルトの並び順はタイムスタンプの降順となります。
API call:
curl -L -X POST "https://api.
Response:
ログイベントは以下の応答にある通り、 pageViews ファセット値の昇順で取得されます。ユーザーごとのページビューはそれぞれ、chris が 450、bob が 500、steve が 700 です。
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIiwidmFsdWVzIjpbIjcwMCJdfQ"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=%40pageViews&filter%5Bquery%5D=%2A&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIiwidmFsdWVzIjpbIjcwMCJdfQ&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00"
}
}
タイムスタンプ
以下の API コールで、取得したログイベントを timestamp で昇順に並べ替えます。デフォルト表示は降順です。
API call:
curl -L -X POST "https://api.
Response:
ログイベントは以下の応答にある通り、timestamp の値に基づいて昇順で取得されます。
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIn0"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=timestamp&filter%5Bquery%5D=%2A&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIn0&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00"
}
}
取得した結果数の制限
以下の API コールで、取得したログイベントの数を制限します。limit は該当する応答で返されたログイベントの最大数を表します。制限の最大値は 1000 です。
curl -L -X POST "https://api.
Response:
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWFZOU3Z1TXZXd0FBQUFCQldGVkJXRlpPVTJJMlpXY3hYM2MyTFZWQlFRIiwidmFsdWVzIjpbIjUwMCJdfQ"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=-%40pageViews&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWFZOU3Z1TXZXd0FBQUFCQldGVkJXRlpPVTJJMlpXY3hYM2MyTFZWQlFRIiwidmFsdWVzIjpbIjUwMCJdfQ&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bquery%5D=%2A&page%5Blimit%5D=2"
}
}
時間設定
from および to パラメーターの定義は以下の通りです。
- ISO-8601 文字列
- Unix タイムスタンプ (Epoch 以降の経過ミリ秒を表す数)
- 1 時間を加算する
+1h、2 日を差し引く -2d など、日付の計算文字列。秒を表す s、 分を表す m、時間を表す h、日を表す d などが含まれます。オプションとして現在時刻を示す now も使用可能です。
{
"filter": {
"from": "now-1h",
"to": "now"
}
}
タイムゾーンはオフセット (“UTC+03:00” など) または地域ゾーン (“Europe/Paris” など) で指定することができます。オフセットとゾーンの両方が渡された場合は、オフセットが優先されます。オフセットは秒で指定する必要があります。
{
"options": {
"timeOffset": -1000,
"timezone": "Europe/Paris"
}
}
ページ区切り
1000 のログ制限よりも長いログリストを取得するには、ページ区切り機能を使用します。
data パラメーターは Log オブジェクトの配列であり、最大でクエリの limit パラメーターで定義された数のログが含まれます。このパラメーターはデフォルトで 50 ですが、最大 1000 に設定できます。
ログの次のページを閲覧するには、前の呼び出しから after を取得する cursor パラメーターでクエリを再送信します。
上記の JSON 例から、after の値 eyJhZnRlciI6IkFRQUFBWFVBWFZOU3Z1TXZXd0FBQUFCQldGVkJXRlpPVTJJMlpXY3hYM2MyTFZWQlFRIiwidmFsdWVzIjpbIjUwMCJdfQ を使用して次の 2 つの結果を取得します。
curl -L -X POST "https://api.
Response:
この応答では、次の 2 つの結果として 500 pageviews を持つ joe と、450 pageviews を持つ chris が取得されます。data が null を返したら、クエリに関連付けられたログのすべてのページが返ったことになります。
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIiwidmFsdWVzIjpbIjQ1MCJdfQ"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:00:59.733Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "joe",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXHFV1KuyTgAAAABBWFVBWEhGVlZrQmFzdEZ2X2dBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=-%40pageViews&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIiwidmFsdWVzIjpbIjQ1MCJdfQ&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bquery%5D=%2A&page%5Blimit%5D=2"
}
}
注: ページ区切りを使用する際は、相対的なタイムレンジを使用しないでください。検索結果が失われる可能性があります。
その他の参考資料
