ダッシュボード

ダッシュボードの作成

ダッシュボードを作成します。

POST /api/v0/dashboards

APIキーに必要な権限

  • Read
  • Write

入力

以下のキーをもつオブジェクト。

KEY TYPE DESCRIPTION
title string ダッシュボード名
memo string ダッシュボードのメモ
urlPath string ダッシュボードのURLのパス *1
widgets array[object] ウィジェットを表すオブジェクトのリスト

*1 urlPath のフォーマットは以下の通りです:

^([A-Za-z0-9_][-A-Za-z0-9_]*)(/[A-Za-z0-9_][-A-Za-z0-9_]*)*$

応答

成功時

作成されたダッシュボードを返します。

KEY TYPE DESCRIPTION
id string ダッシュボードのID *1
title string ダッシュボード名
memo string ダッシュボードのメモ
urlPath string ダッシュボードのURLのパス
widgets array[object] ウィジェットを表すオブジェクトのリスト
createdAt number 作成時刻（エポック秒）
updatedAt number 最終更新時刻（エポック秒）

*1 id は新しく作成されたダッシュボードに割り当てられたIDです。以降のリクエストではこのIDを用いてダッシュボードを識別します。

失敗時

STATUS CODE DESCRIPTION
400 入力が不正だったとき
403 作成できるダッシュボード数の上限に達しているとき / APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
409 urlPath に指定したURLのパスに既に他のダッシュボードが存在しているとき

ダッシュボードの取得

GET /api/v0/dashboards/<dashboardId>

APIキーに必要な権限

  • Read

応答

成功時

ダッシュボードの作成と同様の形式です。

失敗時

STATUS CODE DESCRIPTION
404 指定されたIDのダッシュボードがみつからないとき

ダッシュボードの更新

PUT /api/v0/dashboards/<dashboardId>

APIキーに必要な権限

  • Read
  • Write

入力

ダッシュボードの作成と同様の形式です。

応答

成功時

更新後のダッシュボードをダッシュボードの作成と同様の形式で返します。

失敗時

STATUS CODE DESCRIPTION
400 入力が不正だったとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
404 指定されたIDのダッシュボードがみつからないとき
409 urlPath に指定したURLのパスに既に他のダッシュボードが存在しているとき

ダッシュボードの削除

指定されたIDのダッシュボードを削除します。

DELETE /api/v0/dashboards/<dashboardId>

APIキーに必要な権限

  • Read
  • Write

応答

成功時

削除する直前のダッシュボードをダッシュボードの作成と同様の形式で返します。

失敗時

STATUS CODE DESCRIPTION
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
404 指定されたIDのダッシュボードがみつからないとき

ダッシュボードの一覧

GET /api/v0/dashboards

APIキーに必要な権限

  • Read

応答

KEY TYPE DESCRIPTION
dashboards array[object] ダッシュボードのリスト

それぞれのダッシュボードをダッシュボードの作成と同様の形式で返します。

ウィジェット

ウィジェットを表すオブジェクトは、各ウィジェットの種類ごとに、以下の形式となっています。

グラフウィジェット

KEY TYPE DESCRIPTION
type string 固定文字列 "graph"
title string ウィジェットのタイトル
graph object グラフを表すオブジェクト
range object [optional] グラフの表示期間を表すオブジェクト
valueRange object [optional] グラフの縦軸固定を表すオブジェクト
referenceLines array[object] [optional] 補助線を表すオブジェクトの配列。補助線の設定を削除したい場合には、空の配列を指定してください。
ダッシュボードの取得時に補助線が未設定の場合、空の配列が返されます。配列に2つ以上の要素を指定できません。
layout object レイアウトを表すオブジェクト

数値ウィジェット

KEY TYPE DESCRIPTION
type string 固定文字列 "value"
title string ウィジェットのタイトル
metric object メトリックを表すオブジェクト
fractionSize number [optional] 表示する小数点以下の桁数 (0–16)
suffix string [optional] 数値の後に表示する単位
formatRules array[object] [optional] フォーマットルールを表すオブジェクトの配列。フォーマットルールの設定を削除したい場合には、空の配列を指定してください。
ダッシュボードの取得時にフォーマットルールが未設定の場合、空の配列が返されます。配列に2つ以上の要素を指定できません。
layout object レイアウトを表すオブジェクト

Markdownウィジェット

KEY TYPE DESCRIPTION
type string 固定文字列 "markdown"
title string ウィジェットのタイトル
markdown string Markdown形式の文字列
layout object レイアウトを表すオブジェクト

アラートステータスウィジェット

KEY TYPE DESCRIPTION
type string 固定文字列 "alertStatus"
title string ウィジェットのタイトル
roleFullname string サービス名とロール名を:で連結したもの
ただし、ダッシュボード取得時に関連するロールやサービスが削除されていた場合、roleFullname には null が設定されます。
layout object レイアウトを表すオブジェクト

グラフ

ホストグラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "host"
hostId string ホストのID
name string グラフ名（"loadavg" など）

ロールグラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "role"
roleFullname string サービス名とロール名を:で連結したもの
name string グラフ名（"loadavg5" など）
isStacked boolean [optional] グラフが積み重ねグラフ / 線グラフのどちらか。true の場合、積み重ねグラフになります

サービスグラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "service"
serviceName string サービス名
name string グラフ名

式グラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "expression"
expression string グラフを表す式

クエリグラフ

KEY TYPE DESCRIPTION
type string 固定文字列 "query"
query string PromQL 形式のクエリ
legend string クエリの凡例。{{ }} で囲んだ箇所にラベルのキーを指定することで、ラベルの値に展開できます。例: { http.method: "GET" } というラベルがあるとき、legend に method: {{http.method}} を指定すると、method: GET と展開されます。

これらに加えて、ダッシュボード取得時に関連するロール・サービス・グラフ定義が削除されていた場合、次の結果が返却されることがあります。

KEY TYPE DESCRIPTION
type string 固定文字列 "unknown"

グラフの表示期間

未指定の場合は可変となり、ダッシュボード上部に表示されるコントローラーから表示期間を変更できるようになります。

相対

KEY TYPE DESCRIPTION
type string 固定文字列 "relative"
period number 期間の長さ（秒）
offset number 現在時刻からの差（秒）

（現在時刻 + offset - period）から（現在時刻 + offset）までの期間が表示されます。 offset に負の値を指定することで、過去の指定期間のグラフを表示できます。

絶対

KEY TYPE DESCRIPTION
type string 固定文字列 "absolute"
start number 開始時刻（エポック秒）
end number 終了時刻（エポック秒）

start から end までの期間が表示されます。

グラフの縦軸固定

未指定の場合はメトリックの値に合わせて自動で縦軸が設定されます。

KEY TYPE DESCRIPTION
min number [optional] 縦軸の最小値
max number [optional] 縦軸の最大値

グラフの補助線

グラフの補助線を指定した場合、指定した値を基準として水平線が描画されます。

KEY TYPE DESCRIPTION
label string 補助線のラベル
value number 補助線の値

ラベル名について

ラベル名は下記の条件に従う必要があります。

  • 空白文字を除いて1文字以上であること
  • 32文字以下であること

値について

値は下記の条件に従う必要があります。

  • 0以上であること

フォーマットルール

値のフォーマットルールを指定した場合、設定した条件式を満たす場合に強調したスタイルに変更されます。 例えば、threshold に 10 を指定し、operator に ">" を指定した場合、数値が 10 より大きい場合に強調したスタイルに変更されます。

KEY TYPE DESCRIPTION
name string [optional] フォーマットルールの名前
threshold number 条件の基準となる値
operator string 強調したスタイルが適用される条件を指定。">" または "<"。

名前について

名前は下記の条件に従う必要があります。

  • 32文字以下であること

メトリック

ホストメトリック

KEY TYPE DESCRIPTION
type string 固定文字列 "host"
hostId string ホストのID
name string メトリック名（"loadavg5" など）

サービスメトリック

KEY TYPE DESCRIPTION
type string 固定文字列 "service"
serviceName string サービス名
name string メトリック名

式

KEY TYPE DESCRIPTION
type string 固定文字列 "expression"
expression string メトリックを表す式

クエリ

KEY TYPE DESCRIPTION
type string 固定文字列 "query"
query string PromQL 形式のクエリ
legend string クエリの凡例。{{ }} で囲んだ箇所にラベルのキーを指定することで、ラベルの値に展開できます。例: { http.method: "GET" } というラベルがあるとき、legend に method: {{http.method}} を指定すると、method: GET と展開されます。

式によるメトリック指定を使用して数値を正しく表示するためには、式の結果が単一の系列を表すようにする必要があります。

これらに加えて、ダッシュボード取得時に関連するサービスが削除されていた場合、次の結果が返却されることがあります。

KEY TYPE DESCRIPTION
type string 固定文字列 "unknown"

レイアウト

KEY TYPE DESCRIPTION
x number ウィジェットのx座標
y number ウィジェットのy座標
width number ウィジェットの幅
height number ウィジェットの高さ

座標はウィジェット表示領域の左上を原点（x = 0, y = 0）として、右方向をx軸、下方向をy軸の正の方向として指定します。また、各数値は以下の条件に従う必要があります。条件に従っていない場合、ウィジェットが期待した位置に表示されないことがあります。

  • 各数値が0または正の整数であること
  • ウィジェット表示領域 (幅24) からウィジェットがはみ出さないこと
  • 他のウィジェットと重ならないこと
  • 各ウィジェットの種類ごとに、以下の最小サイズ以上かつ最大サイズ以下であること
ウィジェット width の最小値 height の最小値 width の最大値 height の最大値
グラフ 6 6 24 32
数値 4 4 24 32
Markdown 4 2 24 80
アラートステータス 4 3 24 32