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 Copy linkLink copied!
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 asACTIVE,COMPLETED,ERROR, orSUSPENDED.sonataflow.transaction.id: Indicates the ID used to correlate multiple workflows in a single business transaction.sonataflow.tracker.*: Indicates custom attributes converted fromX-TRACKER-*headers.service.nameandservice.version: Indicates the service identification details from the configuration.
Process lifecycle events for timeline tracking Copy linkLink copied!
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 theprocess.instance.id, thetriggerthat started the process, and thereference.id.process.instance.complete: Indicates the completion of the workflow. This event includes theprocess.instance.id, the finaloutcome, and the totalduration.ms.process.instance.error: Indicates a workflow failure. This event includes theprocess.instance.id, theerror.message, and theerror.type.state.startedandstate.completed: Indicate the start and completion of individual workflow states. These events include anevent.descriptionthat details the state execution.log.message: Indicates the application log content within the trace span. This event provides thelevel,logger,message,thread.name, andthread.id.
Function call attributes for external integration debugging Copy linkLink copied!
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 asrestorexpression.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 Copy linkLink copied!
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 assonataflow.tracker.*, to simplify querying.