Humanize

Text Processing Data Analysis

Synopsis

Converts numbers to human-readable format with metric prefixes.

Schema

- humanize:
    field: <ident>
    type: <enum>
    target_field: <ident>
    format: <string>
    precision: <numeric>
    binary: <boolean>
    short_form: <boolean>
    min_unit: <string>
    max_unit: <string>
    separator: <string>
    reference_time: <string>
    suffix: <boolean>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing the value to humanize
type	N	auto	What the value is: bytes, duration, number, timestamp, boolean, percent, or auto to infer it from the value's Go type
target_field	N	field	Field to store the result. Defaults to field, replacing the value
format	N	-	Secondary modifier within a type. bytes/size and duration/time steer auto-detection; short/long pick the duration wording; ordinal/word pick the number wording
precision	N	1	Decimal places to show in the result
binary	N	false	Use the binary (1024) base instead of the decimal (1000) base
short_form	N	false	Abbreviate duration units. Equivalent to format: short
min_unit	N	-	Smallest unit the result may use
max_unit	N	-	Largest unit the result may use
separator	N	" " (space)	String placed between the parts of a multi-unit result. An explicit "" is not honoured — it resolves back to a single space
reference_time	N	now	Instant a timestamp is measured against
suffix	N	false	Append "ago" or "remaining" to a relative time
relative	N	false	Accepted but not applied. The value is never read
compact_form	N	false	Accepted but not applied. The value is never read
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if conversion fails
ignore_missing	N	false	Skip processing if referenced 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

Details

Converts numeric values to human-readable format using appropriate metric prefixes (K, M, G, T) or time units. The processor makes large numbers more readable by automatically selecting the appropriate scale and unit.

The processor supports different format types including data sizes, general numbers, time durations, and frequencies, each with appropriate unit conventions.

note

The processor automatically selects the most appropriate unit based on the magnitude of the input number. For example, 1500000 becomes "1.5M" and 2048 becomes "2.0K" (or "2.0Ki" in binary mode).

When binary is enabled, the processor uses 1024-based calculations (Ki, Mi, Gi, Ti) instead of 1000-based (K, M, G, T), which is common for memory and storage sizes.

warning

Non-numeric input values will cause the processor to fail unless ignore_failure is set to true. Ensure the source field contains valid numeric data.

Examples

Basic Number Humanization

Converting large number to readable format...	{ "byte_count": 1048576 } - humanize: field: byte_count target_field: readable_size
creates human-readable size:	{ "byte_count": 1048576, "readable_size": "1.0MB" }

Binary Format

Using binary (1024-based) formatting...	{ "memory_bytes": 2147483648 } - humanize: field: memory_bytes binary: true precision: 2 target_field: memory_size
formats with binary units:	{ "memory_bytes": 2147483648, "memory_size": "2.00GiB" }

Time Format

Humanizing time duration in milliseconds...	{ "duration_ms": 125000 } - humanize: field: duration_ms type: duration target_field: duration_human
converts to time units:	{ "duration_ms": 125000, "duration_human": "2m 5s" }

Custom Precision

Setting specific decimal precision...	{ "request_count": 1234567 } - humanize: field: request_count type: number precision: 3 target_field: formatted_count
formats with 3 decimal places:	{ "request_count": 1234567, "formatted_count": "1.235M" }

With Time Suffix

Adding suffix to time duration values...	{ "remaining_seconds": 3600 } - humanize: field: remaining_seconds type: duration suffix: true target_field: time_remaining
includes "remaining" suffix:	{ "remaining_seconds": 3600, "time_remaining": "1 hour remaining" }