CPID

Analytics Networking

Synopsis

Generates a CPID (Common Process ID) according to RFC 9562.

Schema

- cpid:
    hostname_field: <ident>
    process_id_field: <ident>
    time_field: <ident>
    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
hostname_field	Y	-	Field containing the hostname or system identifier
process_id_field	Y	-	Field containing the process ID
time_field	Y	-	Field containing the process creation time
target_field	N	process.common_id	Field where the generated CPID will be stored
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if generation fails
ignore_missing	N	false	Continue if source fields don't exist (uses empty values)
on_failure	N	-	Error handling processors
on_success	N	-	Success handling processors
tag	N	-	Identifier for logging
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

Generates a Common Process ID (CPID) according to RFC 9562, providing a consistent way to identify unique process instances across systems and log sources. The processor creates a UUID (Version 8, Variant 1) by combining hostname, process ID, and time information.

note

ignore_missing: true substitutes an empty string for a missing hostname or process ID, and the current processing time for a missing time field.

The time substitution defeats the point of the processor: the same process yields a different CPID on every event, so nothing correlates. Prefer letting the processor fail on a missing time field over silently producing unstable identifiers.

The three inputs are joined as hostname:process_id:time and hashed, so the same three values always yield the same identifier, whatever the log source. A time field that is not RFC 3339 is used verbatim, which means two sources writing the same instant in different formats will not correlate — normalize the timestamp first.

warning

The CPID algorithm uses SHA-256 hashing to generate consistent identifiers. For optimal correlation, ensure that the input fields contain stable and consistent values across log sources.

Examples

Basic CPID Generation

Generating a CPID from standard fields...	{ "host": { "name": "web-server-01" }, "process": { "pid": 1234, "created_at": "2023-06-15T10:30:45Z" } } - cpid: hostname_field: host.name process_id_field: process.pid time_field: process.created_at
creates a standardized process ID:	{ "host": { "name": "web-server-01" }, "process": { "pid": 1234, "created_at": "2023-06-15T10:30:45Z", "common_id": "06cf14ab-eeac-8d76-9a2c-878808dacff4" } }

Custom Target Field

Storing CPID in a custom field...	{ "system": "database-01", "proc_info": { "id": 5678, "start_time": "2023-07-10T08:15:22Z" } } - cpid: hostname_field: system process_id_field: proc_info.id time_field: proc_info.start_time target_field: proc_info.uuid
with custom field placement:	{ "system": "database-01", "proc_info": { "id": 5678, "start_time": "2023-07-10T08:15:22Z", "uuid": "7bcef0ab-89e8-8ecc-ae9a-392ce1bbccc7" } }

Handling Missing Fields

Continuing processing despite missing fields...	{ "host": "app-server-05", "process": { "id": 9012 } } - cpid: hostname_field: host process_id_field: process.id time_field: process.created ignore_missing: true
substitutes the current time, so the value differs on every run — the identifier is no longer stable for that process:	{ "host": "app-server-05", "process": { "id": 9012, "common_id": "<varies per run>" } }