Dashboards - AppSignal Documentation

The dashboards commands list, create, and update an app’s dashboards, and show, add, and update the charts on them. Each command targets one application, by name and environment (--app "MyApp" --environment production) or by ID (--app-id <APP_ID>, the long hexadecimal app ID from appsignal-cli apps list). The --environment flag is only needed when several apps share a name. Each command uses your default organization unless you pass --org. See Apps and organizations for how apps are identified.

List dashboards

Shell

appsignal-cli dashboards list --app "MyApp" --environment production

The list includes each dashboard’s ID, which you need to update one.

Show a dashboard

To see a dashboard’s details and its charts, pass the dashboard’s --id:

Shell

appsignal-cli dashboards show --id <DASHBOARD_ID> --app "MyApp" --environment production

The output lists each chart with its ID, type, and settings. You need a chart’s ID to update it. With --output json, the charts are in dashboard.visuals, each with its id, its type in __typename, and its settings. add-visual and update-visual return the same shape.

Create a dashboard

A new dashboard needs a title and a description:

Shell

appsignal-cli dashboards create --app "MyApp" --environment production \
  --title "Checkout health" --description "Latency and error rate for checkout"

Flag	Description
`--title <title>`	Dashboard title (required)
`--description <text>`	What the dashboard monitors (required; can’t be empty)
`--app <name>`	App to create the dashboard in (add `--environment` when the name isn’t unique)
`--environment <env>`	Environment, used with `--app`
`--app-id <id>`	The app’s ID (a long hexadecimal string), as an alternative to `--app` and `--environment`
`--org <slug>`	Organization slug (uses your default if omitted)

Update a dashboard

Pass the dashboard’s --id (from dashboards list) along with the new title:

Shell

appsignal-cli dashboards update --id <DASHBOARD_ID> --app "MyApp" --environment production \
  --title "Checkout health" --description "Updated description"

Flag	Description
`--id <id>`	ID of the dashboard to update (required; from `dashboards list`)
`--title <title>`	New title (required)
`--description <text>`	New description (optional; leave it out to keep the current one)
`--app <name>`	App the dashboard belongs to (add `--environment` when the name isn’t unique)
`--environment <env>`	Environment, used with `--app`
`--app-id <id>`	The app’s ID (a long hexadecimal string), as an alternative to `--app` and `--environment`
`--org <slug>`	Organization slug (uses your default if omitted)

--title is required even when you only change the description.

Add a chart

You describe a chart in a JSON file, then add it with add-visual. Say you run an online store. Your Checkout health dashboard should answer two questions: is checkout slow, and is it failing? To see how slow checkout is for your slowest customers, chart its 95th percentile response time over time. That’s a timeseries chart. Save it as checkout-speed.json:

checkout-speed.json

{
  "title": "Checkout response time",
  "description": "How long checkout takes for the slowest 5% of customers",
  "display": "LINE",
  "format": "duration",
  "metrics": [
    {
      "name": "transaction_duration",
      "fields": [{ "field": "P95" }],
      "tags": [
        { "key": "namespace", "value": "web" },
        { "key": "action", "value": "CheckoutsController#create" }
      ]
    }
  ]
}

Then add it to the dashboard:

Shell

appsignal-cli dashboards add-visual --dashboard-id <DASHBOARD_ID> \
  --app "MyApp" --environment production \
  --type timeseries --file checkout-speed.json

To see how often checkout fails, add a Big Number tile with the total errors in the selected time range. That’s a number chart, which takes a single metric. Save it as checkout-errors.json:

checkout-errors.json

{
  "title": "Checkout errors",
  "description": "Errors raised during checkout in the selected time range",
  "metric": {
    "name": "error_count",
    "field": "COUNTER",
    "aggregate": "SUM",
    "tags": [
      { "key": "namespace", "value": "web" },
      { "key": "action", "value": "CheckoutsController#create" }
    ]
  }
}

Shell

appsignal-cli dashboards add-visual --dashboard-id <DASHBOARD_ID> \
  --app "MyApp" --environment production \
  --type number --file checkout-errors.json

Replace CheckoutsController#create with the action that handles checkout in your app. Every new chart needs a nonempty title and description. To read the JSON from standard input instead of a file, pass --file -.

Flag	Description
`--dashboard-id <id>`	Dashboard to add the chart to (required; from `dashboards list`)
`--type <type>`	Chart type: `timeseries` or `number` (required)
`--file <path>`	JSON chart definition, or `-` to read it from standard input (required)
`--app <name>`	App the dashboard belongs to (add `--environment` when the name isn’t unique)
`--environment <env>`	Environment, used with `--app`
`--app-id <id>`	The app’s ID (a long hexadecimal string), as an alternative to `--app` and `--environment`
`--org <slug>`	Organization slug (uses your default if omitted)

The CLI doesn’t retry a failed chart creation. If add-visual fails with a network error, check the dashboard with dashboards show before you retry. That way, you don’t add the chart twice.

Update a chart

To change a chart, pass only the settings you want to change. Everything else stays as it is. For example, to show the checkout response time as an area chart, get the chart’s ID from dashboards show and run:

Shell

printf '%s' '{"display":"AREA"}' | \
  appsignal-cli dashboards update-visual --dashboard-id <DASHBOARD_ID> --id <CHART_ID> \
    --app "MyApp" --environment production --file -

update-visual takes the same app flags as add-visual, plus:

Flag	Description
`--dashboard-id <id>`	Dashboard the chart is on (required)
`--id <id>`	ID of the chart to update, from `dashboards show` (required)
`--file <path>`	JSON file with the settings to change, or `-` to read it from standard input (required)

A few settings need more care:

Lists and objects are replaced whole. To also chart the payment step, pass metrics with both the checkout metric and the new one. To move a chart, pass all four layout values.
To clear a setting, set it to null. This works for description, formatInput, layout, lineLabel, minYAxis, and a number chart’s metric. format can’t be cleared, so set it to another format instead.
To remove all of a timeseries chart’s metrics, pass "metrics": [].
Changing format away from size also clears formatInput.

A chart keeps its type, so you can’t turn a timeseries chart into a number chart. An update with no settings is rejected.

Chart settings

Chart JSON uses camelCase keys and holds settings only. The dashboard ID, chart ID, and chart type go in the command flags. Unknown keys, invalid values, and settings for the other chart type return an error.

Chart type	Settings
Both	`title`, `description`, `format`, `formatInput`, `layout`
Timeseries	`metrics`, `lineLabel`, `display`, `drawNullAsZero`, `minYAxis`
Number	`metric`

These settings take a fixed set of values:

Setting	Values
`display`	`LINE`, `AREA`, or `AREA_RELATIVE`
A metric’s `field`	`MEAN`, `P90`, `P95`, `COUNT`, `GAUGE`, or `COUNTER`
A number chart’s `aggregate`	`MAX`, `MIN`, `AVG`, `SUM`, `FIRST`, or `LAST`
`format`	`number`, `percent`, `duration`, `throughput`, or `size`. New charts default to `number`
`formatInput`	`bit`, `byte`, `kilobit`, `kilobyte`, or `megabyte`, the input unit for the `size` format
`layout`	An object with the integers `x`, `y`, `w`, and `h`

Next steps

A dashboard visualizes your metrics. To get alerted when one crosses a threshold, set up anomaly detection triggers.

​List dashboards

​Show a dashboard

​Create a dashboard

​Update a dashboard

​Add a chart

​Update a chart

​Chart settings

​Next steps

List dashboards

Show a dashboard

Create a dashboard

Update a dashboard

Add a chart

Update a chart

Chart settings

Next steps