Customizing Metric Unit

Each metric value is associated with a unit that defines how the value should be interpreted—whether it's in seconds, bytes, percentages, CPU cores, or other measurements. Correctly assigning a unit ensures that your data is accurately visualized and easy to understand.

Examples:

  • system.cpu.time: Represents the total time the CPU spends on tasks, measured in seconds.
  • system.cpu.utilization: Indicates the percentage of CPU used by all processes, measured in percent.

Many metrics have a default unit already configured. When visualized in charts or dashboards, the UI automatically uses this default to format and label the data appropriately. For instance, the system.cpu.utilization metric is rendered using a percent sign (%) to indicate percentage usage. Metrics without a configured display unit are formatted from their OpenTelemetry unit (see Automatic Units from OpenTelemetry).

Where the unit appears depends on the widget type. In a Query Value widget, the unit is shown with the value:

Customizing Metric Unit for Query Value

In a Table widget, the unit is shown in each cell:

Customizing Metric Unit for Table Chart

In Timeseries, Pie, and Tree charts, the unit appears in the tooltip when you hover over the data:

Customizing Metric Unit For Timeseries Chart

Automatic Units from OpenTelemetry#

When you leave the unit set to Default, Middleware picks a unit for each metric in this order:

  1. Configured display unit: If the metric has a display unit configured in Middleware, that unit is used.
  2. OpenTelemetry unit: Only if no display unit is configured and the metric reports an OpenTelemetry unit that Middleware recognizes (see the table below), the mapped unit is used.

A unit you select for the query in the widget always overrides all of these.

OpenTelemetry units use UCUM notation and are case-sensitive. The unit only tells the dashboard how to read the value. The value itself is not converted, and auto scaling then picks a readable size, so a metric reported in ms with a value of 1500 is displayed as 1.5 s.

OpenTelemetry UnitDisplayed As
ns, us (µs), ms, s, min, h, dTime
ByBytes (Binary)
KiBy, MiBy, GiByBytes (Binary)
kBy, MBy, GByBytes (Decimal)
bit, kbit, Mbit, GbitBits
By/s, bit/sBytes Rate, Bit Rate
%Percentage
Hz, kHz, MHz, GHzFrequency
{cpu}, {core}, {cores}CPU (cores)
USDDollars
{request}, or any other {…} annotationCount
{packet}/s, or any other {…}/sCount Rate

Some additional rules apply:

  • Annotations are ignored when a base unit is present. For example, s{CPU} is treated as s.
  • Quotients become rate units. A unit such as MiBy/s or kBy/min is shown as the first unit with per set to the second, for example MiB/s.
  • Cloud integration spellings are recognized. Units such as Seconds, Bytes, Kilobytes/Second, Percent, and Count/Second map the same way as their OpenTelemetry equivalents.

Customizing the Unit#

In some cases, you may want to override the default unit, especially if you know the data's context better or need to align it with a specific reporting format. The unit can be customized for any widget type.

Selecting a unit tells Middleware how to interpret the raw value; it does not convert the value. Choose the unit the metric is actually reported in. For example, if a metric is reported in milliseconds and you select Seconds, every value is displayed 1000× too large.

To set a custom unit:

  1. Open the widget in the Dashboard Builder and go to its query.
  2. Click Show Advanced Options in the query panel.
  3. In the expanded section, locate the Unit field.
  4. Select the appropriate unit from the dropdown.
Customizing Metric Unit: Open Unit Dropdown
Customizing Metric Unit: Tooltip Display

The metric values will now be interpreted and displayed using the selected unit. A unit you select always takes priority over the metric's default unit.

Tip: If you're unsure of the correct unit, leave the Default option selected. The system will apply the most suitable unit automatically based on the metric.

Auto Scaling#

The system automatically scales the value to a larger or smaller unit in the same family for better readability. For example, with the unit set to Kibibyte (KiB):

Raw ValueDisplayed AsInstead Of
3234345453430.12 TiB32343454534 KiB
0.00353.58 B0.0035 KiB

Adding a Rate Unit#

If your metric represents a rate, such as a value over time (e.g., requests per second), you can specify this as well:

  1. Click the + icon next to the unit dropdown.
Customizing Metric Unit: Unit Dropdown
  1. A per dropdown appears next to the unit. Choose a rate unit, for example Seconds (/s), Minutes (/min), or Dollars (/$). To remove the rate, click the × icon next to it.
Customizing Metric Unit: Rate Unit Selection

This ensures that rate-based metrics are accurately labeled and rendered, making your dashboards more informative and easier to interpret. When you apply a rate function to a query, per is set automatically.

Unit List#

TypeUnit
BitsBit / Byte / Kilobit (kb) / Megabit (mb) / Gigabit (gb)
Bytes (Binary)Bit / Byte / Kibibyte (KiB) / Mebibyte (MiB) / Gibibyte (GiB)
Bytes (Decimal)Bit / Byte / Kilobyte (KB) / Megabyte (MB) / Gigabyte (GB)
CPUnanocores (ncores) / microcores (μcores) / millicores (mcores) / cores / kilocores (Kcores) / megacores (Mcores) / gigacores (Gcores)
TimeNanoseconds / Microseconds / Milliseconds / Seconds / Minutes / Hours / Days
PercentagePercentage
MoneyDollars
FrequencyHertz / Kilo Hertz / Mega Hertz / Giga Hertz
GeneralDate Format / Time Ago / Ago / Bytes Rate / Count / Age / Seconds / Percentage Rate / Percentage Without Bar / Badge / Text Style / Cost / Icon / OS Icon / Bit Rate / Time Utilization / Count Rate / Status / Rate / Nanosecond / Milliseconds

Examples#

UnitFamilyRaw ValueFormatted
BitBits33 b
ByteBits500234.34544 mb
KilobitBits0.562.5 B
MegabitBits55 mb
GigabitBits5050 gb
BitBytes (Binary)101.25 B
ByteBytes (Binary)5050 B
Kibibyte (KiB)Bytes (Binary)2309022.55 MiB
Mebibyte (MiB)Bytes (Binary)0.2048209.72 KiB
Gibibyte (GiB)Bytes (Binary)4040 GiB
BitBytes (Decimal)55 b
ByteBytes (Decimal)0.21.6 b
Kilobyte (KB)Bytes (Decimal)2020 KB
Megabyte (MB)Bytes (Decimal)500500 MB
Gigabyte (GB)Bytes (Decimal)5050 GB
Nanocores (ncores)CPU11 ncores
Microcores (μcores)CPU10001 mcores
Millicores (mcores)CPU0.5500 μcores
CoresCPU1010 cores
Kilocores (Kcores)CPU30003 Mcores
Megacores (Mcores)CPU0.6600 Kcores
Gigacores (Gcores)CPU5050 Gcores
NanosecondsTime10000000001 s
MicrosecondsTime1010 μs
MillisecondsTime0.0000011 ns
SecondsTime601 min
MinutesTime1202 hr
HoursTime0.530 min
DaysTime3030 days
PercentagePercentage50.2343250.23 %
DollarsMoney100.23409234$100.23409
HertzFrequency2020 Hz
Kilo HertzFrequency12341.23 MHz
Mega HertzFrequency340340 MHz
Giga HertzFrequency3434 GHz
Date FormatGeneral17513540830002025-07-01 07:14:43
Time AgoGeneralTimestamp 10 minutes ago10 minutes ago
AgoGeneralTimestamp 1 year ago1 year ago
Bytes RateGeneral100100 B/s
CountGeneral34203.42 K
AgeGeneralTimestamp 1 year ago1 year ago
SecondsGeneral4040 s
Percentage RateGeneral50.2343250.23 %/s
CostGeneral50$50.00
Bit RateGeneral81 B/s
Time UtilizationGeneral9360.2446500869862 hrs 36 m 1 s
Count RateGeneral34203.42 K/s
RateGeneral34203.42 K
NanosecondGeneral30000000003.0 s
MillisecondsGeneral34523.45 s

Date Format, Time Ago, Ago, and Age take a Unix timestamp in milliseconds. Date Format displays the time in your browser's local timezone; the example above is shown in UTC. Time Ago, Ago, and Age are calculated relative to the current time.

What did you think of this content?