Skip to content

Commit 4fae498

Browse files
baywetCopilot
andcommitted
Python: include workflow names in invocation spans
Prepare workflow span names and attributes together so named invocation spans preserve operation and scoped conversation attributes. Cover both span factories, graph and functional workflows, AG-UI propagation, and unnamed fallback behavior. Co-authored-by: Copilot <[email protected]> Copilot-Session: aa4dae7a-fdbd-475c-8ec6-fa8333e77cc4
1 parent 2376062 commit 4fae498

7 files changed

Lines changed: 49 additions & 22 deletions

File tree

‎python/packages/ag-ui/tests/ag_ui/test_workflow_run.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -601,7 +601,7 @@ async def passthrough_middleware(_context: AgentContext, call_next: Any) -> None
601601
"ag-ui-workflow-thread",
602602
]
603603

604-
workflow_spans = [span for span in exporter.get_finished_spans() if span.name == "invoke_workflow"]
604+
workflow_spans = [span for span in exporter.get_finished_spans() if span.name == f"invoke_workflow {workflow.name}"]
605605
assert len(workflow_spans) == 2
606606
workflow_conversation_ids = []
607607
for span in workflow_spans:
@@ -631,7 +631,9 @@ async def passthrough_middleware(_context: AgentContext, call_next: Any) -> None
631631
assert fallback_agent_span.attributes is not None
632632
assert fallback_agent_span.attributes.get("gen_ai.conversation.id") == "provider-conversation"
633633

634-
fallback_workflow_span = next(span for span in exporter.get_finished_spans() if span.name == "invoke_workflow")
634+
fallback_workflow_span = next(
635+
span for span in exporter.get_finished_spans() if span.name == f"invoke_workflow {workflow.name}"
636+
)
635637
assert fallback_workflow_span.attributes is not None
636638
assert "gen_ai.conversation.id" not in fallback_workflow_span.attributes
637639

‎python/packages/core/agent_framework/observability.py‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3657,17 +3657,19 @@ def workflow_tracer() -> Tracer:
36573657
return get_tracer() if OBSERVABILITY_SETTINGS.ENABLED else trace.NoOpTracer()
36583658

36593659

3660-
def _workflow_span_attributes(
3660+
def _prepare_workflow_span(
36613661
name: str,
36623662
attributes: Mapping[str, str | int] | None = None,
3663-
) -> dict[str, str | int] | None:
3663+
) -> tuple[str, dict[str, str | int] | None]:
36643664
span_attributes: dict[str, str | int] = dict(attributes) if attributes is not None else {}
36653665
conversation_id = _TELEMETRY_CONVERSATION_ID.get()
36663666
if name == OtelAttr.WORKFLOW_RUN_SPAN:
36673667
span_attributes[OtelAttr.OPERATION] = "invoke_workflow"
36683668
if conversation_id is not None:
36693669
span_attributes.setdefault(OtelAttr.CONVERSATION_ID, conversation_id)
3670-
return span_attributes or None
3670+
if workflow_name := span_attributes.get(OtelAttr.WORKFLOW_NAME):
3671+
name = f"{name} {workflow_name}"
3672+
return name, span_attributes or None
36713673

36723674

36733675
@contextlib.contextmanager
@@ -3695,11 +3697,12 @@ def create_workflow_span(
36953697
generator is later closed on GC from a different ``Context``. Streaming
36963698
workflow runs should use :func:`start_workflow_span` instead.
36973699
"""
3700+
name, span_attributes = _prepare_workflow_span(name, attributes)
36983701
return _capture_span_exceptions(
36993702
workflow_tracer().start_as_current_span(
37003703
name,
37013704
kind=kind,
3702-
attributes=_workflow_span_attributes(name, attributes),
3705+
attributes=span_attributes,
37033706
record_exception=False,
37043707
set_status_on_exception=False,
37053708
)
@@ -3719,7 +3722,8 @@ def start_workflow_span(
37193722
across a yield causes ``ValueError: Token was created in a different
37203723
Context`` when the generator is garbage-collected.
37213724
"""
3722-
return workflow_tracer().start_span(name, kind=kind, attributes=_workflow_span_attributes(name, attributes))
3725+
name, span_attributes = _prepare_workflow_span(name, attributes)
3726+
return workflow_tracer().start_span(name, kind=kind, attributes=span_attributes)
37233727

37243728

37253729
def create_processing_span(

‎python/packages/core/tests/core/test_observability.py‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3074,31 +3074,44 @@ def test_start_workflow_span_does_not_attach_as_current(span_exporter: InMemoryS
30743074
assert spans[0].attributes["key"] == "value" # type: ignore[index] # pyrefly: ignore[unsupported-operation] # ty: ignore[not-subscriptable]
30753075

30763076

3077-
def test_create_workflow_span_uses_scoped_conversation_id(span_exporter: InMemorySpanExporter) -> None:
3078-
"""An ambient conversation id is applied only within its workflow execution scope."""
3077+
@pytest.mark.parametrize("workflow_name", [None, "", "customer_support_pipeline"])
3078+
@pytest.mark.parametrize("unattached", [False, True])
3079+
def test_workflow_span_uses_scoped_conversation_id(
3080+
span_exporter: InMemorySpanExporter, workflow_name: str | None, unattached: bool
3081+
) -> None:
3082+
"""Named and unnamed workflow spans retain scoped conversation ids with either span factory."""
30793083
from agent_framework.observability import (
30803084
OtelAttr,
30813085
_use_telemetry_conversation_id, # pyright: ignore[reportPrivateUsage]
30823086
create_workflow_span,
3087+
start_workflow_span,
30833088
)
30843089

3090+
span_factory = start_workflow_span if unattached else create_workflow_span
3091+
attributes: dict[str, str | int] = {OtelAttr.WORKFLOW_NAME: workflow_name} if workflow_name is not None else {}
30853092
span_exporter.clear() # type: ignore[attr-defined]
30863093
with _use_telemetry_conversation_id("application-thread"):
3087-
with create_workflow_span(OtelAttr.WORKFLOW_RUN_SPAN):
3094+
with span_factory(OtelAttr.WORKFLOW_RUN_SPAN, attributes=attributes):
30883095
pass
3089-
with create_workflow_span(
3096+
with span_factory(
30903097
OtelAttr.WORKFLOW_RUN_SPAN,
3091-
attributes={OtelAttr.CONVERSATION_ID: "explicit-thread"},
3098+
attributes={**attributes, OtelAttr.CONVERSATION_ID: "explicit-thread"},
30923099
):
30933100
pass
3094-
with create_workflow_span(OtelAttr.MESSAGE_SEND_SPAN):
3101+
with span_factory(OtelAttr.MESSAGE_SEND_SPAN, attributes=attributes):
30953102
pass
3096-
with create_workflow_span(OtelAttr.WORKFLOW_RUN_SPAN):
3103+
with span_factory(OtelAttr.WORKFLOW_RUN_SPAN, attributes=attributes):
30973104
pass
30983105

30993106
spans = span_exporter.get_finished_spans() # type: ignore[attr-defined]
3100-
workflow_spans = [span for span in spans if span.name == OtelAttr.WORKFLOW_RUN_SPAN]
3107+
workflow_spans = [
3108+
span
3109+
for span in spans
3110+
if span.attributes is not None and span.attributes.get(OtelAttr.OPERATION) == "invoke_workflow"
3111+
]
31013112
assert len(workflow_spans) == 3
3113+
expected_name = f"invoke_workflow {workflow_name}" if workflow_name else "invoke_workflow"
3114+
assert all(span.name == expected_name for span in workflow_spans)
31023115
ambient_attributes = workflow_spans[0].attributes
31033116
explicit_attributes = workflow_spans[1].attributes
31043117
unscoped_attributes = workflow_spans[2].attributes
@@ -3112,6 +3125,9 @@ def test_create_workflow_span_uses_scoped_conversation_id(span_exporter: InMemor
31123125
message_send_attributes = message_send_span.attributes
31133126
assert message_send_attributes is not None
31143127
assert OtelAttr.CONVERSATION_ID not in message_send_attributes
3128+
assert OtelAttr.OPERATION not in message_send_attributes
3129+
assert OtelAttr.CONVERSATION_ID not in attributes
3130+
assert OtelAttr.OPERATION not in attributes
31153131

31163132

31173133
def test_create_processing_span(span_exporter):

‎python/packages/core/tests/workflow/test_functional_workflow.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -648,7 +648,7 @@ async def pipeline(x: int) -> int:
648648
assert result.get_outputs() == [6]
649649

650650
spans = span_exporter.get_finished_spans() # type: ignore[attr-defined]
651-
run_spans = [s for s in spans if s.name == OtelAttr.WORKFLOW_RUN_SPAN]
651+
run_spans = [s for s in spans if s.name == f"invoke_workflow {pipeline.name}"]
652652
process_spans = [s for s in spans if s.name == f"{OtelAttr.EXECUTOR_PROCESS_SPAN} traced_add"]
653653
assert len(run_spans) == 1
654654
assert len(process_spans) == 1

‎python/packages/core/tests/workflow/test_workflow.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1434,7 +1434,7 @@ def capture_loop_exception(_loop: asyncio.AbstractEventLoop, context: dict[str,
14341434
if "Failed to detach context" in rec.getMessage() or "was created in a different Context" in rec.getMessage()
14351435
]
14361436
assert otel_errors == [], f"Abandoned stream leaked OpenTelemetry errors: {otel_errors!r}"
1437-
assert any(span.name == "invoke_workflow" for span in span_exporter.get_finished_spans())
1437+
assert any(span.name == f"invoke_workflow {workflow.name}" for span in span_exporter.get_finished_spans())
14381438

14391439

14401440
async def test_workflow_unawaited_run_coroutine_releases_run_lock() -> None:

‎python/packages/core/tests/workflow/test_workflow_observability.py‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -153,11 +153,12 @@ async def simple_workflow(message: str) -> str:
153153
if any(event.name == "workflow.started" for event in span.events)
154154
]
155155
assert len(run_spans) == 1
156-
assert run_spans[0].name == "invoke_workflow"
156+
expected_name = workflow_name or "simple_workflow"
157+
assert run_spans[0].name == f"invoke_workflow {expected_name}"
157158
attributes = run_spans[0].attributes
158159
assert attributes is not None
159160
assert "workflow.name" not in attributes
160-
assert attributes["gen_ai.workflow.name"] == (workflow_name or "simple_workflow")
161+
assert attributes["gen_ai.workflow.name"] == expected_name
161162
assert attributes["gen_ai.operation.name"] == "invoke_workflow"
162163

163164

@@ -403,7 +404,7 @@ async def test_end_to_end_workflow_tracing(span_exporter: InMemorySpanExporter)
403404

404405
# Should have workflow span, processing spans, and sending spans
405406
# Processing spans now use executor_id as the span name, filter by executor.id attribute
406-
workflow_spans = [s for s in spans if s.name == "invoke_workflow"]
407+
workflow_spans = [s for s in spans if s.name == f"invoke_workflow {workflow.name}"]
407408
processing_spans = [s for s in spans if _span_attributes(s).get("executor.id") is not None]
408409
sending_spans = [s for s in spans if s.name == "message.send"]
409410
build_spans_after_run = [s for s in spans if s.name == "workflow.build"]
@@ -508,7 +509,7 @@ async def handle_message(self, message: str, ctx: WorkflowContext) -> None:
508509
spans = span_exporter.get_finished_spans()
509510

510511
# Find workflow span
511-
workflow_spans = [s for s in spans if s.name == "invoke_workflow"]
512+
workflow_spans = [s for s in spans if s.name == f"invoke_workflow {workflow.name}"]
512513
assert len(workflow_spans) == 1
513514

514515
workflow_span = workflow_spans[0]
@@ -586,7 +587,7 @@ async def failing_workflow(message: str) -> None:
586587
_assert_workflow_error_details(executor_failed_events[0].details, private_error_detail, enable_sensitive_data)
587588

588589
spans = span_exporter.get_finished_spans()
589-
workflow_spans = [span for span in spans if span.name == "invoke_workflow"]
590+
workflow_spans = [span for span in spans if span.name == f"invoke_workflow {workflow_instance.name}"]
590591
assert len(workflow_spans) == 1
591592
span = workflow_spans[0]
592593
assert span.attributes is not None

‎skills/agent-framework-builder-python/references/observability.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ runtime evidence; it does not determine whether output is correct.
1717
Inspect run boundaries, model calls, tool and MCP calls, workflow transitions, checkpoints, approvals, retries, usage,
1818
and hosted-service continuations. Use stable agent, workflow, and service identifiers.
1919

20+
Workflow invocation spans are named `invoke_workflow {gen_ai.workflow.name}` when the workflow-name attribute is
21+
non-empty, or `invoke_workflow` otherwise. Their `gen_ai.operation.name` is always `invoke_workflow`; supplied
22+
conversation identifiers remain available as `gen_ai.conversation.id`.
23+
2024
## Learn more
2125

2226
- [Agent observability](https://learn.microsoft.com/agent-framework/agents/observability)

0 commit comments

Comments
 (0)