OpenTelemetry
|
Preview — This feature is functional and tested, but backward compatibility is not guaranteed across releases. |
Quarkus Flow provides built-in OpenTelemetry instrumentation, enabling observational insight into your workflow executions.
|
This functionality is tech preview and is currently best suited for straight-through workflow executions. |
Configuring OpenTelemetry
To enable OpenTelemetry, you must add the following dependency to your project:
<dependency>
<groupId>io.quarkiverse.flow</groupId>
<artifactId>quarkus-flow-opentelemetry</artifactId>
</dependency>
Once the dependency is added, workflow executions will start producing OpenTelemetry information automatically.
|
To disable Quarkus Flow OpenTelemetry specifically, set quarkus.flow.otel.enabled=false (in application.properties or as a system/environment property at startup), or simply remove the dependency.
Produced Spans
Quarkus Flow generates two main types of spans to trace workflow execution:
Workflow Spans: Represent the end-to-end lifecycle of a workflow instance, from its initial trigger to completion, failure or cancellation.
Task Spans: Represent the execution of a workflow task within the context of a parent workflow.
Task spans automatically reflect the workflow hierarchy, attaching as children to either the parent workflow span or another task span.
Workflow Spans
Workflow spans represent the overall execution of a workflow instance and includes the following information:
-
Span Name Format:
workflow.execute <workflow-name> -
Example,
workflow.execute order-processing
| Attribute Name | Type | Description |
|---|---|---|
|
String |
Identifier of the Quarkus Flow application. |
|
String |
Name of the executed workflow. |
|
String |
Unique execution id generated for this specific workflow run. |
|
String |
Namespace of the executed workflow. |
|
String |
Version of the executed workflow. |
|
String |
|
|
String |
Name of the agent. Only present when the workflow itself is an agent. |
|
String |
The workflow’s |
Task Spans
Task spans represent the execution of a workflow task and includes the following information:
-
Span Name Format:
task.execute <task-name> -
Example,
task.execute Submit Order
| Attribute Name | Type | Description |
|---|---|---|
|
String |
Identifier of the Quarkus Flow application. |
|
String |
Name of the executed parent workflow. |
|
String |
Unique execution id of the parent workflow execution. |
|
String |
Namespace of the executed parent workflow. |
|
String |
Version of the executed parent workflow. |
|
String |
Name of the executed task. |
|
String |
Type of executed task. Can be any of the following values: |
|
String |
Identifier of the executed task. |
|
Integer |
Number of the current task iteration. |
|
Boolean |
True if the task execution is a retry of a previous failing attempt, false in any other case. |
|
Integer |
Number of retry if the task execution is a retry of a previous failing attempt, 0 in any other case. |
|
String |
|
|
String |
Name of the invoked agent. For tasks created with |
|
Use meaningful names for your workflows and tasks. Because span names and attributes directly reflect your workflow definitions, well-named tasks result in much cleaner and readable traces in your telemetry UI. |
Task-Specific Attributes
In addition to the standard task attributes, certain task types produce specialized attributes relevant to their execution.
Call Http Task Attributes
Tasks of type call_http produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
HTTP request method configured in the workflow definition. |
|
String |
URL configured in the workflow definition. |
Call gRPC Task Attributes
Tasks of type call_grpc produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
GRPC method configured in the workflow definition. |
|
String |
GRPC service configured in the workflow definition. |
|
String |
GRPC host configured in the workflow definition. |
|
Integer |
GRPC port configured in the workflow definition. |
Call OpenAPI Task Attributes
Tasks of type call_openapi produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
The id of the OpenAPI operation to call configured in the workflow definition. |
|
String |
Name of the referred external resource with the OpenAPI document. Only present if configured in the workflow definition. |
|
String |
URL of the OpenAPI document. Only present if configured in the workflow definition. |
Call Function Task Attributes
Tasks of type call_function produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
Name of the function to call configured in the workflow definition. |
Call A2A Task Attributes
Tasks of type call_a2a produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
Name of the A2A JSON-RPC method to execute configured in the workflow definition. |
|
String |
URI of the A2A server to call. Only present if configured in the workflow definition. |
|
String |
Name of the referred external resource with the AgentCard that describes the agent to call. Only present if configured in the workflow definition. |
|
String |
URL of the resource with the AgentCard that describes the agent to call. Only present if configured in the workflow definition. |
Run Task Attributes
Tasks of type run produce these additional attributes based on the executed kind: workflow, container, script or shell.
| Attribute Name | Type | Applies When | Description |
|---|---|---|---|
|
String |
Always |
Reflects the configured execution variant in the workflow definition: |
|
String |
|
Namespace of the workflow to run configured in the workflow definition. |
|
String |
|
Name of the workflow to run configured in the workflow definition. |
|
String |
|
Version of the workflow to run configured in the workflow definition. |
|
String |
|
Name of the container to run configured in the workflow definition. |
|
String |
|
Full container image name and tag configured in the workflow definition. |
|
String |
|
Container command to execute configured in the workflow definition. |
|
String |
|
Language of the script to execute configured in the workflow definition. |
|
String |
|
Inline script code to execute. Only present if configured in the workflow definition. |
|
String |
|
Name of the referred external resource with the source of the script to execute. Only present if configured in the workflow definition. |
|
String |
|
Full URL of the document with the source of the script to execute. Only present if configured in the workflow definition. |
|
String |
|
Command to execute configured in the workflow definition. |
Wait Task Attributes
Tasks of type wait produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
Literal ISO 8601 duration. Only present if configured in the workflow definition. |
|
String |
Duration expression. Only present if configured in the workflow definition. |
|
Integer |
Days of the configured duration. Only present if configured in the workflow definition. |
|
Integer |
Hours of the configured duration. Only present if configured in the workflow definition. |
|
Integer |
Minutes of the configured duration. Only present if configured in the workflow definition. |
|
Integer |
Seconds of the configured duration. Only present if configured in the workflow definition. |
|
Integer |
Milliseconds of the configured duration. Only present if configured in the workflow definition. |
Emit Task Attributes
Tasks of type emit produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
Identifier of the emitted event. Only present if configured in the workflow definition. |
|
String |
Type of the emitted event. Only present if configured in the workflow definition. |
|
String |
Source of the emitted event. Only present if configured in the workflow definition. |
|
String |
Subject of the emitted event. Only present if configured in the workflow definition. |
Raise Task Attributes
Tasks of type raise produce these additional attributes:
| Attribute Name | Type | Description |
|---|---|---|
|
String |
Name of the referred error. Only present if configured in the workflow definition. |
|
String |
Expression defining the error type. Only present if configured in the workflow definition. |
|
String |
URI defining the error type. Only present if configured in the workflow definition. |
|
Integer |
Error status code. Only present if configured in the workflow definition. |
|
String |
Error instance. Only present if configured in the workflow definition. |
|
String |
Error title. Only present if configured in the workflow definition. |
|
String |
Error details. Only present if configured in the workflow definition. |
Trace Context Propagation
Spans created inside a task
While a Java function call task runs, its task.execute span is the current span. These are the tasks created with the Java DSL’s function(..), consume(..) and agent(..). Spans the task creates, such as REST client calls, JDBC queries, LangChain4j AI service calls or your own Span instances, become children of the task span. They stay in the workflow’s trace.
|
HTTP, OpenAPI, gRPC, A2A, AsyncAPI and MCP call tasks are not covered yet. Their outgoing request spans are not children of their task span:
|
To keep the task span from being current inside task bodies, set:
quarkus.flow.otel.task-span-current=false
With this setting the task span is still recorded, but Span.current() inside the task body is whatever was current on the executing thread.
Agentic workflows
When a task invokes a LangChain4j agentic system (@SequenceAgent, @ParallelAgent, @ConditionalAgent, @LoopAgent) through quarkus-flow-langchain4j, Quarkus Flow passes the trace context through the whole run:
-
The workflow generated for the agentic system becomes a child of the invoking task.
-
Each agent’s AI service call becomes a child of the task that ran it, including agents run in parallel on LangChain4j’s executor.
The whole run is a single trace:
workflow.create my-workflow
└── workflow.execute my-workflow
└── task.execute runAgents
└── workflow.create intake-agents
└── workflow.execute intake-agents
├── task.execute classify-0
│ └── langchain4j.aiservices.ClassifierAgent.classify
└── task.execute extract-1
└── workflow.create extraction-agent
└── workflow.execute extraction-agent
└── task.execute parallel
├── task.execute details-0
│ └── langchain4j.aiservices.DetailsAgent.details
└── task.execute summarize-1
└── langchain4j.aiservices.SummaryAgent.summarize
GenAI Semantic Conventions
Quarkus Flow types the spans of agent invocations according to the OpenTelemetry GenAI agent span conventions. GenAI-aware observability backends can then classify these spans as agents. Backends that keep only spans carrying a gen_ai.* attribute also keep them, even when the span ends in a later export batch than its AI children.
Which span is typed depends on what the agent is:
-
When the workflow itself is an agent, its
workflow.executespan is typed. This covers generated agentic workflows and workflows that opt in. -
When a task invokes an agent, its
task.executespan is typed. This covers tasks created with the Java DSLagent(..), and any other task that invokes a leaf LangChain4j agent, detected at runtime.
A typed span gets these attributes:
-
gen_ai.operation.name:invoke_agent -
gen_ai.agent.name: the agent name -
gen_ai.agent.description: the workflow’sdocument.summary, when it is not blank (workflow spans only)
Span names and all flow.* attributes are kept. workflow.create spans and all other task spans are never typed: a plain workflow step is not an agent, and the conventions define no operation name for it.
Generated agentic workflows
The workflows that quarkus-flow-langchain4j generates for @SequenceAgent, @ParallelAgent, @ConditionalAgent and @LoopAgent are typed automatically, in every launch mode. The agent name is the annotation’s name, or the annotated method’s name when name is not set. For the example in Agentic workflows, workflow.execute intake-agents has gen_ai.agent.name=process and workflow.execute extraction-agent has gen_ai.agent.name=extract.
Workflows built at runtime with FlowAgentsBuilderService are typed too. Their agent name is the simple name of the agent interface (UntypedAgent for untyped agents).
Typing your own workflows
Any other workflow opts in by setting the io.quarkiverse.flow.agent.name key in its document metadata. Its value becomes gen_ai.agent.name. Workflows without this key are never typed.
With the Java DSL:
@Override
public Workflow descriptor() {
return workflow("triage")
.document(d -> d.summary("Triage an incoming request")
.metadata(m -> m.metadata("io.quarkiverse.flow.agent.name", "triage")))
.tasks(/* ... */)
.build();
}
In a YAML definition:
document:
dsl: '1.0.0'
namespace: support
name: triage
version: '1.0.0'
summary: Triage an incoming request
metadata:
io.quarkiverse.flow.agent.name: triage
Agent tasks
Tasks created with the Java DSL agent(..) are agent invocations. Their task.execute span is typed, and the task name becomes gen_ai.agent.name. The workflow containing them is not typed, unless it is an agent itself.
@Override
public Workflow descriptor() {
return workflow("newsletter")
.tasks(agent("draftAgent", drafter::draft, NewsletterRequest.class), (1)
function("publish", publisher::publish, Draft.class)) (2)
.build();
}
| 1 | task.execute draftAgent has gen_ai.operation.name=invoke_agent and gen_ai.agent.name=draftAgent. |
| 2 | task.execute publish is not typed. |
Name your agent tasks: an unnamed agent(..) task gets a generated name such as function-0, which then becomes the agent name.
Nothing is added to the workflow definition for this: agent(..) holds an io.quarkiverse.flow.dsl.types.AgentFunction, and that is what the OpenTelemetry extension recognizes. There is no task-level equivalent of the document metadata key above, and no way to mark a task in a YAML definition — a YAML workflow cannot call a Java function in the first place.
Agent calls detected at runtime
A task built with the Java DSL’s plain function(..) (or consume(..)) that calls a LangChain4j @Agent directly, rather than through agent(..), is still an agent invocation — just one the build-time checks above cannot see, since nothing in the task’s definition distinguishes it from any other Java call. Quarkus Flow detects this case at runtime instead: a LangChain4j AgentListener notifies the extension whenever a leaf agent (one with no sub-agents of its own) is invoked while a task’s task.execute span is current, and the span is typed then.
@Inject
TriageAgent triageAgent;
@Override
public Workflow descriptor() {
return workflow("support")
.tasks(function("triage", email -> triageAgent.triage(email), String.class)) (1)
.build();
}
| 1 | task.execute triage is typed gen_ai.operation.name=invoke_agent, gen_ai.agent.name=triage (the LangChain4j agent’s name, not the task name), once triageAgent.triage(..) runs. |
Composite agents (@SequenceAgent, @ParallelAgent, @LoopAgent, @ConditionalAgent) are not detected this way: they become generated agentic workflows, whose workflow.execute span is already typed, so detecting them here too would duplicate the typing. A leaf sub-agent of such a workflow is detected, since it has no workflow.execute span of its own.
If a task invokes several agents, the span is typed with the first agent invoked; every invocation, including the first, also adds a gen_ai.invoke_agent span event naming the agent, so later calls are not lost.
Enabled by default; disable with:
quarkus.flow.otel.genai.detect-agent-calls=false
Runtime detection requires quarkus.flow.otel.task-span-current=true (the default), since it relies on the task span being current while the task body runs.
Limitations
-
The GenAI semantic conventions are still incubating, so attribute names may change in future versions of the conventions and of Quarkus Flow.
-
gen_ai.provider.nameis not set, although the conventions require it oninvoke_agentspans. A workflow that orchestrates several agents has no single provider. The model call spans beneath it, such as LangChain4j’s chat spans, carry the provider of each call. -
Agent calls detected at runtime type a span that has already started: attributes added after
startSpan()are invisible to samplers and toonStartSpanProcessorimplementations.gen_ai.*attributes set at build time (generated agentic workflows,agent(..)tasks, opted-in workflows) are unaffected, since they are set on theSpanBuilderbefore the span starts.