Keep First

Text Processing Data Analysis

Synopsis

Keeps the first N characters of a string, or of each string in an array.

Schema

- keep_first:
    field: <ident>
    count: <string>
    target_field: <string>
    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 string or array to process
count	Y	-	Number of characters to keep from the beginning. Quote the value — it is read as a string
target_field	N	Same as field	Target field to store result
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if operation 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

Extracts the first N characters of a string. Given an array, it applies that truncation to every element — it does not select the first N elements.

Truncation is at character boundaries, so multi-byte characters are never split. Elements of an array are converted to strings before truncation.

note

When processing strings, the processor counts Unicode characters correctly, not bytes. This ensures proper handling of international characters and emojis.

If the specified count is greater than the length of the string or array, the processor returns the entire original value without modification.

warning

Non-string and non-array values will cause the processor to fail unless ignore_failure is set to true. The processor cannot determine what "first N" means for other data types.

Examples

String Truncation

Keeping first 10 characters of a string...	{ "long_message": "This is a very long message that needs truncation" } - keep_first: field: long_message count: "10" target_field: preview
creates truncated preview:	{ "long_message": "This is a very long message that needs truncation", "preview": "This is a " }

Array Limitation

Keeping first 3 elements from an array...	{ "ip_addresses": [ "192.168.1.1", "192.168.1.2", "192.168.1.3", "192.168.1.4", "192.168.1.5" ] } - keep_first: field: ip_addresses count: "3" target_field: top_ips
truncates EVERY element to its first 3 characters — it does not take the first 3 elements:	{ "ip_addresses": [...], "top_ips": ["192", "192", "192", "192", "192"] }

In-Place Truncation

Truncating field value in place...	{ "user_id": "user_1234567890_extended_identifier" } - keep_first: field: user_id count: "12"
overwrites original field:	{ "user_id": "user_1234567" }

Unicode String Handling

Properly handling Unicode characters...	{ "international_text": "Héllo Wörld 😀 Unicode Text" } - keep_first: field: international_text count: "8" target_field: prefix
counts Unicode characters correctly:	{ "international_text": "Héllo Wörld 😀 Unicode Text", "prefix": "Héllo Wö" }

Conditional Processing

Applying truncation based on conditions...	{ "error_message": "Database connection failed after multiple retry attempts", "truncate_errors": true } - keep_first: field: error_message count: "20" if: "truncate_errors == true"
truncates when condition matches:	{ "error_message": "Database connection ", "truncate_errors": true }