Microsoft Agent Framework Workflows - Observability

Observability provides insights into the internal state and behavior of workflows during execution. This includes logging, metrics, and tracing capabilities that help monitor and debug workflows.

Tip

Observability is a framework-wide feature and is not limited to workflows. For more information, see Observability.

Aside from the standard GenAI telemetry, Agent Framework Workflows emits additional spans, logs, and metrics to provide deeper insights into workflow execution. These observability features help developers understand the flow of messages, the performance of executors, and any errors that might occur.

Enable Observability

Please refer to Enabling Observability for instructions on enabling observability in your applications.

Workflow Spans

The following spans are emitted during workflow execution:

Span Name	Description
`workflow.build`	Emitted for each workflow build.
`workflow.session`	Outer span representing the entire lifetime of a workflow execution, from start until stop or error.
`workflow_invoke`	Emitted for each input-to-halt cycle within a workflow session.
`executor.process {executor_id}`	Emitted for each executor processing a message. The executor ID is appended to the span name.
`edge_group.process`	Emitted for each edge group processing a message.
`message.send`	Emitted for each message sent from an executor to another executor.

The following spans are emitted during workflow execution:

Span Name	Description
`workflow.build`	Emitted for each workflow build.
`workflow.run`	Emitted for each workflow execution.
`executor.process {executor_id}`	Emitted for each executor processing a message. The executor ID is appended to the span name.
`edge_group.process {edge_group_type}`	Emitted for each edge group processing a message. The edge group type is appended to the span name.
`message.send`	Emitted for each message sent from an executor to another executor.

The following spans are emitted during workflow execution:

Span Name	Description
`workflow.build`	Emitted for each workflow build.
`workflow.session`	Outer span representing the lifetime of a workflow execution session.
`workflow_invoke`	Emitted for each input-to-halt cycle within a workflow session.
`executor.process {executor_id}`	Emitted for each executor processing a message. The executor ID is appended to the span name.
`edge_group.process`	Emitted for each edge group processing a message.
`message.send`	Emitted for each message sent from one executor to another.

Span Attributes

Spans carry attributes that provide additional context about the operation. The following attributes are set on workflow spans:

Attribute	Span(s)	Description
`workflow.id`	`workflow.build`, `workflow.session`	The unique identifier of the workflow.
`workflow.name`	`workflow.session`	The name of the workflow.
`workflow.description`	`workflow.session`	The description of the workflow.
`workflow.definition`	`workflow.build`	The JSON definition of the workflow graph.
`session.id`	`workflow.session`	The unique session identifier.
`executor.id`	`executor.process`	The unique identifier of the executor.
`executor.type`	`executor.process`	The type name of the executor.
`executor.input`	`executor.process`	The input message. Only set when sensitive data is enabled.
`executor.output`	`executor.process`	The output of the executor. Only set when sensitive data is enabled.
`message.type`	`executor.process`, `message.send`	The type name of the message.
`message.content`	`message.send`	The message content. Only set when sensitive data is enabled.
`message.source_id`	`message.send`	The ID of the executor that sent the message.
`message.target_id`	`message.send`	The ID of the target executor, if specified.
`edge_group.type`	`edge_group.process`	The type of the edge group.
`edge_group.delivered`	`edge_group.process`	Whether the message was delivered (boolean).
`edge_group.delivery_status`	`edge_group.process`	The delivery outcome (see Edge Group Delivery Status).
`error.type`	Any span on error	The exception type name.

Attribute	Span(s)	Description
`workflow.id`	`workflow.build`, `workflow.run`	The unique identifier of the workflow.
`workflow.name`	`workflow.run`	The name of the workflow.
`workflow.description`	`workflow.run`	The description of the workflow.
`workflow.definition`	`workflow.build`	The JSON definition of the workflow graph.
`workflow_builder.name`	`workflow.build`	The name of the workflow builder.
`workflow_builder.description`	`workflow.build`	The description of the workflow builder.
`executor.id`	`executor.process`	The unique identifier of the executor.
`executor.type`	`executor.process`	The type name of the executor.
`message.type`	`executor.process`, `message.send`	The type name of the message.
`message.payload_type`	`executor.process`	The data type of the message payload.
`message.destination_executor_id`	`message.send`	The ID of the target executor, if specified.
`message.source_id`	`edge_group.process`	The ID of the executor that sent the message.
`message.target_id`	`edge_group.process`	The ID of the target executor, if specified.
`edge_group.type`	`edge_group.process`	The type of the edge group.
`edge_group.id`	`edge_group.process`	The unique identifier of the edge group.
`edge_group.delivered`	`edge_group.process`	Whether the message was delivered (boolean).
`edge_group.delivery_status`	`edge_group.process`	The delivery outcome (see Edge Group Delivery Status).

Attribute	Span(s)	Description
`workflow.id`	`workflow.build`, `workflow.session`, `workflow_invoke`	The workflow start executor ID.
`workflow.name`	`workflow.session`, `workflow_invoke`	The workflow name, when set.
`workflow.description`	`workflow.session`, `workflow_invoke`	The workflow description, when set.
`workflow.definition`	`workflow.build`	The JSON definition of the workflow graph.
`session.id`	`workflow.session`, `workflow_invoke`	The workflow session identifier.
`executor.id`	`executor.process`	The executor ID.
`executor.implementation.id`	`executor.process`	The executor implementation ID.
`executor.input`	`executor.process`	The input message. Only set when sensitive data is enabled.
`executor.output`	`executor.process`	The executor output. Only set when sensitive data is enabled.
`message.type`	`executor.process`	The type name of the processed message.
`message.content`	`message.send`	The message content. Only set when sensitive data is enabled.
`message.source_id`	`edge_group.process`, `message.send`	The ID of the executor that sent the message.
`message.target_id`	`edge_group.process`, `message.send`	The target executor ID, when specified.
`edge_group.type`	`edge_group.process`	The type of edge group being processed.
`edge_group.delivered`	`edge_group.process`	Whether the message was delivered.
`edge_group.delivery_status`	`edge_group.process`	The delivery outcome (see Edge Group Delivery Status).
`error.type`	Any span on error	The exception type name.
`error.message`	Any span on error	The exception message.

Span Events

Span events are structured log entries attached to spans, providing a timeline of key moments within each span.

Event Name	Span(s)	Description
`build.started`	`workflow.build`	Emitted when the build process begins.
`build.validation_completed`	`workflow.build`	Emitted when build validation passes.
`build.completed`	`workflow.build`	Emitted when the build completes successfully.
`build.error`	`workflow.build`	Emitted when the build fails.
`session.started`	`workflow.session`	Emitted when a workflow session begins.
`session.completed`	`workflow.session`	Emitted when a workflow session completes.
`session.error`	`workflow.session`	Emitted when a workflow session encounters an error.
`workflow.started`	`workflow_invoke`	Emitted when a workflow invocation begins.
`workflow.completed`	`workflow_invoke`	Emitted when a workflow invocation completes.
`workflow.error`	`workflow_invoke`	Emitted when a workflow invocation encounters an error.