Logo of AppSignal

Menu
Docs navigation

Custom metric dashboards Beta

Custom metrics dashboards are in beta. Dashboards are currently configured using a YAML definition format (which will change in the future) on the "Add Dashboards" page.

These dashboards can be created based on custom metrics sent from apps integrated with AppSignal. Some metrics are automatically created by AppSignal based on request and background job data.

This page describes how to create/edit dashboards for your apps using our YAML definition format.

Custom metrics demo dashboard

Table of Contents

Example dashboard

Below is an example of our YAML structure that will generate a tab on the metrics page with two graphs. This examples a single dashboard with graphs for the error rate and response times grouped by every namespace.

This dashboard requires that some request or background job data has been received by AppSignal for your app.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
title: 'Example dashboard'
description: 'An example dashboard with standard AppSignal metrics'
graphs:
  -
    title: 'Error rate'
    description: 'The error rates of all namespaces'
    line_label: '%namespace%'
    format: percent
    metrics:
      -
        name: transaction_exception_rate
        fields:
          - GAUGE
        tags:
          namespace: "*"
  -
    title: 'Response time'
    description: 'The response times of all namespaces'
    line_label: '%namespace%'
    format: duration
    metrics:
      -
        name: transaction_duration
        fields:
          - MEAN
          - P90
          - P95
        tags:
          namespace: "*"

Definition YAML

In this definition example some sections are annotated with their types, which correspond to the naming/headings on this page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# Annotated example dashboard YAML definition

# Dashboard
title: 'Dashboard title'
description: 'Example dashboard description'
graphs:
  - # Graph
    title: 'Graph title #1'
    description: 'Graph #1 description'
    line_label: 'Configurable line label for %name%'
    format: percent
    draw_null_as_zero: true
    metrics:
      - # Metric
        name: my_metric_1
        fields:
          - GAUGE
      -
        name: my_metric_2
        fields:
          - GAUGE
  - # Graph
    title: 'Graph title #2'
    description: 'Graph #2 description'
    line_label: 'Configurable line label for %name% with %tag_1% %tag_2%'
    format: size
    format_input: kilobyte
    draw_null_as_zero: false
    metrics:
      - # Metric
        name: 'my_metric_*'
        fields:
          - GAUGE
        tags:
          tag_1: 'value_1'
          tag_2: 'value_with_wildcard_*'

Dashboards

The dashboards editor allows you to create/edit one dashboard at a time. Each dashboard consists of a title and one or more graphs.

1
2
3
4
5
# Dashboard
title: "Dashboard title"
description: "My dashboard description"
graphs:
  - <Graph>
Field Type Description
title String Title of the dashboard.
description String Description of the dashboard. Not shown anywhere else but in the YAML.
graphs Array<Graph> List of Graphs to show on the dashboard.

Graphs

Per graph the following options can be configured.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Dashboard
title: 'Dashboard title'
graphs:
  - # Graph
    title: 'Graph title #1'
    description: "My graph description"
    line_label: 'Configurable line label for %name%'
    format: percent
    metrics:
      - <Metric>
  - # Graph
    title: 'Graph title #2'
    line_label: 'Configurable line label for %name%'
    format: size
    metrics:
      - <Metric>
Field Type Description
title String
Required.
Title of the graph. Used for naming the dashboard navigation items.
description String Optional description to show on the graph.
line_label String
Default: "%name%"
Line label formatter for this graph. Supports replacements of metric names, fields and tags with percent symbols.
format String
Default: "number"
The formatter for the line values. Available options are: number, size, percent, duration and throughput.
format_input String (no default) The format of the input of this metrics when using the size formatter. Available options are: bit, byte, kilobit, kilobyte and megabyte.
draw_null_as_zero Boolean
Default: true
If true no data (NULL) will be rendered as 0. If false it will repeat the last received value until a new value is registered.
metrics Metric Array of each metric that should be graphed.

Graph description

Sometimes a graph title doesn't tell the whole story. If you need a place for a longer summary of what's being displayed in the graph it's possible to set a graph description.

Set the description key with any string value to get a description in the graph as shown below. Multi line descriptions are wrapped on a single line and expanded on hover.

Graph description example

Line label format

The line_label option allows you to format the label of every line as displayed in the graph legend on mouse over.

  • %name%: the metric name.
  • %field%: the field of the metric.
  • %tag%: every available tag key. Used as %my_tag_key%. These are dynamic and can differ per metric.

Example

The following example shows how to send a counter metric with tags and how to create a dashboard graph that uses tags to format line label using the line_label option.

1
2
3
# Ruby
Appsignal.increment_counter("visits_per_region", 2, :region => "eu", :subscription_type => "pro")
Appsignal.increment_counter("visits_per_region", 1, :region => "us", :subscription_type => "standard")
1
2
3
# Elixir
Appsignal.increment_counter("visits_per_region", 2, %{region: "eu", subscription_type: "pro"})
Appsignal.increment_counter("visits_per_region", 1, %{region: "us", subscription_type: "standard"})

The following graph definition will show two lines with the following labels:

  • "visits_per_region - EU - pro"
  • "visits_per_region - US - standard"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Dashboard
title: "My visits dashboard"
graphs:
  - # Graph
    title: "Visits graph"
    line_label: "%name% - %region% - %subscription_type%"
    metrics:
      - # Metric
        name: visits_per_region
        fields:
          - COUNTER
        tags:
          region: "*"
          subscription_type: "*"

Value formatting

The format option allows customization of the value type used to display values in the graph and graph legends.

Selecting a value formatter does not affect the data stored in our systems, only how it's displayed.

Formatter Description
number A human readable formatted number. The value 1_000_000 is displayed as 1 M and 10_000 as 10 K.
size Size formatted as megabytes. 1.0 megabytes is displayed as 1Mb. Use the format_input option to specify the unit of the input value.
percent A percentage. The value 40 is displayed as "40 %".
duration A duration of time in milliseconds. The value 100 is displayed as "100 ms" and 60_000 as "60 sec". Commonly used for measurement metric.
throughput Throughput of a metric. It will display the throughput formatted as a number for both the minute and the hour. The value 10_000 is displayed "10k / hour 166 / min". Commonly used for counter metrics.

Size value format input

Specify the "size" of the incoming metric value in units of bytes with the format_input option. For example, you can either send a value expressed in bytes or megabytes and the formatter will use this as a basis to format the value in a human readable way. This option only works for the format option "size".

AppSignal host metrics send sizes in megabytes and won't need the format_input option to be configured for graphs, the default option megabyte will be used.

Selecting a value formatter input does not affect the data stored in our systems, only how it's displayed.

The available options are:

  • bit
  • byte
  • kilobit
  • kilobyte
  • megabyte

When sending a metric with the following value:

1
Appsignal.set_gauge("database_size", 1024)

The graph will render the following values for the specified settings:

  • format_input: bit will render "128 Bytes"
  • format_input: byte will render "1 KB"
  • format_input: kilobit will render "128 KB"
  • format_input: kilobyte will render "1 MB"
  • format_input: megabyte will render "1 GB"
  • format_input: "" will render "1 GB"

Draw NULL as zero

Not always does every point in time have a value for a metric, yet the value is not 0. In our system we do not record a value for this time and treat this point as NULL rather than 0. This means, no value is present and can be interpreted in two ways. Either it was actually 0 (useful for counter metrics) or it retains the value of the previous known point.

The draw_null_as_zero option (true by default) allows configuration of the draw behavior for a graph. If set to true it will treat the NULL value as 0. If set to false it will repeat the last known value until a later point in time specifies a new value.

See the difference in the graph below. With draw_null_as_zero: true the graph makes a sharp drop to 0 every time the app stopped reporting data. With draw_null_as_zero: false the graph looks less volatile in terms of lines moving up and down.

Draw NULL as zero option graph comparison screenshot

The configuration to generate the graphs above:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Dashboard
title: 'draw_null_as_zero example dashboard'
graphs:
  - # Graph
    title: 'draw_null_as_zero: true (default)'
    format: number
    draw_null_as_zero: true
    metrics:
      - # Metric
        name: random_number
        fields:
          - GAUGE
  - # Graph
    title: 'draw_null_as_zero: false'
    format: number
    draw_null_as_zero: false
    metrics:
      - # Metric
        name: random_number
        fields:
          - GAUGE

The app used to generate these graphs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# app.rb
# gem install "appsignal"
require "appsignal"
Appsignal.config = Appsignal::Config.new(".", "development", { :name => "My app", :active => true, :push_api_key => "00000000-0000-0000-0000-000000000000" })
Appsignal.start
Appsignal.start_logger

[
  [5, 1],
  [7, 1],
  [3, 3],
  [5, 2],
  [2, 5],
  [10, 2],
  [8, 1],
  [4, 2]
].each do |(value, pause)|
  puts "set_gauge random_number #{value}"
  Appsignal.set_gauge("random_numbers", value)
  pause_in_minutes = pause * 60
  puts "Sleeping #{pause} minute(s)"
  sleep pause_in_minutes
end

Appsignal.stop

Graph metrics

The graph metrics section describes which lines should be drawn in a graph based on the (custom) metrics available in AppSignal for an app. It's possible to select one or multiple metrics, specify which metric field and narrow down which tags should be filtered by.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Dashboard
title: 'Dashboard title'
graphs:
  - # Graph
    title: 'Graph title #1'
    line_label: 'Configurable line label for %name%'
    format: percent
    metrics:
      - # Metric
        name: counter_one
        fields:
          - COUNTER
      - # Metric
        name: counter_two
        fields:
          - COUNTER
  - # Graph
    title: 'Graph title #2'
    line_label: 'Configurable line label for %name%'
    format: size
    metrics:
      - # Metric
        name: transaction_exception_count
        fields:
          - GAUGE
Field Type Description
name String supporting wildcard symbols (*).
Required.
An array of metric names to graph. Select metric by name using a wildcard symbol (*).
fields Array<String>
Required.
The type of metrics to display in this graph. Available options are: GAUGE, COUNTER, MEAN, P90, P95 and COUNT.
tags Object<Key, Value> Select metric by tags and their values.

Name

The name of the metric to be graphed in this graph. You can either use the full metric name to select one metric, or use a wildcard to select multiple metrics at once.

1
2
# Metric
name: db_users_document_count

Wildcard support

When using a wildcard, all metric names matching the given wildcard will be graphed. This can be useful if you have a type of grouping metrics by name to compare different kinds of systems.

1
2
# Metric
name: "db_*_size"

This filter will match any metric name that begins with db_ and ends with _size. For example:

  • db_graph_collection_size
  • db_user_collection_size

Note: We don't recommend using metric names for a lot of variables, instead use tags for this purpose.

Fields

For every graph you can specify which type of metric to graph. Only the following values are supported:

Tags

With the tags option it's possible to select which tags for the metric to display in the graph. By default, when graphing a metric, all variations of the tags will create their own line in the graph. By omitting the tags option it will use this default behavior.

When matching metrics with tags all tags need to be specified, either with a value or a wildcard. For example, when a metric visits_per_region has two tags region and subscription_type, both tags need to be specified in the dashboard YAML definition. If one is omitted the graph will query for a metric only containing the specified tags, thus not finding the metric with more tags.

With the metric visits_per_region and the two tags region and subscription_type, this definition will not match the metric:

1
2
3
# Metric
tags:
  region: "eu"

This definition will match the metric:

1
2
3
4
# Metric
tags:
  region: "eu"
  subscription_type: "*"

It is also possible to match partial tag values with the wildcard, for example by specifying the value like so "tag_value_*".

For metrics with tags we recommend customizing the labels used in the graph legend using the line_label option.

Example

The following graph will create two graphs, one that only shows visits in the EU region and another that only shows visits from the "pro" plan. It will draw two lines in each graph based on the wildcard specified in the other tag.

  • "EU visits graph"
    • Lines to be drawn:
      1. "visits_per_region EU pro"
      2. "visits_per_region EU standard"
  • "Pro visits graph"
    • Lines to be drawn:
      1. "visits_per_region EU pro"
      2. "visits_per_region US pro"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Dashboard
title: "My visits dashboard"
graphs:
  - # Graph
    title: "EU visits graph"
    line_label: "%name% %region% %subscription_type%"
    metrics:
      - # Metric
        name: visits_per_region
        fields:
          - COUNTER
        tags:
          region: "eu"
          subscription_type: "*"
  - # Graph
    title: "Pro visits graph"
    line_label: "%name% %region% %subscription_type%"
    metrics:
      - # Metric
        name: visits_per_region
        fields:
          - COUNTER
        tags:
          region: "*"
          subscription_type: "pro"

Note: When matching all tags values, the YAML format requires you to escape the wildcard character: "*", otherwise it will try and interpret it as a YAML alias.

We'd like to set cookies, read why.