feat: add ReferenceContext for span reference hierarchy propagation by jepadil23 · Pull Request #1708 · UiPath/uipath-python

jepadil23 · 2026-06-10T19:10:06Z

Summary

Adds ReferenceContext — an immutable, copy-on-write ordered list of ReferenceEntry objects (serviceType, referenceId, version) that flows via contextvars.ContextVar across await boundaries
_span_utils.py reads from ReferenceContextAccessor to populate UiPathSpan.context.referenceHierarchy — wire-format compatible with service-common x-uipath-tracebaggage header
Fixes BatchSpanProcessor thread-boundary issue by stamping the hierarchy as a span attribute at span start
Normalizes empty-string env vars (UIPATH_ORGANIZATION_ID, UIPATH_TENANT_ID, UIPATH_FOLDER_KEY) to None for Guid fields in UiPathSpan

Test plan

tests/services/test_reference_context.py — unit tests for ReferenceContext, ReferenceEntry, and ReferenceContextAccessor (push/pop/reset, async propagation, wire serialization)
Verify UiPathSpan.context.referenceHierarchy is populated when ReferenceContextAccessor has entries set upstream
Verify empty-string env vars normalize to None in span fields

🤖 Generated with Claude Code

Introduces an immutable, copy-on-write ReferenceContext (modelled after service-common BaggageContext) that propagates the reference hierarchy through all spans emitted to LLMOps/Traceview. - `_reference_context.py`: ReferenceEntry, ReferenceContext (add / to_wire_list / from_baggage_header / to_baggage_header_value), ReferenceContextAccessor (ContextVar-backed, async-safe) - `_span_utils.py`: UiPathSpan gains `context` field; to_dict() emits `Context.referenceHierarchy` when set; otel_span_to_uipath_span() reads ReferenceContextAccessor and builds the wire payload - `uipath.tracing`: re-exports ReferenceEntry, ReferenceContext, ReferenceContextAccessor for downstream consumers - Tests: 30 new tests covering immutability, wire format, baggage header round-trip, accessor lifecycle, and span wiring Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…hSpan UIPATH_FOLDER_KEY, UIPATH_ORGANIZATION_ID, and UIPATH_TENANT_ID default to "" when unset. SpanReq.FolderKey is Guid? on the server — sending "" causes a JSON deserialization exception ("could not convert to System.Nullable[Guid]") which cascades into "The spans field is required" from ASP.NET's model binding. Normalize all three to None so unset vars serialize as null instead of an unparseable empty string. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…Processor thread boundary ContextVar values are not propagated to background threads. The BatchSpanProcessor exports spans in a worker thread where ReferenceContextAccessor.get() always returns None, so Context.referenceHierarchy was never populated in the wire payload. Fix: register a span-start hook (_inject_reference_hierarchy) that runs synchronously in on_start — same thread/context as the span creator — reads the ambient ReferenceContext and stamps it as uipath.reference_hierarchy on the span. The attribute travels with the span to the export thread. otel_span_to_uipath_span now reads from the attribute instead of the ContextVar, and pops it from attributes_dict so it does not appear in the wire Attributes field. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new reference-hierarchy propagation mechanism for spans by introducing an immutable ReferenceContext carried via contextvars, stamping the hierarchy onto spans at start-time to survive BatchSpanProcessor thread boundaries, and wiring that stamped hierarchy into the UiPath span wire payload (Context.referenceHierarchy).

Changes:

Introduces ReferenceContext / ReferenceEntry plus a ReferenceContextAccessor backed by ContextVar.
Adds a span-start hook mechanism in core tracing processors and uses it in _span_utils.py to stamp uipath.reference_hierarchy at span creation time.
Extends UiPathSpan serialization to emit a top-level Context field and normalizes empty-string org/tenant/folder env vars to None.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
packages/uipath/src/uipath/tracing/init.py	Re-exports `ReferenceContext*` types from platform common tracing surface.
packages/uipath-platform/src/uipath/platform/common/_reference_context.py	Adds the new immutable reference hierarchy model + ContextVar accessor + header (de)serialization.
packages/uipath-platform/src/uipath/platform/common/_span_utils.py	Registers a span-start hook to stamp hierarchy and wires stamped hierarchy into `UiPathSpan.Context`.
packages/uipath-platform/src/uipath/platform/common/init.py	Exposes `ReferenceContext*` from `uipath.platform.common`.
packages/uipath-core/src/uipath/core/tracing/processors.py	Adds global span-start hook registration and invokes hooks in `on_start`.
packages/uipath-platform/tests/services/test_reference_context.py	Adds unit tests for the new reference context model + span wiring behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

saksharthakkar · 2026-06-17T19:20:36Z

You'll need to bump up the version here and then use it in other repos.

saksharthakkar · 2026-06-17T19:21:14Z

Please make sure to address the review comments by Copilot and address these CI requirements
CI / check-dependency-bumps / check-dependency-bumps (pull_request)
CI / check-dependency-bumps / check-dependency-bumps (pull_request)Failing after 8s
CI / check-versions / check-version-availability (pull_request)
CI / check-versions / check-version-availability (pull_request)Failing after 6s
CI / lint / Lint (pull_request)
CI / lint / Lint (pull_request)Failing after 4s
Required
CI / lint / Lint uipath-platform (pull_request)
CI / lint / Lint uipath-platform (pull_request)Failing after 19s

Introduces an immutable, copy-on-write ReferenceContext (modelled after service-common BaggageContext) that propagates the reference hierarchy through all spans emitted to LLMOps/Traceview. - `_reference_context.py`: ReferenceEntry, ReferenceContext (add / to_wire_list / from_baggage_header / to_baggage_header_value), ReferenceContextAccessor (ContextVar-backed, async-safe) - `_span_utils.py`: UiPathSpan gains `context` field; to_dict() emits `Context.referenceHierarchy` when set; otel_span_to_uipath_span() reads ReferenceContextAccessor and builds the wire payload - `uipath.tracing`: re-exports ReferenceEntry, ReferenceContext, ReferenceContextAccessor for downstream consumers - Tests: 30 new tests covering immutability, wire format, baggage header round-trip, accessor lifecycle, and span wiring Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…Processor thread boundary ContextVar values are not propagated to background threads. The BatchSpanProcessor exports spans in a worker thread where ReferenceContextAccessor.get() always returns None, so Context.referenceHierarchy was never populated in the wire payload. Fix: register a span-start hook (_inject_reference_hierarchy) that runs synchronously in on_start — same thread/context as the span creator — reads the ambient ReferenceContext and stamps it as uipath.reference_hierarchy on the span. The attribute travels with the span to the export thread. otel_span_to_uipath_span now reads from the attribute instead of the ContextVar, and pops it from attributes_dict so it does not appear in the wire Attributes field. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

sonarqubecloud · 2026-07-06T07:00:25Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

github-actions · 2026-07-06T07:00:30Z

🚨 Heads up: `uipath-integrations` cross-tests are FAILING 🚨

Your changes may break one or more integrations in uipath-integrations-python:

uipath-openai-agents
uipath-google-adk
uipath-agent-framework
uipath-llamaindex
uipath-pydantic-ai

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

github-actions · 2026-07-06T07:02:22Z

🚨 Heads up: `uipath-langchain` cross-tests are FAILING 🚨

Your changes may break the uipath-langchain-python integration.

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

saksharthakkar · 2026-07-06T18:51:36Z

            factory = None
            try:
                trace_manager = UiPathTraceManager()
+                trace_manager.add_span_processor(ReferenceHierarchySpanProcessor())


nit: if we can avoid duplication across multiple files
by putting something like this in common place
def create_trace_manager() -> UiPathTraceManager:
tm = UiPathTraceManager()
tm.add_span_processor(ReferenceHierarchySpanProcessor()) # one ordering choke point
return tm

saksharthakkar · 2026-07-06T18:52:06Z

+        return result
+
+    @staticmethod
+    def from_baggage_header(header_value: Optional[str]) -> "ReferenceContext":


is this used any where?

jepadil23 and others added 3 commits June 8, 2026 21:12

Copilot AI review requested due to automatic review settings June 10, 2026 19:10

github-actions Bot added test:uipath-langchain Triggers tests in the uipath-langchain-python repository test:uipath-runtime test:uipath-integrations labels Jun 10, 2026

Copilot started reviewing on behalf of jepadil23 June 10, 2026 19:10 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

danflorescu96 approved these changes Jun 10, 2026

View reviewed changes

saksharthakkar reviewed Jun 17, 2026

View reviewed changes

Comment thread packages/uipath-core/src/uipath/core/tracing/processors.py Outdated

jepadil23 and others added 4 commits July 6, 2026 00:42

Merge branch 'main' into feat/reference-hierarchy-context

0f40c2d

fix(traceview): fixes based on comments

d688438

github-actions Bot removed the test:uipath-runtime label Jul 6, 2026

jepadil23 added 3 commits July 5, 2026 23:51

fix(traceview): fix not reference

67b6bc3

fix(traceview): fix versions and modules order

aa4ed3a

fix(traceview): uipath-platform updated version

5da6ad3

danflorescu96 approved these changes Jul 6, 2026

View reviewed changes

saksharthakkar reviewed Jul 6, 2026

View reviewed changes

saksharthakkar approved these changes Jul 6, 2026

View reviewed changes

Uh oh!

Conversation

jepadil23 commented Jun 10, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saksharthakkar commented Jun 17, 2026

Uh oh!

saksharthakkar commented Jun 17, 2026

Uh oh!

sonarqubecloud Bot commented Jul 6, 2026

Quality Gate passed

Uh oh!

github-actions Bot commented Jul 6, 2026

🚨 Heads up: uipath-integrations cross-tests are FAILING 🚨

Uh oh!

github-actions Bot commented Jul 6, 2026

🚨 Heads up: uipath-langchain cross-tests are FAILING 🚨

Uh oh!

saksharthakkar Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

saksharthakkar Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

🚨 Heads up: `uipath-integrations` cross-tests are FAILING 🚨

🚨 Heads up: `uipath-langchain` cross-tests are FAILING 🚨