Convert values between different units. Such as, 514 ms to 0.514 or sizeInKiB=4 to size=4096.

ParameterTypeRequiredDefaultDescription
asstringoptional[a]  The output name of the field to set (defaults to the same as the input field).
binarybooleanoptional[a]false If specified, unit prefixes kMGTPEZY will be treated as powers of 1024 instead of 1000.
field[b]stringrequired  The name of the input field.
fromstringoptional[a]  If the field contains unitless values, specify this parameter to tell which unit the value should be normalized from.
keepUnitbooleanoptional[a]false If specified, the output field will have the normalized unit appended.
tostringoptional[a]  The output field should have the value converted to this unit.
unitstringoptional[a]  If specified, the field must end with this unit.

[a] Optional parameters use their default value unless explicitly set

[b] The argument name field can be omitted.

Omitted Argument Names

The argument name for field can be omitted; the following forms of this function are equivalent:

logscale
unit:convert("value")

and:

logscale
unit:convert(field="value")

Tip

If the unit begins with a reserved prefix character, try manually setting the unit parameter.

Any unit is supported and the following unit prefixes are converted:

Prefix Decimal Factor Binary Factor Prefix Typical Value
Y 1024 10248 (280) Yotta- (Yobi-) Bytes
Z 1021 10247 (270) Zetta- (Zebi-) Bytes
E 1018 10246 (260) Exa- (Exbi-) Bytes
P 1015 10245 (250) Peta- (Pebi-) Bytes
T 1012 10244 (240) Tera- (Tebi-) Bytes
G 109 10243 (230) Giga- (Gibi-) Bytes
M 106 10242 (220) Mega- (Mebi-) Bytes
k 103 1024 (210) Kilo- (Kibi-) Metric, Bytes
h 102   Hect- Metric
da 10   Deca- Metric
d 10-1   Deci- Metric
c 10-2   Centi- Metric
m 10-3   Milli- Metric, Seconds
u, µ 10-6   Micro- Metric, Seconds
n 10-9   Nano Metric, Seconds
p 10-12   Pico Metric, Seconds
f 10-15   Femto Metric, Seconds
a 10-18   Atto Metric, Seconds
z 10-21   Zepto Metric, Seconds
y 10-24   Yocto Metric, Seconds
Yi   10248 (280) Yobi- Bytes
Zi   10247 (270) Zebi- Bytes
Ei   10246 (260) Exbi- Bytes
Pi   10245 (250) Pebi- Bytes
Ti   10244 (240) Tebi- Bytes
Gi   10243 (230) Gibi- Bytes
Mi   10242 (220) Mebi- Bytes
Ki   1024 (210) Kibi- Metric, Bytes

Tip

Units can be expressed as SI units or binary units. An example of a base unit is 2Gi bytes. We use the standard SI-units K, M, G, and P to denote 1000-based kilo, mega, giga and peta; whereas Ki, Mi, Gi, and Pi designate the binary multiple 1024n style. See the National Institute of Standards & Technology's Reference on Prefixes for Binary Multiples for a detailed explanation.

If a field contains a value such as 5 kB that should be treated as 5 KiB, set the binary flag.

When the unit is a rate, such as MB/min the rate will be normalized to per second, e.g. B/s.

The following rate conversions are supported: s, sec, m, min, h, hour, d, day, w, week.

Parses a value into a number by removing the unit. An input event with the field size with the value 5 MB results in the field size having the value 5000000.

logscale
unit:convert(size)

Parses a value into a number by removing the unit. An input event with the field size with the value 5 MiB results in the field size having the value 5242880.

logscale
unit:convert(size)

Parses a value into a number by removing the unit. An input event with the field size with the value 5 MB results in the field size having the value 5242880.

logscale
unit:convert(size, binary=true)

Parses a value into a number by removing the unit. An input event with the field duration with the value 514 us results in the field duration having the value 0.000514.

logscale
unit:convert(duration)

Parses a unit less value into a number by manually specifying the input unit. An input event with the field size with the value 234.567 results in the field size having the value 234567.

Internally the value is parsed as {size} {from}, just as if the field had contained the value 234.567 k.

logscale
unit:convert(size, from="k")

Parses a value into a number by removing the unit. An input event with the field rate with the value 120 hits/min results in the field rate having the value 2.

Note

Since the unit in this case starts with a letter h from the supported prefixes, it will be interpreted as the prefix h (102) and unit hits. To enforce that the unit is actually hits, specify the unit parameter.

logscale
unit:convert(rate, as="rate", unit="hits")

Converts a number into a value with a unit. An input event with the field size with the value 19886168 results in the field rate having the value 19.886168.

logscale
unit:convert(rate, as="rate", to="M")