Convert values between different units. Such as,
514 ms to
0.514 or
sizeInKiB=4 to
size=4096.
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
as | string | optional[a] | The output name of the field to set (defaults to the same as the input field). | |
binary | boolean | optional[a] | false | If specified, unit prefixes kMGTPEZY will be treated as powers of 1024 instead of 1000. |
field[b] | string | required | The name of the input field. | |
from | string | optional[a] | If the field contains unitless values, specify this parameter to tell which unit the value should be normalized from. | |
keepUnit | boolean | optional[a] | false | If specified, the output field will have the normalized unit appended. |
to | string | optional[a] | The output field should have the value converted to this unit. | |
unit | string | optional[a] | If specified, the field must end with this unit. | |
[a] Optional parameters use their default value unless explicitly set. | ||||
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
fieldcan be omitted; the following forms of this function are equivalent:logscale Syntaxunit:convert("value")and:
logscale Syntaxunit:convert(field="value")These examples show basic structure only.
unit:convert() Function Operation
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, for example, B/s.
The following rate conversions are supported:
s,
sec,
m,
min,
h,
hour,
d,
day,
w,
week.
unit:convert() Syntax Examples
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.
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.
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.
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.
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.
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.
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.
unit:convert(rate, as="rate", to="M")unit:convert()Examples
Click next to an example below to get the full details.
Convert Values Between Units
Convert file size and transfer time units using the
unit:convert() function
Query
unit:convert(field=file_size, from="B", to="MB")
| unit:convert(field=transfer_time, from="ms", to="s")
| table([file_size, transfer_time])Introduction
In this example, the unit:convert() function is
used to convert file sizes and transfer times units. The
unit:convert() function automatically handles the
mathematical conversion between units, making it easier to work with
different measurement scales in the event set.
Note that any unit is supported in LogScale.
Example incoming data might look like this:
| timestamp | file_name | file_size | transfer_time | status |
|---|---|---|---|---|
| 2025-05-15 05:30:00 | doc1.pdf | 1048576 | 3500 | complete |
| 2025-05-15 05:31:00 | img1.jpg | 2097152 | 4200 | complete |
| 2025-05-15 05:32:00 | video1.mp4 | 5242880 | 12000 | complete |
Step-by-Step
Starting with the source repository events.
- logscale
unit:convert(field=file_size, from="B", to="MB")Converts file sizes from Bytes (B) to Megabytes (MB).
- logscale
| unit:convert(field=transfer_time, from="ms", to="s")Converts transfer times from milliseconds (ms) to seconds (s)
- logscale
| table([file_size, transfer_time])Displays the result of the fields file_size and transfer_time in a table.
Event Result set.
Summary and Results
The query is used to convert file sizes and transfer times units. A table showing file sizes and transfer times is, for example, useful to spot unusually large file transfers, to identify slow transfers or bottlenecks (for debugging).
The unit:convert() function is useful to
standardize the units for better comparison and make data more readable.
Note that any unit is supported in LogScale. For more examples,
see unit:convert().
Sample output from the incoming example data:
| file_name | file_size | transfer_time |
|---|---|---|
| doc1.pdf | 1.0 | 3.5 |
| img1.jpg | 2.0 | 4.2 |
| video1.mp4 | 5.0 | 12.0 |