Bytes

Mutate Elastic Compatible

Synopsis

Converts string field values expressing size in byte units to their numeric value in bytes.

Schema

- bytes:
    field: <ident>
    description: <text>
    if: <script>
    ignore_missing: <boolean>
    ignore_failure: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>
    target_field: <ident>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y		The field containing the unit values
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_missing	N	`false``	If true and field does not exist or contains no value, exit quietly without making any modifications
ignore_failure	N	-
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
target_field	N	-	Field to assign the converted value to, if distinct from field

Details

If the field contains multiple values, all of them are converted.

Allowed units are B, KB, MB, GB, TB, and PB, all case insensitive. Fractional values like "1.5KB" are also supported. If the string is not in one of the enumerated formats or exceeds $2^64-1$ in value, an error is raised.

Examples

Basic

Convert size with byte units...	{ "file_size": "1.5KB" } - bytes: field: file.size
to its value in bytes:	{ "file.size": 1536 }

Unit Variations

The processor handles various unit formats and cases...	{ "sizes": { "a": "1kb", "b": "1KB", "c": "1 KB", "d": "1 Kb" } } - bytes: field: sizes.a - bytes: field: sizes.b - bytes: field: sizes.c - bytes: field: sizes.d
all converting to the same value:	{ "sizes": { "a": 1024, "b": 1024, "c": 1024, "d": 1024 } }

Keep Original

Store the result in a different field...	{ "raw_size": "1GB" } - bytes: field: raw_size target_field: size_in_bytes
keeping the original value:	{ "raw_size": "1GB", "size_in_bytes": 1073741824 }

Error Handling

With invalid formats...	{ "size": "100XB" } - bytes: field: size ignore_failure: true
errors can be ignored:	{ "size": "100XB", "error": { "message": "Invalid byte unit format" } }

Missing Fields

When field is missing...	{ "other_field": "value" } - bytes: field: size ignore_missing: true
processing continues if configured:	{ "other_field": "value" }