Length

Mutate

Synopsis

Writes the size of a field into a target field. What "size" means depends on what the field holds: the element count of an array, the key count of an object, or the character count of a string.

Schema

- length:
    field: <ident>
    array_only: <boolean>
    byte_length: <boolean>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <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	-	Field to measure
array_only	N	false	Restrict the processor to arrays. With true, an object, a string or a null value is an error instead of being measured
byte_length	N	false	Count a string in bytes rather than characters. Only affects strings
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	See Handling Failures
ignore_missing	N	false	If true, quietly exit if field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration
target_field	N	field	Field to store the length. Defaults to field, replacing the value that was measured

Details

The measurement is chosen from the value's shape:

Value	Length
Array	Number of elements
Object	Number of top-level keys
String	Number of characters, or bytes under byte_length
null	0

Anything else — a number, a boolean — is an error: it has no length to report.

byte_length matters for any text outside ASCII. A character counted once may occupy several bytes, so "café" is 4 characters and 5 bytes. Use the byte count when you are sizing a payload against a transport limit, and the character count when you are reasoning about the text itself.

note

target_field defaults to field, which replaces the value you measured with its length. Set target_field explicitly whenever you need to keep the original.

Examples

Array Length

Counting the elements of an array...	{ "tags": ["prod", "web", "eu-west"] } - length: field: tags target_field: tag_count
writes the count alongside it:	{ "tags": ["prod", "web", "eu-west"], "tag_count": 3 }

Characters and Bytes

The default counts characters...	{ "user": {"name": "café"} } - length: field: user.name target_field: user.name_chars - length: field: user.name byte_length: true target_field: user.name_bytes
and byte_length counts the encoded size:	{ "user": { "name": "café", "name_chars": 4, "name_bytes": 5 } }

Rejecting Non-Arrays

With array_only, a field that is not an array fails rather than being measured...	{ "message": "connection refused" } - length: field: message array_only: true target_field: message_count on_failure: - set: field: error.reason value: "expected an array"
so the string length is never written:	{ "message": "connection refused", "error": {"reason": "expected an array"} }

Object Keys

An object reports its top-level key count...	{ "labels": { "env": "prod", "team": "platform" } } - length: field: labels target_field: label_count
counting only the outermost level:	{ "labels": { "env": "prod", "team": "platform" }, "label_count": 2 }