リクエストパスとメソッド
リクエストパス: /api/query
リクエストメソッド: POST
説明: この API 操作を呼び出してデータをクエリできます。
JSON 形式のリクエストのパラメーター
パラメーター | タイプ | 必須 | 説明 | デフォルト値 | 例 |
start | Long | はい | クエリ対象の時間範囲の開始時刻です。単位：秒またはミリ秒。TSDB がタイムスタンプの単位を決定する方法の詳細については、このトピックの タイムスタンプの単位 セクションをご参照ください。 | なし | 1499158925 |
end | Long | いいえ | クエリ対象の期間の終了時刻です。単位：秒またはミリ秒。TSDB がタイムスタンプの単位を決定する方法の詳細については、このトピックの [タイムスタンプの単位] セクションをご参照ください。 デフォルト値は、TSDB サーバーの現在の時刻です。 | 現在の時刻 | 1499162916 |
queries | Array | はい | サブクエリアレイ。 | なし | 詳細については、「JSON 形式のサブクエリのパラメーター」セクションを参照してください。 |
msResolution | boolean | いいえ | タイムスタンプの単位をミリ秒に変換するかどうかを指定します。 | false | このパラメーターは、クエリするデータポイントのタイムスタンプが秒単位で測定されている場合にのみ有効になります。値を true に設定すると、クエリ結果のタイムスタンプの単位はミリ秒になります。それ以外の場合、元のタイムスタンプ単位が保持されます。クエリするデータポイントのタイムスタンプがミリ秒の場合、このパラメーターの値が true か false かに関係なく、クエリ結果のタイムスタンプ単位はミリ秒になります。 |
hint | Map | いいえ | クエリヒント。 | なし | 詳細については、「パラメーター: hint」セクションを参照してください。 |
タイムスタンプの単位
タイムスタンプは、秒またはミリ秒で測定できます。TSDB は、タイムスタンプの数値に基づいて、次のルールを使用してタイムスタンプの単位を決定します。
[4294968, 4294967295] の範囲内の値の場合、TSDB はタイムスタンプが秒単位で測定されていると判断します。この場合、対応する日付と時刻の範囲は [1970-02-20 01:02:48, 2106-02-07 14:28:15] です。
[4294967296, 9999999999999] の範囲内の値の場合、単位はミリ秒です。この場合、日付と時刻の範囲は [1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999] です。
値が (-∞, 4294968) または (9999999999999, +∞) の範囲内にある場合、タイムスタンプは無効です。
これらのルールは、次の API 操作に適用されます。/api/put および api/query。最初の API 操作はデータの書き込みに使用されます。もう 1 つの API 操作はデータのクエリに使用されます。
単一時点のデータポイントのクエリ
TSDB では、単一時点でのデータポイントをクエリできます。単一時点でのデータポイントをクエリするには、開始時刻と終了時刻を同じ値に設定します。たとえば、start パラメーターと end パラメーターを 1356998400 に設定できます。
JSON 形式のサブクエリのパラメーター
パラメーター | タイプ | 必須 | 説明 | デフォルト値 | 例 |
aggregator | String | はい | 集計関数。詳細については、「パラメーター: aggregator」セクションをご参照ください。 | なし | sum |
metric | String | はい | メトリック名。 | なし | sys.cpu0 |
rate | Boolean | いいえ | 指定されたメトリックの値間の増加率を計算するかどうかを指定します。増加率は、次の式に基づいて計算されます。増加率 = (Vt - Vt-1)/(t1 - t-1)。 | false | true |
delta | Boolean | いいえ | 指定されたメトリックの値間のデルタを計算するかどうかを指定します。このデルタは、次の式に基づいて計算されます。デルタ = Vt - (Vt-1)。 | false | true |
limit | Integer | いいえ | サブクエリごとに各ページで返す各時系列のデータポイントの最大数。 | 0 | 1000 |
offset | Integer | いいえ | サブクエリごとに各ページでスキップする各時系列のデータポイントの数。 | 0 | 500 |
dpValue | String | いいえ | 返されるデータポイントがフィルタリングされるフィルタリング条件。>、<、=、<=、>=、および != 演算子がサポートされています。 | なし | >=1000 |
preDpValue | String | いいえ | 生のデータポイントがスキャンされるフィルタリング条件。>、<、=、<=、>=、および != 演算子がサポートされています。 説明 preDpValue は | なし | >=1000 |
downsample | String | いいえ | ダウンサンプリング構成。 | なし | 60m-avg |
tags | Map | いいえ | データのフィルタリングに使用されるタグ条件を指定します。このパラメーターは、filters パラメーターと相互に排他的です。 | なし | - |
filters | List | いいえ | フィルタリング条件を指定します。このパラメーターは、tags パラメーターと相互に排他的です。 | なし | - |
hint | Map | いいえ | クエリヒント。 | なし | 詳細については、「パラメーター: hint」セクションを参照してください。 |
forecasting | String | いいえ | 時系列のデータを予測します。 | なし | 詳細については、「パラメーター: forecasting」セクションを参照してください。 |
abnormaldetect | String | いいえ | 異常検出のために時系列のデータを予測します。 | なし | 詳細については、「パラメーター: abnormaldetect」セクションを参照してください。 |
クエリには最大 200 のサブクエリが含まれます。
tags パラメーターと filters パラメーターの両方を指定した場合、JSON 形式のデータの後半に指定したパラメーターが有効になります。
limit、dpValue、downsample、tags、および filters パラメーターの詳細については、以下の説明を参照してください。
サンプルリクエスト
リクエスト行: POST/api/query
{
"start": 1356998400, // 開始時刻
"end": 1356998460, // 終了時刻
"queries": [
{
"aggregator": "sum", // 集計関数
"metric": "sys.cpu.0" // メトリック名
},
{
"aggregator": "sum", // 集計関数
"metric": "sys.cpu.1" // メトリック名
}
]
}パラメーター: limit と offset
limit パラメーターは、サブクエリごとに各時系列で返すデータポイントの最大数を指定します。limit パラメーターのデフォルト値は 0 です。デフォルト値 0 は、返されるデータポイントの数に制限がないことを示します。
offset パラメーターは、サブクエリごとに各時系列でスキップするデータポイントの数を指定します。offset パラメーターのデフォルト値は 0 です。デフォルト値 0 は、データポイントがスキップされないことを示します。
limit パラメーターまたは offset パラメーターを負の数に設定することはできません。
例
ランキングが 1001 位から 1500 位のデータポイントを取得する場合、limit パラメーターを 500 に、offset パラメーターを 1000 に設定します。
{
"start":1346046400, // 開始時刻
"end":1347056500, // 終了時刻
"queries":[
{
"aggregator":"avg", // 集計関数
"downsample":"2s-sum", // ダウンサンプリング設定
"metric":"sys.cpu.0", // メトリック名
"limit":"500", // 制限
"offset":"1000", // オフセット
"tags":{
"host":"localhost", // ホストタグ
"appName":"hitsdb" // アプリケーション名タグ
}
}
]
}パラメーター: dpValue
dpValue パラメーターは、データ値の制限を指定します。このパラメーターを指定して、返されるデータポイントをフィルタリングできます。有効な値は、>、<、=、<=、>=、および != です。
このパラメーターを文字列に設定する場合、文字列には = および != 演算子のみを含めることができます。
例
{
"start":1346046400, // 開始時刻
"end":1347056500, // 終了時刻
"queries":[
{
"aggregator":"avg", // 集計関数
"downsample":"2s-sum", // ダウンサンプリング設定
"metric":"sys.cpu.0", // メトリック名
"dpValue":">=500", // データ値の制限
"tags":{
"host":"localhost", // ホストタグ
"appName":"hitsdb" // アプリケーション名タグ
}
}
]
}パラメーター: delta
サブクエリでデルタ演算子を指定すると、TSDB によって返される dps データポイントのキーと値のペアの値は、計算されたデルタになります。デルタパラメーターが指定されていないときに返される dps データポイントに n 個のキーと値のペアが含まれている場合、デルタの計算後に返される dps データポイントには n-1 個のキーと値のペアのみが含まれます。最初のキーと値のペアは、このペアのデルタを計算できないため、使用されません。デルタ演算子は、ダウンサンプリング後の値にも適用されます。
デルタ演算子を指定した後、サブクエリで deltaOptions を構成して、デルタの計算方法をさらに制御できます。次の表に、deltaOptions に使用できるパラメーターを示します。
パラメーター | タイプ | 必須 | 説明 | デフォルト値 | 例 |
counter | Boolean | いいえ | このマーカービットを指定すると、デルタの計算に想定されるメトリック値を、単調に増加または減少する累積値と見なすことができます。累積値は、カウンターの値に似ています。サーバーはメトリック値をチェックしません。 | false | true |
counterMax | Integer | いいえ | counter パラメーターが true に設定されている場合、counterMax パラメーターはデルタのしきい値を指定します。デルタの絶対値がしきい値を超えると、デルタは異常です。counterMax パラメーターの値を指定しない場合、デルタにしきい値はありません。 | なし | 100 |
dropReset | Boolean | いいえ | このマーカービットは、counterMax と一緒に使用する必要があります。 counterMax パラメーターが指定されていて、計算されたデルタが異常な場合、dropReset パラメーターを使用して、異常なデルタを破棄するかどうかを指定できます。 dropReset パラメーターが true に設定されている場合、異常なデルタは破棄されます。 このパラメーターが false に設定されている場合、異常なデルタは 0 にリセットされます。 このパラメーターのデフォルト値は false です。 | false | true |
例
{
"start":1346046400, // 開始時刻
"end":1347056500, // 終了時刻
"queries":[
{
"aggregator":"none", // 集計関数
"downsample":"5s-avg", // ダウンサンプリング設定
"delta":true, // デルタを計算するかどうか
"deltaOptions":{
"counter":true, // カウンターとして扱うかどうか
"counterMax":100 // カウンターの最大値
}
"metric":"sys.cpu.0", // メトリック名
"dpValue":">=50", // データ値の制限
"tags":{
"host":"localhost", // ホストタグ
"appName":"hitsdb" // アプリケーション名タグ
}
}
]
}パラメーター: downsample
長い時間範囲で生成されたデータをクエリし、指定された時間間隔に基づいてデータを集計する必要がある場合に、このパラメーターを使用します。タイムラインは、ダウンサンプリング用に指定された時間間隔に基づいて複数の時間範囲に分割されます。返される各タイムスタンプは、各時間範囲の開始を示します。次のサンプルコードは、クエリの形式の例を示しています。
<interval><units>-<aggregator>[-fill policy]クエリ形式は、ダウンサンプリング式です。
downsample パラメーターを指定した後、データ集計用に指定された間隔と同じ長さの時間ウィンドウが、指定された時間範囲の開始と終了に自動的に追加されます。たとえば、指定されたタイムスタンプ範囲が [1346846401, 1346846499] で、指定された間隔が 5 分の場合、クエリの実際のタイムスタンプ範囲は [1346846101, 1346846799] です。
次のリストでは、ダウンサンプリング式のフィールドについて説明します。
間隔: 5 や 60 などの数値を指定します。値 0all は、時間範囲内のデータポイントが単一の値に集計されることを示します。
単位: 単位です。 s は秒を表します。 m は分を表します。 h は時間を表します。 d は日を表します。 n は月を表します。 y は年を表します。
説明デフォルトでは、タイムスタンプを調整するために剰余演算と切り捨て演算が実行されます。タイムスタンプは、次の式を使用して調整されます。調整されたタイムスタンプ = データタイムスタンプ - (データタイムスタンプ % 時間間隔)。
カレンダー時間間隔に基づいてデータをダウンサンプリングすることができます。カレンダー時間間隔を使用するには、units パラメータの値の末尾に
cを追加します。例えば、1dcは、当日の 00:00 から翌日の 00:00 までの 24 時間の期間を示します。
アグリゲーター: 集計設定です。次の表は、ダウンサンプリングに使用される演算子について説明しています。
演算子
説明
avg
平均値を返します。
count
データポイントの数を返します。
first
最初の値を返します。
last
最後の値を返します。
min
最小値を返します。
max
最大値を返します。
median
中央値を返します。
sum
値の合計を返します。
zimsum
値の合計を返します。
rfirst
first演算子によって返されるのと同じデータポイントを返します。ただし、返されるタイムスタンプは、調整されたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に調整されます。rlast
last演算子によって返されるのと同じデータポイントを返します。ただし、返されるタイムスタンプは、調整されたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に調整されます。rmin
min演算子によって返されるデータポイントと同じデータポイントを返します。ただし、返されるタイムスタンプは、調整されたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に調整されます。rmax
max演算子によって返されるデータポイントと同じデータポイントを返します。ただし、返されるタイムスタンプは、調整されたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に調整されます。説明ダウンサンプリング式でアグリゲーターを rfirst、rlast、rmin、または rmax 演算子に設定した場合、ダウンサンプリング式で fill ポリシーパラメーターを設定することはできません。
塗りつぶしポリシー
埋め込みポリシーを指定して、欠損値を事前定義された値で埋める方法を決定できます。ダウンサンプリング中、すべてのタイムラインは指定された時間間隔に基づいて分割され、各時間範囲のデータポイントが集計されます。ダウンサンプリング結果の時間範囲に値が存在しない場合、埋め込みポリシーを指定して、欠損値を事前定義された値で埋めることができます。例を使用して埋め込みポリシーについて説明します。この例では、ダウンサンプリング後のタイムラインのタイムスタンプは t+0、t+20、および t+30 です。埋め込みポリシーを指定しない場合、3 つの値のみが報告されます。埋め込みポリシーを null に設定すると、4 つの値が報告されます。時点 t+10 の欠損値は null で埋められます。
次の表に、埋め込みポリシーと埋められる値を示します。
埋め込みポリシー
欠損値を次で埋める
none
値は埋められません。これがデフォルト値です。
nan
null
null
null
zero
0
linear
線形補間に基づいて計算された値。
previous
前の値。
near
隣接値。
after
次の値。
fixed
ユーザー指定の固定値。詳細については、このトピックの「[埋め込みポリシー (固定値)]」セクションの説明を参照してください。
固定塗りつぶしポリシー
欠損値を固定値で埋めるには、番号記号 (
#) の末尾に固定値を追加します。固定値を正または負の数に設定できます。次のサンプルコードは、有効な形式の例を示しています。<interval><units>-<aggregator>-fixed#<number>2 つの例は、1h-sum-fixed#6 と 1h-avg-fixed#-8 です。
ダウンサンプリングの例
3 つのダウンサンプリングの例は、1m-avg、1h-sum-zero、および 1h-sum-near です。
重要downsample パラメーターは、クエリではオプションです。このパラメーターを null に設定するか、このパラメーターを空のままにすることができます。{"downsample": null} または {"downsample": ""}。この場合、データはダウンサンプリングされません。
パラメーター: aggregator
データがダウンサンプリングされた後、複数のタイムラインに沿った値が取得され、これらのタイムラインのタイムスタンプが調整されます。各調整済みタイムスタンプの値を集計することにより、これらのタイムラインを 1 つにマージするために集計を実行できます。タイムラインが 1 つしかない場合は、集計は実行されません。集計中、各タイムラインは各調整済みタイムスタンプに値を持つ必要があります。調整済みタイムスタンプに値が見つからない場合は、補間が実行されます。詳細については、次の「[補間]」セクションを参照してください。
補間
タイムラインにタイムスタンプの値がない場合、値がタイムスタンプのタイムラインに補間されます。これは、埋め込みポリシーを指定せず、集計される他のタイムラインのいずれかにこのタイムスタンプの値がある場合にのみ発生します。例を使用して補間について説明します。この例では、sum 演算子を使用して 2 つのタイムラインをマージします。ダウンサンプリングと集計の設定は、{"downsample": "10s-avg", "aggregator": "10s-avg", "aggregator": "sum"} です。データがダウンサンプリングされた後、2 つのタイムラインに沿って次のタイムスタンプに値が見つかります。
タイムライン 1 では、タイムスタンプ t+0、t+10、t+20、および t+30 に値が見つかります。タイムライン 2 では、タイムスタンプ t+0、t+20、および t+30 に値が見つかります。
タイムライン 2 に沿って、t+10 タイムスタンプの値がありません。データが集計される前に、この タイムスタンプ のタイムライン 2 に値が補間されます。補間方法は、集計演算子によって異なります。次の表に、演算子と補間方法を示します。
演算子 | 説明 | 補間方法 |
avg | 平均値を返します。 | 線形補間が使用されます。線形補間は、線形勾配に基づいて実行されます。 |
count | データポイントの数を返します。 | 値 0 が補間されます。 |
mimmin | 最小値を返します。 | 最大値が補間されます。 |
mimmax | 最大値を返します。 | 最小値が補間されます。 |
min | 最小値を返します。 | 線形補間が使用されます。 |
max | 最大値を返します。 | 線形補間が使用されます。 |
none | データ集計をスキップします。 | 値 0 が補間されます。 |
sum | 値の合計を返します。 | 線形補間が使用されます。 |
zimsum | 値の合計を返します。 | 値 0 が補間されます。 |
パラメーター: filters
次の方法を使用して、filters パラメーターを構成できます。
タグキーを指定します。
tagk = *: タグキーのタグ値に対して GROUP BY 操作を実行して、同じタグ値を集計できます。
tagk = tagv1|tagv2: タグキーの tagv1 値を集計し、タグキーの tagv2 値を集計できます。
JSON 形式でフィルターを指定します。次の表に、パラメーターを示します。
パラメーター
タイプ
必須
説明
デフォルト値
例
type
String
はい
フィルターのタイプ。詳細については、「[フィルターのタイプ]」セクションを参照してください。
なし
literal_or
tagk
String
はい
タグのキー。
なし
host
filter
String
はい
フィルター式。
なし
web01|web02
groupBy
Boolean
いいえ
タグ値で GROUP BY 演算を実行するかどうかを指定します。
false
false
フィルターの種類
フィルタータイプ
例
説明
literal_or
web01|web02
各 tagv の値が集計されます。このフィルターでは大文字と小文字が区別されます。
wildcard
*.example.com
各 tagv に指定されたワイルドカードを含むタグ値が集計されます。このフィルターでは大文字と小文字が区別されます。
サンプルリクエスト
フィルターなしのサンプルリクエスト
リクエスト本文:
{ "start": 1356998400, // 開始時刻 "end": 1356998460, // 終了時刻 "queries": [ { "aggregator": "sum", // 集計関数 "metric": "sys.cpu.0",// メトリック名 "rate": "true", // 増加率を計算するかどうか "tags": { "host": "*", // ホストタグ "dc": "lga" // データセンタータグ } } ] }フィルターを指定したサンプルリクエスト
リクエスト本文:
{ "start": 1356998400, // 開始時刻 "end": 1356998460, // 終了時刻 "queries": [ { "aggregator": "sum", // 集計関数 "metric": "sys.cpu.0",// メトリック名 "rate": "true", // 増加率を計算するかどうか "filters": [ { "type": "wildcard", // フィルタータイプ "tagk": "host", // タグキー "filter": "*", // フィルター "groupBy": true // グループ化するかどうか }, { "type": "literal_or",// フィルタータイプ "tagk": "dc", // タグキー "filter": "lga|lga1|lga2",// フィルター "groupBy": false // グループ化するかどうか } ] } ] }クエリ結果
クエリが成功した場合、HTTP ステータスコードは 200 で、レスポンスは JSON 形式で返されます。次の表に、レスポンスパラメーターを示します。
パラメーター
説明
metric
メトリック名。
tags
値が集計されなかったタグ。
aggregateTags
値が集計されたタグ。
dps
データポイントに対応するタグのキーと値のペア。
サンプルレスポンス:
[ { "metric": "tsd.hbase.puts", // メトリック名 "tags": {"appName": "hitsdb"}, // タグ "aggregateTags": [ "host" // 集計タグ ], "dps": { "1365966001": 25595461080, // データポイント "1365966061": 25595542522, // データポイント "1365966062": 25595543979, // データポイント "1365973801": 25717417859 // データポイント } }
パラメーター: hint
シナリオ
ほとんどの場合、クエリヒントはクエリのレスポンスタイムを短縮するために使用されます。たとえば、タグ A とタグ B が指定されており、タグ B によってヒットされた時系列がタグ A によってヒットされた時系列に明らかに含まれているとします。この場合、タグ A によってヒットされた時系列からデータは読み取られません。タグ A によってヒットされた時系列のセットとタグ B によってヒットされた時系列のセットの共通部分は、タグ B によってヒットされた時系列のセットと同じです。
形式の説明
現在の TSDB バージョンでは、ヒントで tagk パラメーターのみを使用してクエリインデックスを制限できます。
tagk パラメーターで指定されたタグのキーと値のペアでは、タグキーのタグ値は同じである必要があります。有効な値: 0 と 1。タグ値が
0の場合、タグキーに対応するインデックスは使用されません。タグ値が1の場合、タグキーに対応するインデックスが使用されます。
バージョン説明
クエリヒント機能は、TSDB V2.6.1 以降でサポートされています。
サンプルリクエスト
サブクエリに適用されるヒント
{
"start": 1346846400, // 開始時刻
"end": 1346846400, // 終了時刻
"queries": [
{
"aggregator": "none", // 集計関数
"metric": "sys.cpu.nice",// メトリック名
"tags": {
"dc": "lga", // データセンタータグ
"host": "web01" // ホストタグ
},
"hint": {
"tagk": {
"dc": 1 // データセンタータグのヒント
}
}
}
]
}クエリ全体に適用されるヒント
{
"start": 1346846400, // 開始時刻
"end": 1346846400, // 終了時刻
"queries": [
{
"aggregator": "none", // 集計関数
"metric": "sys.cpu.nice",// メトリック名
"tags": {
"dc": "lga", // データセンタータグ
"host": "web01" // ホストタグ
}
}
],
"hint": {
"tagk": {
"dc": 1 // データセンタータグのヒント
}
}
}例外
tagk パラメーターで指定されたキーと値のペアのタグ値に 0 と 1 の両方が含まれている場合、エラーが返されます。
{
"start": 1346846400, // 開始時刻
"end": 1346846400, // 終了時刻
"queries": [
{
"aggregator": "none",// 集計関数
"metric": "sys.cpu.nice", // メトリック名
"tags": {
"dc": "lga", // データセンタータグ
"host": "web01" // ホストタグ
}
}
],
"hint": {
"tagk": {
"dc": 1, // データセンタータグのヒント
"host": 0 // ホストタグのヒント
}
}
}次のエラーメッセージが返されます。
{
"error": {
"code": 400,
"message": "ヒントの値は 0 または 1 のみである必要があり、0 と 1 の両方があってはなりません",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
} tagk パラメーターで指定されたキーと値のペアのタグ値が 0 または 1 でない場合、エラーが返されます。
{
"start": 1346846400, // 開始時刻
"end": 1346846400, // 終了時刻
"queries": [
{
"aggregator": "none",// 集計関数
"metric": "sys.cpu.nice", // メトリック名
"tags": {
"dc": "lga", // データセンタータグ
"host": "web01" // ホストタグ
}
}
],
"hint": {
"tagk": {
"dc": 100 // データセンタータグのヒント
}
}
}次のエラーメッセージが返されます。
{
"error": {
"code": 400,
"message": "ヒントの値は 0 または 1 のみで、'100' が渡されたことが検出されました",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
}パラメーター: forecasting
AI トレーニングを実行して、将来の期間の時系列のデータポイントを予測できます。AI トレーニング中、時系列の既存のデータをトレーニングセットとして使用して、データの傾向とデータサイクルを特定します。次のサンプルコードは、クエリの形式の例を示しています。
<AlgorithmName>-<ForecastPointCount>[-<ForecastPolicy>] 次のリストでは、クエリのフィールドについて説明します。
AlgorithmName: アルゴリズムの名前。 arima アルゴリズムと holtwinters アルゴリズムがサポートされています。
ForecastPointCount: 予測されるデータポイントの数。整数を指定します。たとえば、値 2 は 2 つのデータポイントが予測されることを指定します。
ForecastPolicy: 予測ポリシー。 予測ポリシーは、指定されたアルゴリズムによって異なります。
AlgorithmName パラメーターが arima に設定されている場合、ForecastPolicy パラメーターの値は次の形式になります。
説明delta パラメーターは、2 つの値の差を指定します。デフォルトのデルタは 1 です。デルタを増やしてデータの変動を減らすことができます。
seasonality パラメーターは、変動のサイクルを指定します。デフォルト値は 1 です。データが定期的に変動する場合は、seasonality パラメーターを指定して予測サイクルを調整できます。たとえば、データが 10 データポイントごとに 1 回変動する場合は、seasonality パラメーターを 10 に設定します。
AlgorithmName パラメーターが holtwinter に設定されている場合、ForecastPolicy パラメーターの値は次の形式になります。
説明seasonality パラメーターは、変動のサイクルを指定します。デフォルト値は 1 です。データが定期的に変動する場合は、seasonality パラメーターを指定して予測サイクルを調整できます。たとえば、データが 10 データポイントごとに 1 回変動する場合は、seasonality パラメーターを 10 に設定します。
予測の例
例: arima-1、arima-48-1-48、および holtwinters-1-1 次のコードは、シリーズの既存データの例を示しています。
[
{
"metric": "sys.cpu.nice", // メトリック名
"tags": {
"dc": "lga", // データセンタータグ
"host": "web00" // ホストタグ
},
"aggregateTags": [],
"dps": {
"1346837400": 1, // データポイント
"1346837401": 2, // データポイント
"1346837402": 3, // データポイント
"1346837403": 4, // データポイント
"1346837404": 5, // データポイント
"1346837405": 6, // データポイント
"1346837406": 7, // データポイント
"1346837407": 8, // データポイント
"1346837408": 9, // データポイント
"1346837409": 10, // データポイント
"1346837410": 11, // データポイント
"1346837411": 12 // データポイント
}
}
]次のコードは、クエリ条件を示しています。
{
"start":1346837400, // 開始時刻
"end": 1346847400, // 終了時刻
"queries":[
{
"aggregator":"none", // 集計関数
"metric":"sys.cpu.nice", // メトリック名
"forecasting" : "arima-1" // 予測設定
}
]
}予測結果は、予測結果を示しています。
[
{
"metric": "sys.cpu.nice", // メトリック名
"tags": {
"dc": "lga", // データセンタータグ
"host": "web00" // ホストタグ
},
"aggregateTags": [],
"dps": {
"1346837400": 1, // データポイント
"1346837401": 2, // データポイント
"1346837402": 3, // データポイント
"1346837403": 4, // データポイント
"1346837404": 5, // データポイント
"1346837405": 6, // データポイント
"1346837406": 7, // データポイント
"1346837407": 8, // データポイント
"1346837408": 9, // データポイント
"1346837409": 10, // データポイント
"1346837410": 11, // データポイント
"1346837411": 12, // データポイント
"1346837412": 13 // 予測データポイント
}
}
]パラメーター: abnormaldetect
AI トレーニングを実行して、将来の期間の時系列のデータポイントを予測できます。AI トレーニング中、時系列の既存のデータをトレーニングセットとして使用して、データの傾向とデータサイクルを特定します。次のサンプルコードは、クエリの形式の例を示しています。
<AlgorithmName>[-<Sigma>-<NP>-<NS>-<NT>-<NL>]異常検出には、Standard Template Library (STL) アルゴリズムのみがサポートされています。パラメーターチューニングに慣れていない場合は、デフォルトのパラメーター値を選択することをお勧めします。STL アルゴリズムに精通している場合は、パラメーターを調整して より正確な予測 を有効にすることができます。異常検出には、AlgorithmName-Sigma-NP-NS-NT-NL の 6 つのパラメーターが用意されています。たとえば、パラメーターを stl-5-5-7-0-0 に設定できます。これらのパラメーターはハイフン (-) で区切ります。次のリストでは、6 つのパラメーターについて説明します。
Sigma: データポイントの値と時系列のすべての値の平均値の差の絶対値が時系列の標準偏差の 3 倍大きい場合、このデータポイントは異常なポイントと見なされます。ほとんどの場合、このパラメーターの値は 3.0 です。
NP: 各サイクルのデータポイントの数。サイクル数は、データポイントの数を決定するために使用されます。
NS: 季節的スムージングパラメーター。
NT: トレンドスムージングパラメーター。
NL: ローパスフィルタースムージングパラメーター。
予測の例
例 1
"abnormaldetect": "stl",例 2
"abnormaldetect": "stl-5-5-7-0-0",クエリの例
{
"start":1346836400, // 開始時刻
"end":1346946400, // 終了時刻
"queries":[
{
"aggregator": "none", // 集計関数
"metric": "sys.cpu.nice", // メトリック名
"abnormaldetect": "stl-5-5-7-0-0", // 異常検出設定
"filters": [
{
"type": "literal_or", // フィルタータイプ
"tagk": "dc", // タグキー
"filter": "lga", // フィルター
"groupBy": false // グループ化するかどうか
},
{
"type": "literal_or", // フィルタータイプ
"tagk": "host", // タグキー
"filter": "web00", // フィルター
"groupBy": false // グループ化するかどうか
}
]
}
]
}出力例
TSDB の異常検出の結果は、次の形式のリストです。
[srcValue, upperValue, lowerValue, predictValue, isAbnormal]
srcValue: 元のデータポイントの値。
upperValue: データポイントの最大値。
lowerValue: データポイントの最小値。
predictValue: STL アルゴリズムによって予測されたデータポイント値。
isAbnormal: 元の値が異常かどうかを指定します。値 0 は、元の値が正常であることを示します。値 1 は、元の値が異常であることを示します。
[ { "metric": "sys.cpu.nice", // メトリック名 "tags": { "dc": "lga", // データセンタータグ "host": "web00" // ホストタグ }, "aggregateTags": [], "dps": { "1346837400": [ 1, // 元の値 1.0000000000000049, // 上限値 0.9999999999999973, // 下限値 1.0000000000000013, // 予測値 0 // 異常かどうか ], "1346837401": [ 2, // 元の値 2.0000000000000036, // 上限値 1.9999999999999958, // 下限値 1.9999999999999998, // 予測値 0 // 異常かどうか ], // ... (その他のデータポイント) } } ]