Dashboards

Create Dashboards

This section covers creating dashboards.

POST /api/v0/dashboards

Required permissions for the API key

  • Read
  • Write

Input

Objects that hold the following keys:

KEY TYPE DESCRIPTION
title string the name of the dashboard
memo string notes regarding the dashboard
urlPath string the dashboard's URL path *1
widgets array[object] a list of objects that represent widgets

*1 URL path should be as follows:

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

Response

Success

The dashboard that was created is returned.

KEY TYPE DESCRIPTION
id string the dashboard's ID *1
title string the name of the dashboard
memo string notes regarding the dashboard
urlPath string the dashboard's URL path
widgets array[object] a list of objects that represent widgets
createdAt number the time at which created (in epoch seconds)
updatedAt number the time at which last updated (in epoch seconds)

*1 id is the ID that was assigned to this dashboard. With future requests, this ID will identify the dashboard.

Error

STATUS CODE DESCRIPTION
400 when the input is invalid
403 when you have reached your dashboard limit / when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range
409 when you have specified an already existing URL path

Get Dashboards

GET /api/v0/dashboards/<dashboardId>

Required permissions for the API key

  • Read

Response

Success

Same as Create Dashboards.

Error

STATUS CODE DESCRIPTION
404 when the dashboard corresponding to the designated ID can't be found

Update Dashboards

PUT /api/v0/dashboards/<dashboardId>

Required permissions for the API key

  • Read
  • Write

Input

Same as Create Dashboards.

Response

Success

The updated dashboard is returned. Same format as Create Dashboards.

Error

STATUS CODE DESCRIPTION
400 when the input is invalid
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range
404 when the dashboard corresponding to the designated ID can't be found
409 when you have specified an already existing URL path

Delete Dashboards

This will delete the dashboard corresponding to the designated ID.

DELETE /api/v0/dashboards/<dashboardId>

Required permissions for the API key

  • Read
  • Write

Response

Success

The dashboard before deletion is returned, same as Create Dashboards.

Error

STATUS CODE DESCRIPTION
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range
404 when the dashboard corresponding to the designated ID can't be found

List Dashboards

GET /api/v0/dashboards

Required permissions for the API key

  • Read

Response

KEY TYPE DESCRIPTION
dashboards array[object] a list of the dashboards

Each dashboard is same format as Create Dashboards.


Widgets

Objects representing widgets have the following formats for the differing types.

Graph widget

KEY TYPE DESCRIPTION
type string fixed character string "graph"
title string the title of the widget
graph object object representing a graph
range object [optional] object representing the graph display range
valueRange object [optional] object representing the value range of vertical axis
referenceLines array[object] [optional] array of objects representing the reference line. If you want to remove the reference line setting, specify an empty array.
If reference line is not set when get dashboards, an empty array is returned. Cannot specify more than one element in an array.
layout object object representing the layout

Value widget

KEY TYPE DESCRIPTION
type string fixed character string "value"
title string the title of the widget
metric object object representing a metric
fractionSize number [optional] decimal places displayed on the widget (0–16)
suffix string [optional] the units to be displayed after the value
formatRules array[object] [optional] array of objects representing the format rule. If you want to remove the format rule setting, specify an empty array.
If format rule is not set when get dashboards, an empty array is returned. Cannot specify more than one element in an array.
layout object object representing the layout

Markdown widget

KEY TYPE DESCRIPTION
type string fixed character string "markdown"
title string the title of the widget
markdown string a character string in Markdown format
layout object object representing the layout

Alert Status widget

KEY TYPE DESCRIPTION
type string fixed character string "alertStatus"
title string the title of the widget
roleFullname string the service name and role name linked by :
However, if the relevant role or service has been deleted when the dashboard is retrieved, roleFullname will be set as null.
layout object object representing the layout

Graphs

Host graph

KEY TYPE DESCRIPTION
type string fixed character string "host"
hostId string the host's ID
name string the name of the graph ("loadavg" etc.)

Role graph

KEY TYPE DESCRIPTION
type string fixed character string "role"
roleFullname string the service name and role name linked with :
name string the name of the graph ("loadavg5" etc.)
isStacked boolean [optional] whether the graph is stacked or line graph

Service graph

KEY TYPE DESCRIPTION
type string fixed character string "service"
serviceName string the name of the service
name string the name of the graph

Expression graph

KEY TYPE DESCRIPTION
type string fixed character string "expression"
expression string expression representing a graph

Query graph

KEY TYPE DESCRIPTION
type string fixed character string "query"
query string PromQL-style queries
legend string query legend. by specifiying the label key in {{ }}, it can be expanded to the value of the label. e.g. if you have a label { http.method: "GET" } and you specify method: {{http.method}} in the legend, it will expand to method: GET.

In addition to these, if the role/service graph definition connected to obtaining the dashboard is deleted, the following result may be returned.

KEY TYPE DESCRIPTION
type string fixed character string "unknown"

Graph display range

If left unspecified, the display range becomes variable and can be changed from the controller displayed at the top of the dashboard.

Relative

KEY TYPE DESCRIPTION
type string fixed character string "relative"
period number length of the period (in seconds)
offset number difference from the current time (in seconds)

A range from (current time + offset - period) to (current time + offset) is displayed. By specifying a negative value for offset, you can display a graph of the past specified range.

Absolute

KEY TYPE DESCRIPTION
type string fixed character string "absolute"
start number start time (in epoch seconds)
end number end time (in epoch seconds)

The range is displayed from start toend.

Fix the value range of the vertical axis

If not specified, the vertical axis is automatically set according to the metric values.

KEY TYPE DESCRIPTION
min number [optional] minimum value on vertical axis
max number [optional] maximum value on vertical axis

Reference line

If an reference line is specified for the graph, a horizontal line is drawn based on the specified value.

KEY TYPE DESCRIPTION
label string label of the reference line
value number value of the reference line

About the label

The label must comply with the following conditions.

  • Minimum length: 1 character (excluding spaces)
  • Maximum length: 32 characters

About the value

The value must comply with the following conditions.

  • Must be greater than or equal to 0

Format Rule

If a format rule is specified for the widget, the value will be changed to an emphasized style when the set conditional expression is satisfied. For example, if the threshold is set to 10 and the operator is set to >, the value will be emphasized when it is greater than 10.

KEY TYPE DESCRIPTION
name string [optional] Name of the format rule
threshold number Base value of the conditional expression
operator string Specify the conditions under which the emphasized style will be applied. ">" or "<".

About the name

The name must comply with the following conditions.

  • Maximum length: 32 characters

Metrics

Host metrics

KEY TYPE DESCRIPTION
type string fixed character string "host"
hostId string the host's ID
name string the name of the metric ("loadavg5" etc.)

Service metrics

KEY TYPE DESCRIPTION
type string fixed character string "service"
serviceName string the name of the service
name string the name of the metric

Expressions

KEY TYPE DESCRIPTION
type string fixed character string "expression"
expression string an expression that represents a metric

Query

KEY TYPE DESCRIPTION
type string fixed character string "query"
query string PromQL-style queries
legend string query legend. by specifiying the label key in {{ }}, it can be expanded to the value of the label. e.g. if you have a label { http.method: "GET" } and you specify method: {{http.method}} in the legend, it will expand to method: GET.

In order to properly display values of a metric specified by an expression, the result of the expression must represent a single series.

In addition to these, if the service connected to obtaining the dashboard is deleted, the following result may be returned.

KEY TYPE DESCRIPTION
type string fixed character string "unknown"

Layout

KEY TYPE DESCRIPTION
x number x coordinate of widget
y number y coordinate of widget
width number width of widget
height number height of widget

Coordinates are specified using the upper left corner of the widget display area as the origin (x = 0,y = 0), the right direction as the x axis, and the downward direction as the positive y axis. Also, each numerical value must comply with the following conditions. If these conditions are not met, the widget may not display in the position expected.

  • each value must be a positive integer or 0
  • widgets can not protrude from the widget display area (24 width)
  • widgets can not overlap
  • widgets must be at least the minimum size and at most the maximum size, as described below for each type.
Widget Minimum value width Minimum value height Maximum value width Maximum value height
Graph 6 6 24 32
Value 4 4 24 32
Markdown 4 2 24 80
Alert Status 4 3 24 32