Metrics

Metrics are provided by plugins and displayed by widgets. This page explains what a widget receives for a metric, and how to work with it efficiently. For a first example, see Display a Metric.

Selecting a Metric

A widget lets users select a metric using a field of type metric. When selecting the metric, users can additionally choose:

• A unit to convert the value to, e.g. °F instead of °C, or GB instead of bytes.
• A value source: the current value of the metric, or its minimum, maximum or average value.

MoBro applies both before the value reaches the widget, so the widget always receives the value to display. The selection is stored as a ValueMetricConfig.

The ChannelValue

useMetricField returns a ChannelValue, which combines the metric's current value with the information needed to display it:

ChannelValue
├── metric         the metric: id, label, description, …
├── type           the metric type: id, label, valueType, baseUnit, units
├── unit           the unit the value is provided in (after conversion)
└── value          the metric value
    ├── value          the actual value: number, string or null
    ├── valueUpdated   when the value was last updated (ISO date)
    ├── valueChanged   when the value last changed (ISO date)
    └── statistics     min, max, avg, count, started, lastUpdated

The actual value is therefore accessed as channelValue.value.value.

The ChannelValue corresponds to the metric value a plugin provides, extended by the metric, its type and its unit.

Value Types

How to interpret channelValue.value.value depends on the value type of the metric, available as channelValue.type.valueType:

Value type	Value
Numeric, Duration	A number, converted to channelValue.unit
Currency	A number, in the currency of channelValue.unit
Boolean	A boolean state, interpret it using Boolean(value)
String, Custom	A string
DateTime, DateOnly, TimeOnly	An ISO date string
Resource	The id of a resource (e.g. an image) provided by the plugin

Instead of handling every value type yourself, use useFormattedMetricValue, which formats the value based on its value type. Use filters to only offer metrics with value types your widget supports.

Statistics

Every metric value includes statistics, which MoBro collects from the values the plugin provided:

Field	Description
min	The smallest value
max	The largest value
avg	The average value
count	The number of values
started	When MoBro started collecting the statistics
lastUpdated	When the statistics were last updated

The statistics are especially useful to scale gauges and charts. For example, the gauge of the Charts widget pack uses statistics.max as maximum, unless the user configured a maximum value.

note

A metric value may also contain a timeseries with previous values, but widgets can't rely on it being present. Widgets that display previous values, like line charts, should collect the values they receive themselves.

Re-rendering

useMetricField re-renders the widget for every new value, even if the value didn't change. How often that happens depends on how often the plugin updates the metric.

If a widget only displays a derived value, e.g. a rounded number, use useMemoizedMetricField instead. It only re-renders the widget when the derived value changes. A common pattern is to format the value within the memo function, so the widget only re-renders when the displayed text changes:

src/widgets/example/Example.tsx

import React, {useCallback} from 'react'
import {useFormatMetricValue, useMemoizedMetricField} from '@modbros/dashboard-sdk'
import type {ChannelValue} from '@modbros/dashboard-core'

export default function Example() {
  const format = useFormatMetricValue()

  const memo = useCallback(
    (channelValue: ChannelValue | null) => {
      const formatted = format(channelValue, {precision: 0})

      return formatted ? `${formatted.value} ${formatted.unit ?? ''}` : null
    },
    [format]
  )

  const {value} = useMemoizedMetricField({field: 'metric', memo})

  return <span>{value}</span>
}

Metrics in the Dashboard Builder

While editing a dashboard in the dashboard builder, widgets receive the current value of their metrics when the metric is selected. The values are only updated continuously if live updates are enabled in the dashboard builder.

Missing Metrics

A selected metric may not exist anymore, e.g. because its plugin was uninstalled. In that case, useMetricField throws an error and MoBro shows an error on the widget. See Error Handling.