Dashboards

This page explains Custom Dashboards following the feature's renovation as of November 2018. For details regarding the API operating this feature before its renovation, refer here.

Creating Dashboards

This section covers creating dashboards.

POST /api/v0/dashboards

Required permissions for 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 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

Getting Dashboards

GET /api/v0/dashboards/<dashboardId>

Required permissions for API key

  • Read

Response

Success

Same as Creating Dashboards.

Error

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

Updating Dashboards

PUT /api/v0/dashboards/<dashboardId>

Required permissions for API key

  • Read
  • Write

Input

Same as Creating Dashboards.

Response

Success

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

Error

STATUS CODE DESCRIPTION
400 when the input is invalid
403 when the API 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

Deleting Dashboards

This will delete the dashboard corresponding to the designated ID.

DELETE /api/v0/dashboards/<dashboardId>

Required permissions for API key

  • Read
  • Write

Response

Success

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

Error

STATUS CODE DESCRIPTION
403 when the API 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 of Dashboards

GET /api/v0/dashboards

Required permissions for API key

  • Read

Response

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

dashboards contains both Custom Dashboards and Legacy Custom Dashboards. Each format is as follows:

For Custom Dashboards

KEY TYPE DESCRIPTION
id string the dashboard's ID
title string the dashboard's name
memo string notes regarding the dashboard
urlPath string the dashboard's URL path
createdAt number the time at which created (in epoch seconds)
updatedAt number the time at which last updated (in epoch seconds)

For Legacy Custom Dashboards

KEY TYPE DESCRIPTION
id string the dashboard's ID
title string the name of the dashboard
urlPath string the dashboard's URL path
bodyMarkdown string a character string in Markdown format
createdAt number the time at which created (in epoch seconds)
updatedAt number the time at which last updated (in epoch seconds)
isLegacy boolean a fixed value true

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
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
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

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 not

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

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.

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

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, as described below for each type.
Widget Minimum value width Minimum value height
Graph 6 6
Value 4 4
Markdown 4 2