Correlation data
The SDK adds correlation metadata to outgoing messages so you can see which application, handler and earlier message
produced them. $correlationId links to the immediate triggering message; $traceId connects the wider message chain.
Adding your own trace context
Section titled “Adding your own trace context”Use Metadata.withTrace(...) for a value that should follow subsequent messages in the same flow:
Fluxzero.sendCommand(new TurnOnLight("living-room"), Metadata.empty().withTrace("operationId", "evening-routine"));Fluxzero.sendCommand(TurnOnLight("living-room"), Metadata.empty().withTrace("operationId", "evening-routine"))This adds $trace.operationId. When handling the message, the default correlation provider copies its $trace.*
entries to follow-up messages. Ordinary metadata entries are not generally propagated this way.
See Metadata for the trace helpers.
Built-in correlation fields
Section titled “Built-in correlation fields”These are string-valued metadata entries. Their presence depends on configuration and the active message-handling context; a message sent outside a handler need not have a trigger, consumer or invocation.
Application and client
Section titled “Application and client”| Metadata key | Description |
|---|---|
| $applicationId | Configured application identity, when available; not the identity of an individual process. |
| $applicationVersion | Deployed application version, when configured. |
| $taskId | Platform task or pod identity, when configured; distinct from the SDK client identity. |
| $clientId | Identity of the SDK client instance producing the message. |
| $clientName | Logical, human-readable name of that client. |
Configure the version with fluxzero.application.version (FLUXZERO_APPLICATION_VERSION) and the task identity
with FLUXZERO_TASK_ID. The standard builder adds these values when present; absent or blank settings add no value.
For other application settings, see Application properties.
Handler and tracker
Section titled “Handler and tracker”| Metadata key | Description |
|---|---|
| $consumer | Name of the active tracking consumer. |
| $tracker | Identifier of the active tracker. |
| $handler | Simple class name of the current handler, when available. |
| $invocation | Identifier of the current handler invocation. |
Trigger and message chain
Section titled “Trigger and message chain”| Metadata key | Description |
|---|---|
| $correlationId | Index of the currently handled message, or its message ID when no index is available. |
| $traceId | Trace ID inherited from the handled message, falling back to its correlation ID. |
| $trigger | Payload type name of the triggering message. |
| $triggerType | Message category of the trigger, such as COMMAND, EVENT or SCHEDULE. |
| $triggerNamespace | Namespace of the triggering message, when available. |
| $msDelay | Time in milliseconds from the handled message’s timestamp to correlation-data collection; not limited to schedules. |
The correlation ID changes as the chain moves to a new trigger; the trace ID carries the chain’s shared identity.
Use $triggerNamespace when resolving a trigger across namespaces; older messages may omit it and use the
application namespace. $msDelay is elapsed message age, not a handler execution duration.
Customizing correlation
Section titled “Customizing correlation”Fluxzero.currentCorrelationData() exposes the active correlation context. For application-wide enrichment,
use the builder’s replaceCorrelationDataProvider(...); compose with the existing provider using andThen(...)
when you want to retain the standard fields. See CorrelationDataProvider for provider
composition, context overloads and key definitions.
© 2026 Fluxzero