Trace attributes and lifecycle events

Reference information about span attributes and lifecycle events that SonataFlow automatically generates for workflow executions.

Use this data dictionary to build Jaeger queries, filter traces by workflow state, and track requests across service boundaries. This data allows you to track a workflow from start to finish, analyze external function calls, and correlate logs across asynchronous boundaries.

Trace attribute definitions and filtering keys

Automatic span attributes that identify workflow executions, instances, and states. Use these attributes in Jaeger queries to locate specific workflow runs, filter by version, or trace process instances through various execution states.

To locate specific workflow executions or trace a process through various states, use the automatic span attributes generated by SonataFlow. Each span includes the following specific attributes:

  • sonataflow.process.id: Indicates the ID of the workflow definition.
  • sonataflow.process.instance.id: Indicates the unique ID for the specific execution instance.
  • sonataflow.process.version: Indicates the version of the workflow definition.
  • sonataflow.workflow.state: Indicates the name of the current workflow state, for example, StartEvent.
  • sonataflow.process.instance.state: Indicates the current state of the process instance, such as ACTIVE, COMPLETED, ERROR, or SUSPENDED.
  • sonataflow.transaction.id: Indicates the ID used to correlate multiple workflows in a single business transaction.
  • sonataflow.tracker.*: Indicates custom attributes converted from X-TRACKER-* headers.
  • service.name and service.version: Indicates the service identification details from the configuration.

Process lifecycle events for timeline tracking

OpenTelemetry events that mark workflow execution milestones including start, completion, errors, and state transitions. Use these events to reconstruct the chronological order of workflow execution and identify when failures occurred.

To understand the exact chronological order of a workflow’s execution, look for OpenTelemetry events that are automatically generated at key lifecycle points. SonataFlow attaches the following events and their specific attributes to spans to mark execution milestones:

  • process.instance.start: Indicates the beginning of the execution. This event includes the process.instance.id, the trigger that started the process, and the reference.id.
  • process.instance.complete: Indicates the completion of the workflow. This event includes the process.instance.id, the final outcome, and the total duration.ms.
  • process.instance.error: Indicates a workflow failure. This event includes the process.instance.id, the error.message, and the error.type.
  • state.started and state.completed: Indicate the start and completion of individual workflow states. These events include an event.description that details the state execution.
  • log.message: Indicates the application log content within the trace span. This event provides the level, logger, message, thread.name, and thread.id.

Function call attributes for external integration debugging

HTTP and function-specific attributes attached to external service call spans. Use these attributes to debug REST API failures, identify slow external dependencies, and verify correct endpoint invocation in workflow integrations.

When a workflow invokes an external function, for example, a REST service, the function call spans are enriched with additional HTTP attributes:

  • sonataflow.function.name: The name of the function being called.
  • sonataflow.function.type: The type of function, such as rest or expression.
  • http.method: The HTTP method used for external REST calls.
  • http.url: The full target URL for the external call.
  • http.status_code: The resulting HTTP response code from the service.

Propagation headers

HTTP headers that SonataFlow extracts and propagates to maintain trace correlation across service boundaries. Use these headers to link workflow executions in distributed transactions and pass custom tracking context through service chains.

SonataFlow extracts and propagates the following headers to maintain observability across service boundaries:

  • X-TRANSACTION-ID: Correlates multiple workflow executions that belong to the same business transaction.
  • X-TRACKER-*: Sanitizes and converts any custom tracking context from headers into span attributes, such as sonataflow.tracker.*, to simplify querying.