UUID

Mutate

Synopsis

Writes a freshly generated random UUID into a target field.

Schema

- uuid:
    target_field: <ident>
    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
target_field	Y	-	Field to store the generated UUID. There is no default: an empty value fails with uuid requires a target_field
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

Details

The value is a version 4 UUID — random, not derived from the event — rendered lowercase in the canonical hyphenated form, for example 9f1c2b7e-6a3d-4f58-9c21-0d4e8b5a7c33.

The processor takes no input field. It generates a value and writes it, so it is a correlation handle rather than a transformation of anything already on the event.

Because the value is random, the same event processed twice gets two different UUIDs. Where a stable identifier is needed — deduplication, or matching an event to a record produced elsewhere — derive one from the event's own contents with Fingerprint instead. Use uuid when the point is that the identifier is unique per pass, such as tagging each event of a batch so downstream systems can distinguish retries.

Snowflake serves the same purpose with a different shape: its IDs are time-ordered, which makes them sortable, where a version 4 UUID is not.

Examples

Tagging an Event

Giving each event a unique handle...	{ "message": "authentication succeeded" } - uuid: target_field: event.id
which downstream systems can correlate on:	{ "message": "authentication succeeded", "event": {"id": "9f1c2b7e-6a3d-4f58-9c21-0d4e8b5a7c33"} }

Only When Absent

Generating an ID only for events that arrived without one...	{ "message": "session opened" } - uuid: if: "trace.id == null" target_field: trace.id
leaving an upstream identifier untouched where one exists:	{ "message": "session opened", "trace": {"id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"} }