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.

  • The quarkus-flow-opentelemetry extension is built on top of quarkus-opentelemetry. All configurations related to trace exporters and OTLP endpoints are managed via the standard Quarkus OpenTelemetry extension. For full configuration details, refer to the Quarkus OpenTelemetry Guide.

  • Setting either quarkus.otel.enabled=false or quarkus.otel.traces.enabled=false automatically disables the Quarkus Flow OpenTelemetry instrumentation.

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

flow.application.id

String

Identifier of the Quarkus Flow application.

flow.workflow.name

String

Name of the executed workflow.

flow.workflow.instance.id

String

Unique execution id generated for this specific workflow run.

flow.workflow.namespace

String

Namespace of the executed workflow.

flow.workflow.version

String

Version of the executed workflow.

gen_ai.operation.name

String

invoke_agent. Only present when the workflow itself is an agent: a workflow generated from a LangChain4j agentic annotation, or one that opts in through its document metadata. See GenAI Semantic Conventions.

gen_ai.agent.name

String

Name of the agent. Only present when the workflow itself is an agent.

gen_ai.agent.description

String

The workflow’s document.summary. Only present when the workflow itself is an agent and the summary is not blank.

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

flow.application.id

String

Identifier of the Quarkus Flow application.

flow.workflow.name

String

Name of the executed parent workflow.

flow.workflow.instance.id

String

Unique execution id of the parent workflow execution.

flow.workflow.namespace

String

Namespace of the executed parent workflow.

flow.workflow.version

String

Version of the executed parent workflow.

flow.task.name

String

Name of the executed task.

flow.task.type

String

Type of executed task. Can be any of the following values: do, emit, for, fork, listen, raise, run, set, switch, try, wait, call_http, call_asyncapi, call_grpc, call_openapi, call_a2a, call_function.

flow.task.id

String

Identifier of the executed task.

flow.task.iteration

Integer

Number of the current task iteration.

flow.task.retrying

Boolean

True if the task execution is a retry of a previous failing attempt, false in any other case.

flow.task.retry_attempt

Integer

Number of retry if the task execution is a retry of a previous failing attempt, 0 in any other case.

gen_ai.operation.name

String

invoke_agent. Present on tasks created with the Java DSL agent(..) (see Agent tasks), and on any other task that invokes a leaf LangChain4j agent, detected at runtime (see Agent calls detected at runtime).

gen_ai.agent.name

String

Name of the invoked agent. For tasks created with agent(..), this is the task name. For agent calls detected at runtime, this is the LangChain4j agent name.

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

flow.task.call.http.request.method

String

HTTP request method configured in the workflow definition.

flow.task.call.http.url.full

String

URL configured in the workflow definition.

Call gRPC Task Attributes

Tasks of type call_grpc produce these additional attributes:

Attribute Name Type Description

flow.task.call.grpc.method

String

GRPC method configured in the workflow definition.

flow.task.call.grpc.service

String

GRPC service configured in the workflow definition.

flow.task.call.grpc.server.address

String

GRPC host configured in the workflow definition.

flow.task.call.grpc.server.port

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

flow.task.call.openapi.operation_id

String

The id of the OpenAPI operation to call configured in the workflow definition.

flow.task.call.openapi.document.name

String

Name of the referred external resource with the OpenAPI document. Only present if configured in the workflow definition.

flow.task.call.openapi.document.url.full

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

flow.task.call.function.name

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

flow.task.call.a2a.method

String

Name of the A2A JSON-RPC method to execute configured in the workflow definition.

flow.task.call.a2a.server.url.full

String

URI of the A2A server to call. Only present if configured in the workflow definition.

flow.task.call.a2a.agent_card.name

String

Name of the referred external resource with the AgentCard that describes the agent to call. Only present if configured in the workflow definition.

flow.task.call.a2a.agent_card.url.full

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

flow.task.run.kind

String

Always

Reflects the configured execution variant in the workflow definition: workflow, container, script, or shell.

flow.task.run.workflow.namespace

String

workflow

Namespace of the workflow to run configured in the workflow definition.

flow.task.run.workflow.name

String

workflow

Name of the workflow to run configured in the workflow definition.

flow.task.run.workflow.version

String

workflow

Version of the workflow to run configured in the workflow definition.

flow.task.run.container.name

String

container

Name of the container to run configured in the workflow definition.

flow.task.run.container.image.name

String

container

Full container image name and tag configured in the workflow definition.

flow.task.run.container.command

String

container

Container command to execute configured in the workflow definition.

flow.task.run.script.language

String

script

Language of the script to execute configured in the workflow definition.

flow.task.run.script.code

String

script

Inline script code to execute. Only present if configured in the workflow definition.

flow.task.run.script.source.name

String

script

Name of the referred external resource with the source of the script to execute. Only present if configured in the workflow definition.

flow.task.run.script.source.url.full

String

script

Full URL of the document with the source of the script to execute. Only present if configured in the workflow definition.

flow.task.run.shell.command

String

shell

Command to execute configured in the workflow definition.

Wait Task Attributes

Tasks of type wait produce these additional attributes:

Attribute Name Type Description

flow.task.wait.duration.literal

String

Literal ISO 8601 duration. Only present if configured in the workflow definition.

flow.task.wait.duration.expression

String

Duration expression. Only present if configured in the workflow definition.

flow.task.wait.duration.days

Integer

Days of the configured duration. Only present if configured in the workflow definition.

flow.task.wait.duration.hours

Integer

Hours of the configured duration. Only present if configured in the workflow definition.

flow.task.wait.duration.minutes

Integer

Minutes of the configured duration. Only present if configured in the workflow definition.

flow.task.wait.duration.seconds

Integer

Seconds of the configured duration. Only present if configured in the workflow definition.

flow.task.wait.duration.milliseconds

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

flow.task.emit.event.id

String

Identifier of the emitted event. Only present if configured in the workflow definition.

flow.task.emit.event.type

String

Type of the emitted event. Only present if configured in the workflow definition.

flow.task.emit.event.source

String

Source of the emitted event. Only present if configured in the workflow definition.

flow.task.emit.event.subject

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

flow.task.raise.error.reference

String

Name of the referred error. Only present if configured in the workflow definition.

flow.task.raise.error.type.expression

String

Expression defining the error type. Only present if configured in the workflow definition.

flow.task.raise.error.type.uri

String

URI defining the error type. Only present if configured in the workflow definition.

flow.task.raise.error.status

Integer

Error status code. Only present if configured in the workflow definition.

flow.task.raise.error.instance

String

Error instance. Only present if configured in the workflow definition.

flow.task.raise.error.title

String

Error title. Only present if configured in the workflow definition.

flow.task.raise.error.details

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:

  • When the workflow is started from an incoming request, they are children of that request’s span.

  • Otherwise, they start their own trace.

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:

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’s document.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.name is not set, although the conventions require it on invoke_agent spans. 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 to onStart SpanProcessor implementations. gen_ai.* attributes set at build time (generated agentic workflows, agent(..) tasks, opted-in workflows) are unaffected, since they are set on the SpanBuilder before the span starts.