特定のプロジェクトの Logstore 内のログを照会します。 関連するパラメーターを指定することによって、特定の条件を満たすログの照会もできます。
ログが Logstore に書き込まれた場合、GetHistograms とGetLogs の操作によるこのログの照会待ち時間は ログのタイプによって異なります。 Log Service はログタイムスタンプに基づいてログを次の種類に分類します。
- リアルタイムデータ:サーバー上の現在の時刻に基づいて (-180 秒、900 秒) の間隔内で生成されるログです。 たとえば、ログの生成時刻が 2014-09-25 12:03:00 UTC で、サーバーのログ受け取り時刻が 2014-09-25 12:05:00 UTC の場合、 サーバーはログをリアルタイムデータとして処理しています リアルタイムデータのログは、一般的に通常のシナリオで生成されます。
- 履歴データ:サーバー上の現在の時刻に基づいて (-7 × 86400 秒、-180 秒) の間隔内で生成されるログです。 たとえば、ログの生成時刻が 2014-09-25 12:00:00 UTC で、サーバーのログ受け取り時刻が 2014-09-25 12:05:00 UTC の場合、 サーバーはログを履歴データとして処理しています。 履歴データのログは、一般的に補足シナリオで生成されます。
リアルタイムのデータ書き込みから照会までの最大待ち時間は 3 秒です。 データは 99.9% のケースで 1 秒以内に照会できます。
リクエスト構文
GET /logstores/<logstorename>? type=log&topic=<logtopic>&from=<starttime>&to=<endtime>&query=<querystring>&line=<linenum>&offset=<startindex>&reverse=<true|false> HTTP/1.1
Authorization: <AuthorizationString>
Date: <GMT Date>
Host: <Project Endpoint>
x-log-bodyrawsize: 0
x-log-apiversion: 0.6.0
x-log-signaturemethod: hmac-sha1
リクエストパラメーター
パラメーター | データ型 | 必須/省略可能 | 説明 |
---|---|---|---|
logstorename | String | 必須 | 照会されるログ |
type | String | 必須 | 照会するログが属する Logstore の名前。 このパラメータを GetLogs 操作をするログに設定します。 |
from | Integer | 必須 | クエリの開始時間 (秒)。 このパラメーターを 1970-1-1 00:00:00 UTC からの秒数に設定します。 |
to | Integer | 必須 | データ照会の終了時間 (秒)。 このパラメーターを 1970-1-1 00:00:00 UTC からの秒数に設定します。 |
topic | String | 省略可能 | 照会されたログのタイプ。 |
query | String | 省略可能 | クエリ 文。 クエリ構文の詳細については、「クエリ構文」をご参照ください。 |
line | Integer | 省略可能 | リクエストから返されるログの最大数。 値の範囲:0~100 。 デフォルト値 :100。 |
offset | Integer | 省略可能 | リクエストの指定された時間間隔の開始点。 有効な値:0 と正の整数。 デフォルト値:0。 |
reverse | Boolean | 省略可能 | ログタイムスタンプに基づいてログを逆の順序で返すかどうかを分単位で指定します。 true は逆順、 false は通常の順序で返されたことを示します。 デフォルト値:false。 |
GetLogs 操作では、特別なリクエストヘッダーフィールドは必要ありません。 Log Service操作の一般的なリクエストヘッダー フィールドの詳細については、「一般的なリクエストヘッダーフィールド」をご参照ください。
レスポンスヘッダーフィールドLog Service 操作の一般的なレスポンスヘッダーの詳細については、 「一般的なレスポンスヘッダーフィールド」をご参照ください。
フィールド | データ型 | 説明 |
---|---|---|
x-log-progress | String | クエリ結果の状態。 値は結果が完了したかどうかを表す [Incomplete] または [Complete] です。 |
x-log-count | Integer | 現在のクエリ結果のログの総数。 |
GetLogs 操作に対するリクエストが送信された後、 レスポンスボディには、指定されたクエリ条件を満たすログが含まれます。 多数のログ (TB 単位) を照会する必要がある場合は、GetLogs 操作のレスポンスが未完了の場合があります。 GetLogs 操作のレスポンスボディは配列であり、この配列内の各要素はログです。 次の表に、配列内の各要素の構造を示します。
パラメーター | データ型 | 説明 |
---|---|---|
__time__ | Integer | ログのタイムスタンプ (秒単位)。 この値は、1970-1-1 00:00 UTC 以降の経過時間を示します。 |
__source__ | String | ログの作成時に指定されるログのソース。 |
[content] | Key-value pair | キーと値のペアで編成されたログの元のコンテンツ。 |
- この操作のリクエストパラメーター「from」と「to」で定義される時間間隔は、左クローズの右開きになります。 つまり、時間間隔には開始時刻が含まれますが、終了時刻は含まれません。 「from」と「to」パラメーターの値が同じ場合、 時間間隔は無効であり、サーバーはエラーを直接返します。
- サーバーは、指定された時間内に、この操作の各リクエストに対するレスポンスを返す必要があります。 クエリごとに、サーバーは指定した数のみログをスキャンできます。 サーバーがリクエストに対して多数のログを処理する必要がある場合は、不完全なクエリ結果が返されることがあります。 結果が完了しているかどうかは、 レスポンスヘッダーの x-log-progress フィールドで表示されます。 同時に、サーバーは 15 分以内に照会の結果を 分単位でキャッシュします。 リクエストのクエリ結果がキャッシュ内のデータにヒットした場合、サーバーはこのリクエストのキャッシュ内のデータにヒットしないログをスキャンし続けます。 複数のクエリ結果をマージする作業量を減らすために、サーバーはキャッシュ内のデータに当たったクエリ結果を現在のクエリで新しくスキャンした結果とマージし、マージされた結果を返します。 従って、Log Serviceを使用すると、同じパラメーターを使用して GetLogs 操作を複数回呼び出せば、完全な最終結果を取得できます。 Log Serviceは、完全な結果を取得するために必要な GetLogs 操作の呼び出し回数を予測できません。 なぜなら、照会対象のログ量は大幅に変動するからです。 そこで、各リクエストに対して返される結果の x-log-progress フィールドの値を確認して、 照会を継続するか判断する必要があります。 この操作を呼び出すたびに、コンピューティング ユニット (CALL) が同じ数だけ消費されます。
次の表に示すように、この操作は、Log Service の 一般的なエラー だけでなく特定のエラーも返します。
HTTP ステータスコード | エラーコード | エラーメッセージ | 説明 |
---|---|---|---|
404 | LogStoreNotExist | logstore {Name} does not exist. | 指定された VPC ID が存在しない場合に表示されるエラーメッセージ。 |
400 | InvalidTimeRange | request time range is invalid | 指定されたタグ値が無効な場合に表示されるエラーメッセージ。 |
400 | InvalidQueryString | query string is invalid | 指定されたセキュリティグループ名が無効である場合に表示されるエラーメッセージ。 |
400 | InvalidOffset | offset is invalid | リクエストの指定されたオフセットパラメーターが無効であるため、エラーメッセージが返されました。 |
400 | InvalidLine | line is invalid | リクエストの指定された行パラメーターが無効であるため、エラーメッセージが返されました。 |
400 | InvalidReverse | Reverse value is invalid | 指定されたタグ値が無効な場合に表示されるエラーメッセージ。 |
400 | IndexConfigNotExist | logstore without index config | Logstore のインデックス機能が有効になっていないため、エラーメッセージが返されました。 |
例
例として、中国 (杭州)の「big-game」というプロジェクトを取ります。 big-game プロジェクトの app_log Logstore でトピックが groupA であるログをクエリします。 このクエリの時間間隔は、 2014-09-01 00:00:00 ~ 2014-09-01 22:00:00、query キーワードがエラーです。 クエリは時間間隔の開始時刻から開始され、最大 20 個のログが返されます。
GET /logstores/app_log? type=log&topic=groupA&from=1409529600&to=1409608800&query=error&line=20&offset=0 HTTP/1.1
Authorization: <AuthorizationString>
Date: Wed, 3 Sept. 2014 08:33:46 GMT
Host: big-game.cn-hangzhou.log.aliyuncs.com
x-log-bodyrawsize: 0
x-log-apiversion: 0.4.0
x-log-signaturemethod: hmac-sha1
サンプル成功例
HTTP/1.1 200 OK
Content-MD5: 36F9F7F0339BEAF571581AF1B0AAAFB5
Content-Type: application/json
Content-Length: 269
Date: Wed, 3 Sept. 2014 08:33:47 GMT
x-log-requestid: efag01234-12341-15432f
x-log-progress: Complete
x-log-count: 10000
x-log-processed-rows: 10000
x-log-elapsed-millisecond:5
{
"progress": "Complete",
"count": 2,
"Tags": [
{
"__time__": 1409529660,
"__source__": "10.237.0.17",
"Key1": "error",
"Key2": "Value2"
},
{
"__time__": 1409529680,
"__source__": "10.237.0.18",
"Key3": "error",
"Key4": "Value4"
}
]
}
このサンプルレスポンスでは、 x-log-progress フィールドの値が「Complete」です。つまり、ログクエリは完全であり、返された結果も完全です。 このリクエストでは、2
つのログが指定されたクエリ条件を満たし、logs パラメーターの値として表示されます。 x-log-progress フィールドの値がレスポンスにおいて不完全な場合、
リクエストを繰り返して完全な結果を得る必要があります。