2.7.4　IM管理ノードごとのトレンドデータの管理

〈この項の構成〉

(1)　トレンドデータ管理DBに格納するデータ
(2)　トレンドデータ管理DBに格納したデータの取り出し
(3)　トレンドデータの書き込み機能
(4)　トレンドデータの参照機能
(5)　トレンドデータの削除機能
(6)　トレンドデータオブジェクトについて
(7)　PromQLについて

(1)　トレンドデータ管理DBに格納するデータ

トレンドデータ管理DBに格納するトレンドデータ（時系列データ）は，メトリック名とラベルによって一意に識別されます。また，ラベルを使用して，IM管理ノードとトレンドデータの紐づけが行われます。トレンドデータの参照時は，ラベルを指定して，IM管理ノードに紐づいたトレンドデータを取得できます。

メトリック名とラベルの形式と例を，次に示します。

メトリック名とラベルの形式

メトリック名{ラベル名="ラベル値" ラベル名="ラベル値"…}

メトリック名とラベルの例

windows_logical_disk_free_bytes{instance="host1:9001" volume="C:"}
windows_logical_disk_free_bytes{instance="host1:9001" volume="D:"}
windows_logical_disk_free_bytes{instance="host2:9001" volume="C:"}

トレンドデータ（時系列データ）は，複数のサンプルで形成されます。各サンプルは，次の項目で構成されます。

ミリ秒精度のタイムスタンプ（UNIX時間）
float64型（倍精度浮動小数型）の値（パフォーマンスデータ）

時系列データの例を，次に示します。

表2‒14　時系列データの例
メトリック名			windows_logical_disk_free_bytes
ラベルと値			instance="host1:9001" volume="C:"	instance="host1:9001" volume="D:"	instance="host2:9001" volume="C:"
時系列データ	サンプル	タイムスタンプ	`1624260855`	`1624260855`	`1624260855`
	サンプル	パフォーマンスデータ	`55153717248.0`	`923198898.0`	`194208931840.0`
	サンプル	タイムスタンプ	`1624260870`	`1624260870`	`1624260870`
	サンプル	パフォーマンスデータ	`55151808512.0`	`923162116.0`	`194208688168.0`
	サンプル	タイムスタンプ	`1624260885`	`1624260885`	`1624260885`
	サンプル	パフォーマンスデータ	`55153377280.0`	`923146812.0`	`194208931976.0`
	サンプル	タイムスタンプ	`1624260900`	`1624260900`	`1624260900`
	サンプル	パフォーマンスデータ	`55157182464.0`	`923138684.0`	`194208921684.0`

ページの先頭へ

(2)　トレンドデータ管理DBに格納したデータの取り出し

トレンドデータ管理DBに格納したデータの取り出しには，Prometheusのクエリ（PromQL）を使用します。サポートするPromQLの言語仕様については，「2.7.4(7)PromQLについて」を参照してください。

PromQLでは，トレンドデータを，次の2つの型で取り出せます。

instant Vector型での取得

ある時点（通常はデータの取得時点）のパフォーマンスデータの集合を表します。

例えば，「表2-14 時系列データの例」では，タイムスタンプ「1624260855」に対するパフォーマンスデータ「55153717248.0」，「923198898.0」，「194208931840.0」の集合を指します。
range Vector型での取得

ある時点（通常はデータの取得時点）からさかのぼった複数時点のパフォーマンスデータの集合を表します。

例えば，「表2-14 時系列データの例」では，タイムスタンプ「1624260885」に対するパフォーマンスデータ「55153377280.0」，「923146812.0」，「194208931976.0」と，タイムスタンプ「1624260900」に対するパフォーマンスデータ「55157182464.0」，「923138684.0」，「194208921684.0」を合わせた集合を指します。

トレンドデータの取得には，メトリック名とラベルを指定することで，特定のラベルを持つものだけをフィルタリングして取得できます。

指定したラベルに一致するトレンドデータが存在しない場合，トレンドデータは返却されません（トレンドデータが存在しない場合に，パフォーマンスデータが0で返却されることはありません）。

例えば，「表2-14 時系列データの例」に示す時系列データを対象に，PromQL文に"windows_logical_disk_free_bytes{volume="C:"}"を指定してフィルタリングすると，次に示す「volume="C:"」を含むラベルに対応するパフォーマンスデータの集合を取得できます。

ラベル「instance="host1:9001" volume="C:"」に対応するパフォーマンスデータ「55153717248.0」，「55151808512.0」，「55153377280.0」，「55157182464.0」
ラベル「instance="host2:9001" volume="C:"」に対応するパフォーマンスデータ

「194208931840.0」，「194208688168.0」，「194208931976.0」，「194208921684.0」

また，取り出したトレンドデータは，PromQL文の集計演算子，オペレーター，または関数を使用して集計または演算することで，さまざまな集計結果を取得できます。

注意事項

JP1/IM - Managerが提供するAPIで指定するPromQL文は，最終的な集計結果のデータがinstant Vector型となるように記述する必要があります。

また，取得したデータがrange Vector型の場合，集計演算子，オペレーター，または関数を使用して，最終的な集計結果のデータがinstant Vector型となるように，PromQL文を作成する必要があります。

ページの先頭へ

(3)　トレンドデータの書き込み機能

トレンドデータをトレンドデータ管理DBに書き込む機能です。

JP1/IM - Managerのトレンドデータ書き込みのREST APIを使用し，トレンドデータ管理サービス（Promscale）を経由して，トレンドデータをトレンドデータ管理DBに書き込みます。

トレンドデータ書き込みのAPIの詳細については，マニュアル「JP1/Integrated Management 3 - Manager コマンド・定義ファイル・APIリファレンス」の「5.11.3　トレンドデータ書き込み」を参照してください。

トレンドデータ管理DBに書き込むデータを，次に示します。

データの種類	説明	複数指定	省略可否
メトリクス名	トレンドデータの種別を表す情報です。	不可	不可
ラベル	トレンドデータの発行元ホストなど，トレンドデータの付加情報です。「ラベル名:ラベル値」の形式のデータです。	可	可
トレンドデータ（時系列データ）	「時刻,値」の形式のデータです。	可	不可

データの種類

説明

複数指定

省略可否

メトリクス名

トレンドデータの種別を表す情報です。

不可

ラベル

トレンドデータの発行元ホストなど，トレンドデータの付加情報です。

「ラベル名:ラベル値」の形式のデータです。

可

トレンドデータ（時系列データ）

「時刻,値」の形式のデータです。

可

不可

トレンドデータの書き込み処理は，複数同時に実行できます。データ書き込みの排他制御は，トレンドデータ管理DB内で行います。

ページの先頭へ

(4)　トレンドデータの参照機能

トレンドデータをトレンドデータ管理DBから参照する機能です。

製品プラグインで使用できるjp1TrendDataService.getTrendDataメソッドを使用し，トレンドデータ管理サービス（Promscale）を経由して，トレンドデータ管理DBからトレンドデータを参照します。JP1/IM - Manager（インテリジェント統合管理基盤）は，トレンドデータ管理サービスに対して，REST APIを使用してクエリ（PromQL）を発行し，トレンドデータを取得します。

jp1TrendDataService.getTrendDataメソッドの詳細については，マニュアル「JP1/Integrated Management 3 - Manager コマンド・定義ファイル・APIリファレンス」の「4.5.17　jp1TrendDataService.getTrendData」を参照してください。

トレンドデータの参照処理は，書き込み処理と同時に実行できます。参照できるデータは，トレンドデータ管理DBが参照要求を受け付けた時点で，書き込みが完了しているデータとなります。

■IM管理ノードに紐づくトレンドデータの参照

トレンドデータ管理DBからトレンドデータを取得するjp1TrendDataService.getTrendDataメソッドで，引数promQLQueryに指定するPromQL文内に，置き換え文字列「$jp1im_TrendData_labels」を設定することで，IM管理ノードに紐づくトレンドデータを参照できます。

ページの先頭へ

(5)　トレンドデータの削除機能

「2.7.2(3)トレンドデータの削除」を参照してください。

ページの先頭へ

(6)　トレンドデータオブジェクトについて

マニュアル「JP1/Integrated Management 3 - Manager コマンド・定義ファイル・APIリファレンス」の「7.2.3(1)トレンドデータオブジェクト」を参照してください。

ページの先頭へ

(7)　PromQLについて

(a)　メトリック名とラベルの指定によるトレンドデータの取得

Prometheusのクエリ（PromQL）では，トレンドデータを，次の2つの型で取得できます。

instant Vector型での取得

ある時点のパフォーマンスデータ（instant Vector）を，次のどちらかの形式で取得できます。

メトリック名{ラベル}

メトリック名

JP1/IM - Managerが提供する時系列データ取得のAPIでは，メンバー「startTime」に指定した時系列データの開始日時から，メンバー「step」に指定したトレンドデータの取得間隔（秒）で，メンバー「endTime」に指定した時系列データの終了日時までのパフォーマンスデータを取得します。

取得したデータが小数点以下10桁以上となる場合があります。

取得したデータを切り上げ，切り下げ，または四捨五入をした値にしたい場合はPromQL文の関数（ceil，flor，roundなど）を使用してください。

PromQL文の関数の詳細は，「2.7.4(7)(e)使用できる関数」を参照してください。
range Vector型での取得

ある時点からさかのぼった複数時点のパフォーマンスデータ（range Vector）を，次のどちらかの形式で取得できます。

メトリック名{ラベル}[さかのぼる時刻^※]

メトリック名[さかのぼる時刻^※]

注※

さかのぼる時刻は数値と単位（s，m，h，d，w，またはy）で指定します。

(b)　SIDに紐づくラベルの置き換え

JP1/IM - Managerで提供するAPIでは，PromQL文内に指定するラベルに，置き換え文字列「$jp1im_TrendData_labels」を使用できます。

PromQL文内に置き換え文字列「$jp1im_TrendData_labels」を指定した場合，BNF記法で示す次の文字列に置き換えられます。

<$jp1im_TrendData_labels>     ::= {__name__=~".+"} | (<condition>)
<condition>      ::= { <key_value_list> } | <condition> or { <key_value_list> }
<key_value_list> ::= <key_value> | <key_value_list>, <key_value >
<key_value>      ::= KEY="VALUE^※"

注※: VALUEの値に含まれるバックスラッシュ（\）は「\\」に，ダブルクォーテーション（"）は「\"」に置き換えられてPromQLに指定されます。

SIDに指定したラベルの数，およびSIDの数に応じて，置き換えられる文字列を，次に示します。

■SIDに指定したラベルの数が1の場合

SIDの数が1の場合

{KEY1=VALUE1}
SIDの数が2以上の場合

{SID1.KEY1=SID1.VALUE1} または

{SID2.KEY1=SID2.KEY2} ...
SIDの数が0の場合

トレンドデータ管理サービス（Promscale）にクエリ（PromQL）を発行せず，0件のデータを返却します。

■SIDに指定したラベルの数が2以上の場合

SIDの数が1の場合

{KEY1=VALUE1,KEY2=VALUE2 ...}
SIDの数が2以上の場合

{SID1.KEY1=SID1.VALUE1,SID1.KEY2=SID1.VALUE2...} または

{SID2.KEY1=SID2.VALUE1,SID2.KEY2=SID2.VALUE2...} ...
SIDの数が0の場合

トレンドデータ管理サービス（Promscale）にクエリ（PromQL）を発行せず，0件のデータを返却します。

■SIDに指定したラベルの数が0の場合

SIDの数が1以上の場合

{__name__=~".+"}
SIDの数が0の場合

トレンドデータ管理サービス（Promscale）にクエリ（PromQL）を発行せず，0件のデータを返却します。

■SIDに指定したラベルの数が2以上で，あるものとないものが混在している場合

SIDの数が2以上の場合

{__name__=~".+"}
上記以外

該当せず。

注意事項

JP1/IM - Managerが提供するAPIで指定するPromQL文は，最終的な集計結果のデータがinstant Vector型となるように記述する必要があります。

(c)　使用できる集計演算子

PromQLで使用できる集計演算子を，次に示します。集計演算子を使用して，取得したデータの集計ができます。

演算子	説明
sum	合計を返却します。
count	性能値の数を返却します。
avg	平均値を返却します。
min	最小値を返却します。
max	最大値を返却します。

上記の集計演算子には，次に示すラベル指定ができます。

by ラベル名

指定したラベルごとに集計を行います。
without ラベル名

指定したラベルを無視して集計を行います。

(d)　使用できるオペレーター

PromQLで使用できるオペレーターを，次に示します。オペレーターを使用して，性能値の計算ができます。

■演算対象

演算対象の組み合わせによって，オペレーターの動作が異なります。演算対象の組み合わせごとのオペレーターの動作を，次に示します。

演算対象の組み合わせ	instant Vector	range Vector	scalar
instant Vector	ラベルごとに加算	エラー	ラベルごとにscalarの値を加算
range Vector	エラー	ラベル，タイムスタンプごとに加算	ラベル，タイムスタンプごとに加算
scalar	ラベルごとにscalarの値を加算	ラベル，タイムスタンプごとに加算	scalar同士を加算

■ラベルに対する操作

instant Vector同士，range Vector同士の計算では，ラベルに対して次の操作を指定できます。

ignoring

指定したラベルだけを無視して計算を行う。
on

指定したラベルだけを考慮して計算を行う。

■演算子

使用できる演算子を，次に示します。

演算子	説明
`+`	instant Vector同士，range Vector同士の場合同一ラベルの値をそれぞれ加算します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値にscalarの値をそれぞれ加算します。 scalar同士の場合値をそのまま加算します。上記以外演算エラーを返却します。
`-`	instant Vector同士，range Vector同士の場合同一ラベルの値を減算します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値からscalarの値を減算します。 scalar同士の場合値をそのまま減算します。上記以外演算エラーを返却します。
`*`	instant Vector同士，range Vector同士の場合同一ラベルの値を乗算します。 instant Vectorとscalar，instant Vectorとscalarの場合 scalarの値でVectorの各性能値を乗算します。 scalar同士の場合値をそのまま乗算します。上記以外演算エラーを返却します。
`/`	instant Vector同士，range Vector同士の場合同一ラベルの値を除算します。 instant Vectorとscalar，instant Vectorとscalarの場合 scalarの値でVectorの各性能値を除算します。 scalar同士の場合値をそのまま除算します。上記以外演算エラーを返却します。
`%`	instant Vector同士，range Vector同士の場合同一ラベルの値の剰余を求めます。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値をscalarの値で割った剰余を求めます。 scalar同士の場合値の剰余を求めます。上記以外演算エラーを返却します。
`^`	instant Vector同士，range Vector同士の場合同一ラベル間で左辺の値の「右辺の値」乗を返却します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値の「scalarの値」乗を返却します。 scalar同士の場合左辺の値の「右辺の値」乗を返却します。上記以外演算エラーを返却します。

■比較子

使用できる比較子を，次に示します。

比較子	説明
`==`	instant Vector同士，range Vector同士の場合同一ラベル間で値が同じデータだけを返却します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値のうち，値が「scalarの値」となっているものを返却します。 scalar同士の場合：演算エラーを返却します。bool修飾子を指定する必要があります。上記以外演算エラーを返却します。
`!=`	instant Vector同士，range Vector同士の場合同一ラベル間で値が異なるデータだけを返却します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値のうち，値が「scalarの値」となっていないものを返却します。 scalar同士の場合：演算エラーを返却します。bool修飾子を指定する必要があります。上記以外演算エラーを返却します。
`>`	instant Vector同士，range Vector同士の場合 Vectorの性能値を比較し，右辺より左辺の方が大きいデータだけを返却します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値のうち，scalarの値より大きいデータだけを返却します。 scalar同士の場合：演算エラーを返却します。bool修飾子を指定する必要があります。上記以外演算エラーを返却します。
`<`	instant Vector同士，range Vector同士の場合 Vectorの性能値を比較し，右辺より左辺の方が小さいデータだけを返却します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値のうち，scalarの値より小さいデータだけを返却します。 scalar同士の場合：演算エラーを返却します。bool修飾子を指定する必要があります。上記以外演算エラーを返却します。
`>=`	instant Vector同士，range Vector同士の場合 Vectorの性能値を比較し，右辺より左辺の方が大きい，または同じ値のデータだけを返却します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値のうち，scalarの値より大きい，または同じ値のデータだけを返却します。 scalar同士の場合：演算エラーを返却します。bool修飾子を指定する必要があります。上記以外演算エラーを返却します。
`<=`	instant Vector同士，range Vector同士の場合 Vectorの性能値を比較し，右辺より左辺の方が小さい，または同じ値のデータだけを返却します。 instant Vectorとscalar，instant Vectorとscalarの場合 Vectorの各性能値のうち，scalarの値より小さい，または同じ値のデータだけを返却します。 scalar同士の場合：演算エラーを返却します。bool修飾子を指定する必要があります。上記以外演算エラーを返却します。

■論理演算子

使用できる論理演算子を，次に示します。

演算子	説明
and	対応する右辺にデータがある場合だけ左辺のデータを返却します。
or	左辺がサンプルを持っている場合は左辺のデータ，左辺がサンプルを持っていない場合は右辺のデータを返却します。
unless	右辺にデータがある場合はデータを返却せず，右辺にデータがない場合だけ左辺のデータを返却します。

(e)　使用できる関数

PromQLで使用できる関数を，次に示します。

関数名	説明	引数の型^※	戻り値の型^※
abs	性能値を絶対値にします。	instant Vector	instant Vector
absent_over_time	期間が指定されている時系列データのすべてに対して，性能値がある場合は性能値を返却し，性能値がない場合は値1の要素を返却します。	range Vector	instant Vector
avg_over_time	期間内の値の平均を返却します。	range Vector	instant Vector
ceil	性能値を小数点以下で切り上げをして返却します。	instant Vector	instant Vector
changes	値が変更された数を返却します。	range Vector	instant Vector
clamp	Vector内の性能値が，最小値以下だった場合は最小値，最大値以上だった場合は最大値に，それぞれ丸め込みます。	第1引数 instant Vector 第2引数 scalar 第3引数 scalar	instant Vector
clamp_max	Vector内の性能値が，最大値以上だった場合，最大値に丸め込みます。	第1引数 instant Vector 第2引数 scalar	instant Vector
clamp_min	Vector内の性能値が，最小値以下だった場合，最小値に丸め込む。	第1引数 scalar 第2引数 scalar	instant Vector
count_over_time	指定した期間のデータの個数を返却します。	range Vector	instant Vector
delta	指定した期間の先頭と最後の値の差を返却します。	range Vector	instant Vector
floor	性能値を小数点以下で切り下げをして返却します。	instant Vector	instant Vector
increase	指定した期間の値の増加量を返却します。	range Vector	instant Vector
irate	（1つ前の性能値だけと比較して）指定した期間の1秒当たりの増加率を返却します。	range Vector	instant Vector
label_replace	各時系列データに対して，ラベルを正規表現で置換します。第1引数：対象データ第2引数：置換先ラベル名第3引数：置換後の文字列第4引数：置換元のラベル名第5引数：置換元の文字列（正規表現）	第1引数 instant Vector 第2引数以降 string	instant Vector
label_join	各時系列データに対して，ラベルを結合します。第1引数：対象データ第2引数：結合先ラベル第3引数：セパレータ文字列第4引数以降：結合元ラベル	第1引数 instant Vector 第2引数以降 string	instant Vector
max_over_time	時系列データの各範囲で，最大のデータを返却します。	range Vector	instant Vector
min_over_time	時系列データの各範囲で，最小のデータを返却します。	instant Vector	instant Vector
predict_linear	第1引数に指定したメトリックの性能値から，第2引数に指定した秒数後の性能値を予測して返却します。第1引数には，メトリックの型がGaugeのメトリックを指定してください。	第1引数 range Vector 第2引数 scalar	instant Vector
rate	指定した期間の1秒当たりの増加率を返却します。	range Vector	instant Vector
resets	性能値がリセット（減少）した回数を返却します。	range Vector	instant Vector
round	各性能値を小数点以下で四捨五入した値を返却します。	第1引数 instant Vector 第2引数以降 scalar	instant Vector
sum_over_time	合計を返却します。	range Vector	instant Vector

注※

instant Vector

特定の時刻におけるデータです。
range Vector

複数の時刻におけるデータです。instant Vectorのデータが複数時刻分まとまったものです。
scalar

数値です。
string

文字列です。

ページの先頭へ

2.7.4 IM管理ノードごとのトレンドデータの管理

(1) トレンドデータ管理DBに格納するデータ

(2) トレンドデータ管理DBに格納したデータの取り出し

(3) トレンドデータの書き込み機能

(4) トレンドデータの参照機能

(5) トレンドデータの削除機能

(6) トレンドデータオブジェクトについて

(7) PromQLについて

(a) メトリック名とラベルの指定によるトレンドデータの取得

(b) SIDに紐づくラベルの置き換え

(c) 使用できる集計演算子

(d) 使用できるオペレーター

(e) 使用できる関数

2.7.4　IM管理ノードごとのトレンドデータの管理

(1)　トレンドデータ管理DBに格納するデータ

(2)　トレンドデータ管理DBに格納したデータの取り出し

(3)　トレンドデータの書き込み機能

(4)　トレンドデータの参照機能

(5)　トレンドデータの削除機能

(6)　トレンドデータオブジェクトについて

(7)　PromQLについて

(a)　メトリック名とラベルの指定によるトレンドデータの取得

(b)　SIDに紐づくラベルの置き換え

(c)　使用できる集計演算子

(d)　使用できるオペレーター

(e)　使用できる関数