From 4fd9b88f21c534654aad05385bdd6ef8ab3fef0a Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Tue, 10 Nov 2026 14:53:14 +0200 Subject: [PATCH 1/5] feat(llamaindex): let the LLM Gateway record model spans UiPath LlamaIndex models (OpenAI, Bedrock, Vertex) now send the LLM Gateway trace-context headers on every request, so the Gateway records the model call ("Model run", with its governance and guardrail spans) inside the agent's trace. OpenInference's client-side LLM span would duplicate it, so the runtime no longer creates one. UIPATH_USE_CLIENT_LLM_SPANS=true keeps the client-side LLM span instead and stops sending the traceparent (the baggage is still sent), for agents whose models don't go through the Gateway. Same variable as uipath-langchain. Requires uipath-platform>=0.3.2, where the trace-context headers are no longer behind the EnableTraceContextHeaders flag, and so uipath>=2.15.2. Co-Authored-By: Claude Opus 5.5 --- packages/uipath-llamaindex/pyproject.toml | 6 +- .../src/uipath_llamaindex/_trace_context.py | 44 +++ .../src/uipath_llamaindex/llms/_openai.py | 3 + .../src/uipath_llamaindex/llms/bedrock.py | 2 + .../src/uipath_llamaindex/llms/vertex.py | 2 + .../uipath_llamaindex/runtime/_llm_spans.py | 165 ++++++++++ .../src/uipath_llamaindex/runtime/factory.py | 14 +- .../template-agent/expected_traces.json | 6 - .../tests/runtime/test_trace_context.py | 281 ++++++++++++++++++ packages/uipath-llamaindex/uv.lock | 24 +- 10 files changed, 520 insertions(+), 27 deletions(-) create mode 100644 packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py create mode 100644 packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py create mode 100644 packages/uipath-llamaindex/tests/runtime/test_trace_context.py diff --git a/packages/uipath-llamaindex/pyproject.toml b/packages/uipath-llamaindex/pyproject.toml index e2ae5189..063cf0af 100644 --- a/packages/uipath-llamaindex/pyproject.toml +++ b/packages/uipath-llamaindex/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath-llamaindex" -version = "0.6.2" +version = "0.6.3" description = "Python SDK that enables developers to build and deploy LlamaIndex agents to the UiPath Cloud Platform" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" @@ -11,8 +11,8 @@ dependencies = [ "llama-index-embeddings-azure-openai>=0.4.1", "llama-index-llms-azure-openai>=0.4.2", "openinference-instrumentation-llama-index>=4.3.9", - "uipath>=2.14.41, <2.15.0", - "uipath-platform>=0.2.19, <0.3.0", + "uipath>=2.15.2, <2.16.0", + "uipath-platform>=0.3.2, <0.4.0", "uipath-runtime>=0.13.5, <0.14.0", ] classifiers = [ diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py b/packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py new file mode 100644 index 00000000..c51f55d4 --- /dev/null +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py @@ -0,0 +1,44 @@ +"""LLM Gateway trace context for UiPath LlamaIndex models. + +By default every UiPath model sends the caller's trace and span to the LLM +Gateway, which records the model call itself ("Model run", with its governance +and guardrail spans) inside the agent's trace. The client-side LLM span would +duplicate it, so the runtime doesn't create one. + +``UIPATH_USE_CLIENT_LLM_SPANS=true`` turns that around, for agents whose models +don't go through the Gateway: the client-side LLM span is kept and the +traceparent isn't sent, so the Gateway's spans stay out of the trace. The +baggage (folder / agent / job attribution) is still sent. +""" + +import logging +import os + +from uipath.platform.chat.llm_trace_context import build_trace_context_headers + +logger = logging.getLogger(__name__) + +USE_CLIENT_LLM_SPANS_ENV = "UIPATH_USE_CLIENT_LLM_SPANS" +TRACEPARENT_HEADER = "x-uipath-traceparent-id" +_TRACE_SOURCE = "source=llamaindex" + + +def use_client_llm_spans() -> bool: + """Whether the client-side LLM span is kept instead of the Gateway's.""" + return os.environ.get(USE_CLIENT_LLM_SPANS_ENV, "").strip().lower() in ( + "1", + "true", + "yes", + ) + + +def trace_context_headers() -> dict[str, str]: + """Headers for one LLM Gateway request, built from the active span.""" + try: + headers = build_trace_context_headers(extra_baggage=[_TRACE_SOURCE]) + except Exception: + logger.debug("could not build trace context headers", exc_info=True) + return {} + if use_client_llm_spans(): + headers.pop(TRACEPARENT_HEADER, None) + return headers diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py index e47f74a0..3c3641f9 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py @@ -10,11 +10,13 @@ from uipath.platform.constants import HEADER_AGENTHUB_CONFIG from uipath.utils import EndpointManager +from .._trace_context import trace_context_headers from .supported_models import OpenAIModel class _UiPathSyncURLRewriteTransport(httpx.HTTPTransport): def handle_request(self, request: httpx.Request) -> httpx.Response: + request.headers.update(trace_context_headers()) original_url = str(request.url) if "/openai/deployments/" in original_url: @@ -31,6 +33,7 @@ def handle_request(self, request: httpx.Request) -> httpx.Response: class _UiPathAsyncURLRewriteTransport(httpx.AsyncHTTPTransport): async def handle_async_request(self, request: httpx.Request) -> httpx.Response: + request.headers.update(trace_context_headers()) original_url = str(request.url) if "/openai/deployments/" in original_url: diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py index 328489de..b4faa278 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py @@ -6,6 +6,7 @@ from uipath.platform.constants import HEADER_AGENTHUB_CONFIG from uipath.utils import EndpointManager +from .._trace_context import trace_context_headers from .supported_models import BedrockModel logger = logging.getLogger(__name__) @@ -143,6 +144,7 @@ def _modify_request(self, request, **kwargs): if process_key: headers["X-UiPath-ProcessKey"] = process_key + headers.update(trace_context_headers()) request.headers.update(headers) diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py index 109d78bb..a0502db4 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py @@ -10,6 +10,7 @@ from uipath.platform.constants import HEADER_AGENTHUB_CONFIG from uipath.utils import EndpointManager +from .._trace_context import trace_context_headers from .supported_models import GeminiModel logger = logging.getLogger(__name__) @@ -72,6 +73,7 @@ def _rewrite_request_for_gateway( # Design-time runs meter as CodedAgents.Playground; deployed -> AgentHub.LLM. if agenthub_config := resolve_coded_agenthub_config(): headers[HEADER_AGENTHUB_CONFIG] = agenthub_config + headers.update(trace_context_headers()) # Update host header to match the gateway URL gateway_url_parsed = httpx.URL(gateway_url) headers["host"] = gateway_url_parsed.host diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py new file mode 100644 index 00000000..1d087dc5 --- /dev/null +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py @@ -0,0 +1,165 @@ +"""Leave the LLM span to the LLM Gateway. + +UiPath models send the trace-context headers, and the LLM Gateway records the +model call ("Model run") under the span they name. OpenInference's client-side +LLM span would duplicate it, so it isn't created, unless +``UIPATH_USE_CLIENT_LLM_SPANS`` is true (checked on every call). + +LlamaIndex nests spans by its own span ids, not by OTel context: each call gets +an id, and OpenInference looks its parent up by id. So an LLM call without a +span still needs three things, which the handlers below provide: + +* whatever it calls nests under its nearest ancestor that has a span; +* its exit and events are ignored, rather than logged as a missing span; +* the traceparent names that ancestor (``current_span``), so the Gateway's + span lands under the workflow step or agent that made the call. +""" + +import weakref +from collections.abc import AsyncGenerator, Generator +from typing import Any, Optional + +from llama_index.core.base.llms.base import BaseLLM +from llama_index.core.instrumentation.span import active_span_id +from openinference.instrumentation.llama_index import ( + LlamaIndexInstrumentor, + get_current_span, +) +from openinference.instrumentation.llama_index._handler import ( + EventHandler, + _SpanHandler, +) +from opentelemetry.trace import Span + +from uipath_llamaindex._trace_context import use_client_llm_spans + + +class _SkippedLlmCalls: + """LLM calls in progress that have no span, and where they nest instead.""" + + def __init__(self) -> None: + self._nearest_created: dict[str, Optional[str]] = {} + + def __contains__(self, span_id: object) -> bool: + return span_id in self._nearest_created + + def __len__(self) -> int: + return len(self._nearest_created) + + def skip(self, span_id: str, parent_id: Optional[str]) -> None: + self._nearest_created[span_id] = parent_id + + def nearest_created(self, span_id: Optional[str]) -> Optional[str]: + """The span itself if it was created, otherwise its nearest ancestor.""" + if span_id in self._nearest_created: + return self._nearest_created[span_id] + return span_id + + def forget(self, span_id: str) -> None: + self._nearest_created.pop(span_id, None) + + def forget_when_done(self, span_id: str, result: Any) -> None: + """Forget a call once nothing can refer to it. + + A streamed response outlives the call that returned it, and iterating + it still emits events with the call's span id, so the call is + forgotten when the stream is garbage collected. + """ + if isinstance(result, (Generator, AsyncGenerator)): + weakref.finalize(result, self.forget, span_id) + else: + self.forget(span_id) + + def clear(self) -> None: + self._nearest_created.clear() + + +_skipped = _SkippedLlmCalls() + + +class _SkipLlmSpanHandler(_SpanHandler): + """OpenInference's span handler, without the spans of LLM calls.""" + + def new_span( + self, + id_: str, + bound_args: Any, + instance: Optional[Any] = None, + parent_span_id: Optional[str] = None, + tags: Optional[dict[str, Any]] = None, + **kwargs: Any, + ) -> Any: + parent_span_id = _skipped.nearest_created(parent_span_id) + if isinstance(instance, BaseLLM) and not use_client_llm_spans(): + _skipped.skip(id_, parent_span_id) + return None + return super().new_span( + id_, bound_args, instance, parent_span_id, tags, **kwargs + ) + + def prepare_to_exit_span( + self, + id_: str, + bound_args: Any, + instance: Optional[Any] = None, + result: Optional[Any] = None, + **kwargs: Any, + ) -> Any: + if id_ in _skipped: + _skipped.forget_when_done(id_, result) + return None + return super().prepare_to_exit_span(id_, bound_args, instance, result, **kwargs) + + def prepare_to_drop_span( + self, + id_: str, + bound_args: Any, + instance: Optional[Any] = None, + err: Optional[BaseException] = None, + **kwargs: Any, + ) -> Any: + if id_ in _skipped: + _skipped.forget(id_) + return None + return super().prepare_to_drop_span(id_, bound_args, instance, err, **kwargs) + + +class _SkipLlmEventHandler(EventHandler): + """OpenInference's event handler, ignoring events of LLM calls with no span.""" + + def handle(self, event: Any, **kwargs: Any) -> Any: + if event.span_id in _skipped: + return event + return super().handle(event, **kwargs) + + +def skip_client_llm_spans(instrumentor: LlamaIndexInstrumentor) -> None: + """Make an instrumented ``LlamaIndexInstrumentor`` skip LLM spans. Idempotent. + + OpenInference builds its handlers inside ``instrument()``, so we can't hand + it ours; instead the instances it built, already registered with + llama-index's dispatcher, become the subclasses above. + """ + span_handler = getattr(instrumentor, "_span_handler", None) + event_handler = getattr(instrumentor, "_event_handler", None) + if isinstance(span_handler, _SpanHandler): + object.__setattr__(span_handler, "__class__", _SkipLlmSpanHandler) + if isinstance(event_handler, EventHandler): + object.__setattr__(event_handler, "__class__", _SkipLlmEventHandler) + + +def current_span() -> Optional[Span]: + """The innermost span that was created: what the traceparent names. + + Inside an LLM call with no span, that's the workflow step or agent span + that made the call. + """ + span_id = active_span_id.get() + if span_id not in _skipped: + return get_current_span() + span_handler = getattr(LlamaIndexInstrumentor(), "_span_handler", None) + ancestor = _skipped.nearest_created(span_id) + if span_handler is None or ancestor is None: + return None + open_span = span_handler.open_spans.get(ancestor) + return open_span._otel_span if open_span is not None else None diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py index 6ac6282f..0ffc94cc 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py @@ -3,10 +3,7 @@ import asyncio import os -from openinference.instrumentation.llama_index import ( - LlamaIndexInstrumentor, - get_current_span, -) +from openinference.instrumentation.llama_index import LlamaIndexInstrumentor from uipath.core.tracing import UiPathSpanUtils, UiPathTraceManager from uipath.platform.resume_triggers import UiPathResumeTriggerHandler from uipath.runtime import ( @@ -19,6 +16,7 @@ from uipath.runtime.errors import UiPathErrorCategory from workflows import Workflow +from uipath_llamaindex.runtime._llm_spans import current_span, skip_client_llm_spans from uipath_llamaindex.runtime._telemetry import ( ToolCallAttributeNormalizer, ) @@ -59,8 +57,12 @@ def __init__( def _setup_instrumentation(self, trace_manager: UiPathTraceManager | None) -> None: """Setup tracing and instrumentation.""" - LlamaIndexInstrumentor().instrument() - UiPathSpanUtils.register_current_span_provider(get_current_span) + instrumentor = LlamaIndexInstrumentor() + instrumentor.instrument() + # The LLM Gateway records "Model run", so the client-side LLM span + # isn't created (unless UIPATH_USE_CLIENT_LLM_SPANS is true). + skip_client_llm_spans(instrumentor) + UiPathSpanUtils.register_current_span_provider(current_span) if trace_manager: trace_manager.tracer_provider.add_span_processor( diff --git a/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json b/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json index dbb796b8..a79cf85d 100644 --- a/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json +++ b/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json @@ -36,12 +36,6 @@ "attributes": { "openinference.span.kind": "TOOL" } - }, - { - "name": ["UiPathChatBedrockConverse.achat", "UiPathOpenAI.achat", "UiPathVertex.achat"], - "attributes": { - "openinference.span.kind": "LLM" - } } ] } diff --git a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py new file mode 100644 index 00000000..26ea5153 --- /dev/null +++ b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py @@ -0,0 +1,281 @@ +"""LLM Gateway trace context and client-side LLM spans. + +* every UiPath model sends the trace-context headers on each Gateway request; +* OpenInference no longer opens the client-side LLM span the Gateway's + "Model run" replaces, and the traceparent names the span that made the call; +* with ``UIPATH_USE_CLIENT_LLM_SPANS`` true, it's the other way around: the + client-side LLM span is kept and the traceparent isn't sent (the baggage is). +""" + +import gc +import logging +from collections.abc import Iterator +from types import SimpleNamespace +from typing import Any +from unittest.mock import patch + +import httpx +import pytest +from llama_index.core.llms import CompletionResponse, MockLLM +from openinference.instrumentation.llama_index import LlamaIndexInstrumentor +from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor, TracerProvider +from uipath.core.tracing import UiPathSpanUtils +from uipath.runtime import UiPathRuntimeContext +from workflows import Context, Workflow, step +from workflows.events import StartEvent, StopEvent + +from uipath_llamaindex._trace_context import ( + TRACEPARENT_HEADER, + USE_CLIENT_LLM_SPANS_ENV, + trace_context_headers, +) +from uipath_llamaindex.llms._openai import _UiPathSyncURLRewriteTransport +from uipath_llamaindex.llms.bedrock import AwsBedrockCompletionsPassthroughClient +from uipath_llamaindex.llms.vertex import _rewrite_request_for_gateway +from uipath_llamaindex.runtime import _llm_spans +from uipath_llamaindex.runtime._llm_spans import ( + _SkipLlmEventHandler, + _SkipLlmSpanHandler, + current_span, + skip_client_llm_spans, +) +from uipath_llamaindex.runtime.factory import UiPathLlamaIndexRuntimeFactory + +_TRACE_ID = "aabbccddeeff00112233445566778899" +_HEADERS = { + TRACEPARENT_HEADER: f"00-{_TRACE_ID}-1122334455667788-01", + "x-uipath-tracebaggage": "source=llamaindex", +} + +# What the model saw while generating: the headers a request would carry. +_seen: list[dict[str, str]] = [] + + +class _RecordingLLM(MockLLM): + def complete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> Any: + _seen.append(trace_context_headers()) + return CompletionResponse(text="ok") + + +class _FailingLLM(MockLLM): + def complete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> Any: + raise RuntimeError("gateway said no") + + +class _AskWorkflow(Workflow): + def __init__(self, llm: MockLLM, **kwargs: Any) -> None: + super().__init__(**kwargs) + self._llm = llm + + @step + async def ask(self, ctx: Context, ev: StartEvent) -> StopEvent: + reply = await self._llm.acomplete("hi") + return StopEvent(result=reply.text) + + +class _Recorder(SpanProcessor): + """Captures spans at start (what live tracking sees) and at end.""" + + def __init__(self) -> None: + self.started: list[Span] = [] + self.ended: list[ReadableSpan] = [] + + def on_start(self, span: Span, parent_context: Any = None) -> None: + self.started.append(span) + + def on_end(self, span: ReadableSpan) -> None: + self.ended.append(span) + + def kinds(self) -> list[Any]: + return [ + (s.attributes or {}).get("openinference.span.kind") for s in self.started + ] + + +@pytest.fixture(autouse=True) +def _reset(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]: + monkeypatch.delenv(USE_CLIENT_LLM_SPANS_ENV, raising=False) + monkeypatch.setenv("UIPATH_TRACE_ID", _TRACE_ID) + _seen.clear() + _llm_spans._skipped.clear() + yield + _llm_spans._skipped.clear() + + +@pytest.fixture +def recorder() -> Iterator[_Recorder]: + """Instrument against a local provider, as the factory does.""" + instrumentor = LlamaIndexInstrumentor() + instrumentor.uninstrument() + provider = TracerProvider() + rec = _Recorder() + provider.add_span_processor(rec) + instrumentor.instrument(tracer_provider=provider) + skip_client_llm_spans(instrumentor) + UiPathSpanUtils.register_current_span_provider(current_span) + yield rec + instrumentor.uninstrument() + + +async def _run(llm: MockLLM) -> Any: + return await _AskWorkflow(llm=llm, timeout=10).run() + + +class TestSkipClientLlmSpans: + async def test_never_starts_client_llm_span(self, recorder: _Recorder) -> None: + assert await _run(_RecordingLLM(max_tokens=None)) == "ok" + + # Not just dropped at export: never started, so live tracking can't + # leave it behind as "running". + assert "LLM" not in recorder.kinds() + assert "_AskWorkflow.ask" in [s.name for s in recorder.started] + + async def test_traceparent_names_the_step_that_made_the_call( + self, recorder: _Recorder + ) -> None: + await _run(_RecordingLLM(max_tokens=None)) + + step_span = next(s for s in recorder.ended if s.name == "_AskWorkflow.ask") + span_id = format(step_span.context.span_id, "016x") + assert _seen[0][TRACEPARENT_HEADER] == f"00-{_TRACE_ID}-{span_id}-01" + assert "source=llamaindex" in _seen[0]["x-uipath-tracebaggage"] + + async def test_skipped_spans_log_no_missing_span_warnings( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + await _run(_RecordingLLM(max_tokens=None)) + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + + async def test_model_error_still_propagates(self, recorder: _Recorder) -> None: + with pytest.raises(Exception, match="gateway said no"): + await _run(_FailingLLM(max_tokens=None)) + + step_span = next(s for s in recorder.ended if s.name == "_AskWorkflow.ask") + assert not step_span.status.is_ok + assert "LLM" not in recorder.kinds() + + async def test_skipped_spans_are_forgotten_when_the_call_ends( + self, recorder: _Recorder + ) -> None: + await _run(_RecordingLLM(max_tokens=None)) + assert not _llm_spans._skipped + + with pytest.raises(Exception, match="gateway said no"): + await _run(_FailingLLM(max_tokens=None)) + assert not _llm_spans._skipped + + async def test_streamed_call_is_forgotten_once_the_stream_is_gone( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = await MockLLM(max_tokens=None).astream_complete("a b c") + # The call has returned, but iterating still emits its events. + assert _llm_spans._skipped + chunks = [chunk.delta async for chunk in stream] + + assert "".join(c or "" for c in chunks) == "a b c" + assert "LLM" not in recorder.kinds() + assert not [r for r in caplog.records if "Open span is missing" in r.message] + + del stream + gc.collect() + assert not _llm_spans._skipped + + @pytest.mark.parametrize("value", ["true", "TRUE", "1", "yes"]) + async def test_client_llm_spans_env_keeps_span_and_drops_traceparent( + self, recorder: _Recorder, monkeypatch: pytest.MonkeyPatch, value: str + ) -> None: + monkeypatch.setenv(USE_CLIENT_LLM_SPANS_ENV, value) + await _run(_RecordingLLM(max_tokens=None)) + + assert "LLM" in recorder.kinds() + assert TRACEPARENT_HEADER not in _seen[0] + assert "source=llamaindex" in _seen[0]["x-uipath-tracebaggage"] + + @pytest.mark.parametrize("value", ["false", "0", ""]) + async def test_client_llm_spans_env_not_true_skips_span( + self, recorder: _Recorder, monkeypatch: pytest.MonkeyPatch, value: str + ) -> None: + monkeypatch.setenv(USE_CLIENT_LLM_SPANS_ENV, value) + await _run(_RecordingLLM(max_tokens=None)) + + assert "LLM" not in recorder.kinds() + assert TRACEPARENT_HEADER in _seen[0] + + async def test_skipping_twice_is_harmless(self, recorder: _Recorder) -> None: + skip_client_llm_spans(LlamaIndexInstrumentor()) + await _run(_RecordingLLM(max_tokens=None)) + + assert type(LlamaIndexInstrumentor()._span_handler) is _SkipLlmSpanHandler + assert "LLM" not in recorder.kinds() + + def test_factory_installs_the_skip(self, tmp_path: Any) -> None: + # Guards the private OpenInference handlers we subclass: if an upgrade + # renames them, this fails instead of client LLM spans silently coming back. + instrumentor = LlamaIndexInstrumentor() + instrumentor.uninstrument() + try: + UiPathLlamaIndexRuntimeFactory( + UiPathRuntimeContext( + runtime_dir=str(tmp_path), state_file=str(tmp_path / "state.db") + ) + ) + assert isinstance(instrumentor._span_handler, _SkipLlmSpanHandler) + assert isinstance(instrumentor._event_handler, _SkipLlmEventHandler) + finally: + instrumentor.uninstrument() + + +class TestModelsSendTraceHeaders: + def test_openai_transport(self) -> None: + request = httpx.Request( + "POST", "https://gw/openai/deployments/gpt/chat/completions" + ) + with ( + patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + return_value=dict(_HEADERS), + ), + patch.object( + httpx.HTTPTransport, "handle_request", return_value=httpx.Response(200) + ) as sent, + ): + _UiPathSyncURLRewriteTransport().handle_request(request) + + headers = sent.call_args.args[0].headers + assert headers[TRACEPARENT_HEADER] == _HEADERS[TRACEPARENT_HEADER] + assert headers["x-uipath-tracebaggage"] == "source=llamaindex" + + def test_bedrock_request_hook(self, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("UIPATH_URL", "https://cloud.uipath.com") + request = SimpleNamespace(url="https://aws/model/m/converse", headers={}) + with patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + return_value=dict(_HEADERS), + ): + AwsBedrockCompletionsPassthroughClient( + "m", "tok", "converse" + )._modify_request(request) + + assert _HEADERS.items() <= request.headers.items() + + def test_vertex_request_rewrite(self) -> None: + request = httpx.Request( + "POST", "https://vertex/models/gemini:generateContent", content=b"{}" + ) + with patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + return_value=dict(_HEADERS), + ): + rewritten = _rewrite_request_for_gateway(request, "https://gw/vertex") + + assert rewritten.headers[TRACEPARENT_HEADER] == _HEADERS[TRACEPARENT_HEADER] + + def test_header_errors_never_break_the_request(self) -> None: + with patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + side_effect=RuntimeError("boom"), + ): + assert trace_context_headers() == {} diff --git a/packages/uipath-llamaindex/uv.lock b/packages/uipath-llamaindex/uv.lock index 8778c9fd..0b511e02 100644 --- a/packages/uipath-llamaindex/uv.lock +++ b/packages/uipath-llamaindex/uv.lock @@ -3497,7 +3497,7 @@ wheels = [ [[package]] name = "uipath" -version = "2.14.41" +version = "2.15.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "applicationinsights" }, @@ -3522,23 +3522,23 @@ dependencies = [ { name = "uipath-platform" }, { name = "uipath-runtime" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/99/b3/a1eb57b26c1c36b4142470dc35c7daba55e5311eb243b1dc98915ea217d1/uipath-2.14.41.tar.gz", hash = "sha256:4a03cfd36517388b70b34f74a9fd4f1276aef07458abc902d1f063d312ddf26a", size = 4598519, upload-time = "2026-10-19T15:32:19.85Z" } +sdist = { url = "https://files.pythonhosted.org/packages/b4/5f/fc3fcf760e3fad651f1f7c7e887c2fc36d6c99abb78d1aed2019f9d58e3f/uipath-2.15.2.tar.gz", hash = "sha256:303dbb9ff14954bdcad03ef0dfbab46fd98865c37890d3b289f65fccd779105d", size = 4611713, upload-time = "2026-11-10T08:17:58.635Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/6e/47/ff05433a790bfc8138b52af0c356187e592d700ebb7134d3bc9dbb161417/uipath-2.14.41-py3-none-any.whl", hash = "sha256:d15592f1551b7cd3f912f59d4a785809e8965165280f961774a8045f1e87b7b9", size = 455996, upload-time = "2026-10-19T15:32:17.234Z" }, + { url = "https://files.pythonhosted.org/packages/99/f1/41a7c45309d63fad851d9524755acffd4622d5c8166ae31189a90d7665b2/uipath-2.15.2-py3-none-any.whl", hash = "sha256:543894e5abe30e9f54889015592ad0d97c6cbfa6912c87fb02b88569f63ef492", size = 460190, upload-time = "2026-11-10T08:17:56.856Z" }, ] [[package]] name = "uipath-core" -version = "0.5.33" +version = "0.5.34" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "opentelemetry-instrumentation" }, { name = "opentelemetry-sdk" }, { name = "pydantic" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/c6/32/8a254ae086cfa0ca9808d36b9084cffeea151b4250e77e84eed8c9dcde17/uipath_core-0.5.33.tar.gz", hash = "sha256:f533a3145131ce93bde78a264f98a796134dcd7a6ebf3211d8247a49d3b3eebc", size = 131308, upload-time = "2026-10-06T19:39:30.247Z" } +sdist = { url = "https://files.pythonhosted.org/packages/fc/7e/4e41e9278249a82cd8e14fbe5e407de480be338cde79fe4d09b647fdcaca/uipath_core-0.5.34.tar.gz", hash = "sha256:6511d72989e87f24d3ed3ac3649379c78bce0f82663300357354819d729a4ad8", size = 131912, upload-time = "2026-11-02T11:12:43.798Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/7a/15/3aa01f0011515c0508e966eabf6b0949d61d8c2c326cf83f943616733ec3/uipath_core-0.5.33-py3-none-any.whl", hash = "sha256:13c541c9b684e3f7556c830442b9fa48a3a42a36a38a3086195b10eeb4360ffb", size = 55133, upload-time = "2026-10-06T19:39:28.9Z" }, + { url = "https://files.pythonhosted.org/packages/b7/38/8f1b0db5987ad3607ba81bdd576fe71e5d941b2d9cf31ead262813c5efaf/uipath_core-0.5.34-py3-none-any.whl", hash = "sha256:f3e1168e4ae440cf425703f50986e5d29f635c5c6d4025b3b1f0eebad0e3622c", size = 55393, upload-time = "2026-11-02T11:12:42.089Z" }, ] [[package]] @@ -3552,7 +3552,7 @@ wheels = [ [[package]] name = "uipath-llamaindex" -version = "0.6.2" +version = "0.6.3" source = { editable = "." } dependencies = [ { name = "aiosqlite" }, @@ -3612,8 +3612,8 @@ requires-dist = [ { name = "llama-index-llms-google-genai", marker = "extra == 'vertex'", specifier = ">=0.8.0" }, { name = "llama-index-workflows", specifier = ">=2.18.0,<3.0.0" }, { name = "openinference-instrumentation-llama-index", specifier = ">=4.3.9" }, - { name = "uipath", specifier = ">=2.14.41,<2.15.0" }, - { name = "uipath-platform", specifier = ">=0.2.19,<0.3.0" }, + { name = "uipath", specifier = ">=2.15.2,<2.16.0" }, + { name = "uipath-platform", specifier = ">=0.3.2,<0.4.0" }, { name = "uipath-runtime", specifier = ">=0.13.5,<0.14.0" }, ] provides-extras = ["bedrock", "vertex"] @@ -3640,7 +3640,7 @@ dev = [ [[package]] name = "uipath-platform" -version = "0.2.40" +version = "0.3.4" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, @@ -3651,9 +3651,9 @@ dependencies = [ { name = "truststore" }, { name = "uipath-core" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/9f/a1/2a5c0f5be03e387802ab5347824e4a4830883734f07689b95da6f3f62ca9/uipath_platform-0.2.40.tar.gz", hash = "sha256:d694efd59a1be61d3b805ecec3e6604eb9d8272d952ed58a0812ebd814f8345d", size = 457625, upload-time = "2026-10-16T13:25:56.301Z" } +sdist = { url = "https://files.pythonhosted.org/packages/25/72/3723aae6ed58405fc7fdfd367b330999629999061246e5786c72003f064c/uipath_platform-0.3.4.tar.gz", hash = "sha256:3046938768aaa88824d075b7a9f71915d83c3f01007dfd7ba0087b501af0c88d", size = 491424, upload-time = "2026-11-10T10:40:08.442Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/f6/e3/f66486aefa82b9c2db971213462bf051026705e928f27b7e7f063473ec16/uipath_platform-0.2.40-py3-none-any.whl", hash = "sha256:a652a210969ca844de65c9c672a0eb6f561bdc7575d1d6c05048fc0b5e673894", size = 295681, upload-time = "2026-10-16T13:25:54.739Z" }, + { url = "https://files.pythonhosted.org/packages/b0/80/ef155b60b6a26e521dd568a646d604c33f79eb4cf83417a9b28c75182f65/uipath_platform-0.3.4-py3-none-any.whl", hash = "sha256:9b9471c30059da958f2effd3adc41e80b306c735fc8589b3b37407dbe62789fb", size = 313116, upload-time = "2026-11-10T10:40:06.759Z" }, ] [[package]] From 9c3bbc15403a53d96e51f166fcdac8427c380859 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Tue, 10 Nov 2026 15:08:17 +0200 Subject: [PATCH 2/5] fix(llamaindex): lock uipath 2.15.1 and uipath-platform 0.3.2 CI's package proxy rejects releases younger than its minimum age, and uipath 2.15.2 and uipath-platform 0.3.4 were published today. 0.3.2 is the first platform release without the EnableTraceContextHeaders flag, and uipath 2.15.1 accepts it, so the floor moves to uipath>=2.15.1. Co-Authored-By: Claude Opus 5.5 --- packages/uipath-llamaindex/pyproject.toml | 2 +- packages/uipath-llamaindex/uv.lock | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/uipath-llamaindex/pyproject.toml b/packages/uipath-llamaindex/pyproject.toml index 063cf0af..c326adb5 100644 --- a/packages/uipath-llamaindex/pyproject.toml +++ b/packages/uipath-llamaindex/pyproject.toml @@ -11,7 +11,7 @@ dependencies = [ "llama-index-embeddings-azure-openai>=0.4.1", "llama-index-llms-azure-openai>=0.4.2", "openinference-instrumentation-llama-index>=4.3.9", - "uipath>=2.15.2, <2.16.0", + "uipath>=2.15.1, <2.16.0", "uipath-platform>=0.3.2, <0.4.0", "uipath-runtime>=0.13.5, <0.14.0", ] diff --git a/packages/uipath-llamaindex/uv.lock b/packages/uipath-llamaindex/uv.lock index 0b511e02..067f1ca8 100644 --- a/packages/uipath-llamaindex/uv.lock +++ b/packages/uipath-llamaindex/uv.lock @@ -3497,7 +3497,7 @@ wheels = [ [[package]] name = "uipath" -version = "2.15.2" +version = "2.15.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "applicationinsights" }, @@ -3522,9 +3522,9 @@ dependencies = [ { name = "uipath-platform" }, { name = "uipath-runtime" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/b4/5f/fc3fcf760e3fad651f1f7c7e887c2fc36d6c99abb78d1aed2019f9d58e3f/uipath-2.15.2.tar.gz", hash = "sha256:303dbb9ff14954bdcad03ef0dfbab46fd98865c37890d3b289f65fccd779105d", size = 4611713, upload-time = "2026-11-10T08:17:58.635Z" } +sdist = { url = "https://files.pythonhosted.org/packages/09/dd/4eba149cd1f3169193b33b0b5f61724996ee16b582eb8132f3eeda516516/uipath-2.15.1.tar.gz", hash = "sha256:88d5fe1ee06d949eaf441e2ea26ce4b801deb79df6f7d0756225a9fe7fc5bbb2", size = 4609499, upload-time = "2026-11-06T14:37:13.671Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/99/f1/41a7c45309d63fad851d9524755acffd4622d5c8166ae31189a90d7665b2/uipath-2.15.2-py3-none-any.whl", hash = "sha256:543894e5abe30e9f54889015592ad0d97c6cbfa6912c87fb02b88569f63ef492", size = 460190, upload-time = "2026-11-10T08:17:56.856Z" }, + { url = "https://files.pythonhosted.org/packages/ae/e7/b5c8f42e63c0aa64902074fe35a4aaa280f0742c1ed61bcbf57ff5d7f73d/uipath-2.15.1-py3-none-any.whl", hash = "sha256:86204534049005bbd2b33df4eced75798779ef2a0a5d2629780c2e07ed373da5", size = 459942, upload-time = "2026-11-06T14:37:11.033Z" }, ] [[package]] @@ -3612,7 +3612,7 @@ requires-dist = [ { name = "llama-index-llms-google-genai", marker = "extra == 'vertex'", specifier = ">=0.8.0" }, { name = "llama-index-workflows", specifier = ">=2.18.0,<3.0.0" }, { name = "openinference-instrumentation-llama-index", specifier = ">=4.3.9" }, - { name = "uipath", specifier = ">=2.15.2,<2.16.0" }, + { name = "uipath", specifier = ">=2.15.1,<2.16.0" }, { name = "uipath-platform", specifier = ">=0.3.2,<0.4.0" }, { name = "uipath-runtime", specifier = ">=0.13.5,<0.14.0" }, ] @@ -3640,7 +3640,7 @@ dev = [ [[package]] name = "uipath-platform" -version = "0.3.4" +version = "0.3.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, @@ -3651,9 +3651,9 @@ dependencies = [ { name = "truststore" }, { name = "uipath-core" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/25/72/3723aae6ed58405fc7fdfd367b330999629999061246e5786c72003f064c/uipath_platform-0.3.4.tar.gz", hash = "sha256:3046938768aaa88824d075b7a9f71915d83c3f01007dfd7ba0087b501af0c88d", size = 491424, upload-time = "2026-11-10T10:40:08.442Z" } +sdist = { url = "https://files.pythonhosted.org/packages/9b/bf/93244ad08e046ff0ae6f0286045899f0bcafc5dd5f0cff1bfc4efd76cf4e/uipath_platform-0.3.2.tar.gz", hash = "sha256:d763bbbd53a3d71aca82dd99f07bc8fd096b403dccd4dbcbfc30944e41b0fa64", size = 489635, upload-time = "2026-11-09T12:20:20.105Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b0/80/ef155b60b6a26e521dd568a646d604c33f79eb4cf83417a9b28c75182f65/uipath_platform-0.3.4-py3-none-any.whl", hash = "sha256:9b9471c30059da958f2effd3adc41e80b306c735fc8589b3b37407dbe62789fb", size = 313116, upload-time = "2026-11-10T10:40:06.759Z" }, + { url = "https://files.pythonhosted.org/packages/65/3d/8d84ede6aa14923a25c6b0a7c835469bc30e84a0bb69effefd040ba219fa/uipath_platform-0.3.2-py3-none-any.whl", hash = "sha256:f3a0e70352406e4aff937d2639bc29fdeb1a2535b92d5f0585be2b0edcc45380", size = 312480, upload-time = "2026-11-09T12:20:18.019Z" }, ] [[package]] From ca3459c2dddd8bb75817ce47e3ae0ebeeec18b74 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Tue, 10 Nov 2026 15:24:19 +0200 Subject: [PATCH 3/5] fix(llamaindex): forget a skipped stream on its last event, not on GC A half-read stream that was dropped lost its registration before it was closed: CPython clears weak references before closing a generator, and llama-index's stream wrapper emits an ExceptionEvent (GeneratorExit) while closing, which then reached OpenInference as a missing span. A skipped call is now forgotten when it returns or fails, or, for a chat or completion stream, when its final event (end or exception) arrives, which the wrapper emits exactly once when the stream is exhausted, fails or is closed. Also builds the failing model outside pytest.raises in the tests (Sonar S5778). Co-Authored-By: Claude Opus 5.5 --- .../uipath_llamaindex/runtime/_llm_spans.py | 57 +++++++++++++------ .../tests/runtime/test_trace_context.py | 38 +++++++++++-- 2 files changed, 74 insertions(+), 21 deletions(-) diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py index 1d087dc5..41c05ccc 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py @@ -15,11 +15,16 @@ span lands under the workflow step or agent that made the call. """ -import weakref -from collections.abc import AsyncGenerator, Generator from typing import Any, Optional from llama_index.core.base.llms.base import BaseLLM +from llama_index.core.instrumentation.events.exception import ExceptionEvent +from llama_index.core.instrumentation.events.llm import ( + LLMChatEndEvent, + LLMChatStartEvent, + LLMCompletionEndEvent, + LLMCompletionStartEvent, +) from llama_index.core.instrumentation.span import active_span_id from openinference.instrumentation.llama_index import ( LlamaIndexInstrumentor, @@ -33,12 +38,25 @@ from uipath_llamaindex._trace_context import use_client_llm_spans +# llama-index's chat / completion wrapper emits a start event when the call +# begins and exactly one of these when it's done: at once for a plain call, +# and for a stream when it's exhausted, fails or is closed (GeneratorExit). +_STARTS = (LLMChatStartEvent, LLMCompletionStartEvent) +_ENDS = (LLMChatEndEvent, LLMCompletionEndEvent, ExceptionEvent) + class _SkippedLlmCalls: - """LLM calls in progress that have no span, and where they nest instead.""" + """LLM calls that have no span, and where they nest instead. + + A call is forgotten once nothing can refer to it any more: when it returns + or fails, or, if it returned a stream that still emits events with its span + id, when that stream's last event arrives. + """ def __init__(self) -> None: self._nearest_created: dict[str, Optional[str]] = {} + self._running: set[str] = set() + self._awaiting_end: set[str] = set() def __contains__(self, span_id: object) -> bool: return span_id in self._nearest_created @@ -48,6 +66,7 @@ def __len__(self) -> int: def skip(self, span_id: str, parent_id: Optional[str]) -> None: self._nearest_created[span_id] = parent_id + self._running.add(span_id) def nearest_created(self, span_id: Optional[str]) -> Optional[str]: """The span itself if it was created, otherwise its nearest ancestor.""" @@ -55,23 +74,28 @@ def nearest_created(self, span_id: Optional[str]) -> Optional[str]: return self._nearest_created[span_id] return span_id - def forget(self, span_id: str) -> None: - self._nearest_created.pop(span_id, None) + def returned(self, span_id: str) -> None: + self._running.discard(span_id) + if span_id not in self._awaiting_end: + self.forget(span_id) - def forget_when_done(self, span_id: str, result: Any) -> None: - """Forget a call once nothing can refer to it. + def saw_event(self, span_id: str, event: Any) -> None: + if isinstance(event, _STARTS): + self._awaiting_end.add(span_id) + elif isinstance(event, _ENDS): + self._awaiting_end.discard(span_id) + if span_id not in self._running: + self.forget(span_id) - A streamed response outlives the call that returned it, and iterating - it still emits events with the call's span id, so the call is - forgotten when the stream is garbage collected. - """ - if isinstance(result, (Generator, AsyncGenerator)): - weakref.finalize(result, self.forget, span_id) - else: - self.forget(span_id) + def forget(self, span_id: str) -> None: + self._nearest_created.pop(span_id, None) + self._running.discard(span_id) + self._awaiting_end.discard(span_id) def clear(self) -> None: self._nearest_created.clear() + self._running.clear() + self._awaiting_end.clear() _skipped = _SkippedLlmCalls() @@ -106,7 +130,7 @@ def prepare_to_exit_span( **kwargs: Any, ) -> Any: if id_ in _skipped: - _skipped.forget_when_done(id_, result) + _skipped.returned(id_) return None return super().prepare_to_exit_span(id_, bound_args, instance, result, **kwargs) @@ -129,6 +153,7 @@ class _SkipLlmEventHandler(EventHandler): def handle(self, event: Any, **kwargs: Any) -> Any: if event.span_id in _skipped: + _skipped.saw_event(event.span_id, event) return event return super().handle(event, **kwargs) diff --git a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py index 26ea5153..40b0d702 100644 --- a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py +++ b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py @@ -7,6 +7,7 @@ client-side LLM span is kept and the traceparent isn't sent (the baggage is). """ +import asyncio import gc import logging from collections.abc import Iterator @@ -149,8 +150,9 @@ async def test_skipped_spans_log_no_missing_span_warnings( assert not [r for r in caplog.records if "Open span is missing" in r.message] async def test_model_error_still_propagates(self, recorder: _Recorder) -> None: + llm = _FailingLLM(max_tokens=None) with pytest.raises(Exception, match="gateway said no"): - await _run(_FailingLLM(max_tokens=None)) + await _run(llm) step_span = next(s for s in recorder.ended if s.name == "_AskWorkflow.ask") assert not step_span.status.is_ok @@ -162,11 +164,12 @@ async def test_skipped_spans_are_forgotten_when_the_call_ends( await _run(_RecordingLLM(max_tokens=None)) assert not _llm_spans._skipped + llm = _FailingLLM(max_tokens=None) with pytest.raises(Exception, match="gateway said no"): - await _run(_FailingLLM(max_tokens=None)) + await _run(llm) assert not _llm_spans._skipped - async def test_streamed_call_is_forgotten_once_the_stream_is_gone( + async def test_streamed_call_is_forgotten_once_the_stream_ends( self, recorder: _Recorder, caplog: pytest.LogCaptureFixture ) -> None: with caplog.at_level(logging.WARNING): @@ -178,9 +181,34 @@ async def test_streamed_call_is_forgotten_once_the_stream_is_gone( assert "".join(c or "" for c in chunks) == "a b c" assert "LLM" not in recorder.kinds() assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + async def test_abandoned_async_stream_closes_without_warnings( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = await MockLLM(max_tokens=None).astream_complete("a b c") + await anext(stream) + # Dropped half-way: the event loop closes it later, after it's + # collected, and closing emits an ExceptionEvent for its span id. + del stream + gc.collect() + for _ in range(5): + await asyncio.sleep(0) + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped - del stream - gc.collect() + def test_abandoned_sync_stream_closes_without_warnings( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = MockLLM(max_tokens=None).stream_complete("a b c") + next(stream) + del stream + gc.collect() + + assert not [r for r in caplog.records if "Open span is missing" in r.message] assert not _llm_spans._skipped @pytest.mark.parametrize("value", ["true", "TRUE", "1", "yes"]) From c3fd6a00e6a81761bba0239480c760742543e5c4 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Tue, 10 Nov 2026 16:30:44 +0200 Subject: [PATCH 4/5] fix(llamaindex): keep a skipped LLM call only while it runs A stream that was returned but never read sends no further events, so its registration, kept until the stream's final event, was never removed: one entry leaked per abandoned stream. A skipped call is now forgotten when it exits or is dropped, which llama-index always reports, streams included. The events a stream emits afterwards (in-progress, end, exception) are ignored when OpenInference has no span for their id, so nothing is kept for a stream at all. Tests cover both sides of that filter: late stream events of an unknown span log nothing, and other events of an unknown span are still reported as missing. They read OpenInference's logger directly rather than through caplog, which other tests in the suite leave disabled. Co-Authored-By: Claude Opus 5.5 --- .../uipath_llamaindex/runtime/_llm_spans.py | 84 +++++++------- .../tests/runtime/test_trace_context.py | 105 +++++++++++++++++- 2 files changed, 144 insertions(+), 45 deletions(-) diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py index 41c05ccc..e65b2057 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py @@ -21,9 +21,9 @@ from llama_index.core.instrumentation.events.exception import ExceptionEvent from llama_index.core.instrumentation.events.llm import ( LLMChatEndEvent, - LLMChatStartEvent, + LLMChatInProgressEvent, LLMCompletionEndEvent, - LLMCompletionStartEvent, + LLMCompletionInProgressEvent, ) from llama_index.core.instrumentation.span import active_span_id from openinference.instrumentation.llama_index import ( @@ -38,64 +38,50 @@ from uipath_llamaindex._trace_context import use_client_llm_spans -# llama-index's chat / completion wrapper emits a start event when the call -# begins and exactly one of these when it's done: at once for a plain call, -# and for a stream when it's exhausted, fails or is closed (GeneratorExit). -_STARTS = (LLMChatStartEvent, LLMCompletionStartEvent) -_ENDS = (LLMChatEndEvent, LLMCompletionEndEvent, ExceptionEvent) +# What llama-index's chat / completion wrapper emits for a stream after the +# call has returned: one per chunk, then an end or (failed, closed) exception. +_STREAM_EVENTS = ( + LLMChatInProgressEvent, + LLMCompletionInProgressEvent, + LLMChatEndEvent, + LLMCompletionEndEvent, + ExceptionEvent, +) class _SkippedLlmCalls: - """LLM calls that have no span, and where they nest instead. + """LLM calls with no span that are running, and where they nest instead. - A call is forgotten once nothing can refer to it any more: when it returns - or fails, or, if it returned a stream that still emits events with its span - id, when that stream's last event arrives. + A call is kept only while it runs: llama-index always reports its exit or + drop, so nothing outlives it. A stream it returned emits more events with + its id later; those are recognised by their type (``_STREAM_EVENTS`` for a + span OpenInference doesn't know), so a stream that is never read costs + nothing. """ def __init__(self) -> None: - self._nearest_created: dict[str, Optional[str]] = {} - self._running: set[str] = set() - self._awaiting_end: set[str] = set() + self._parents: dict[str, Optional[str]] = {} def __contains__(self, span_id: object) -> bool: - return span_id in self._nearest_created + return span_id in self._parents def __len__(self) -> int: - return len(self._nearest_created) + return len(self._parents) def skip(self, span_id: str, parent_id: Optional[str]) -> None: - self._nearest_created[span_id] = parent_id - self._running.add(span_id) + self._parents[span_id] = parent_id def nearest_created(self, span_id: Optional[str]) -> Optional[str]: """The span itself if it was created, otherwise its nearest ancestor.""" - if span_id in self._nearest_created: - return self._nearest_created[span_id] + if span_id in self._parents: + return self._parents[span_id] return span_id - def returned(self, span_id: str) -> None: - self._running.discard(span_id) - if span_id not in self._awaiting_end: - self.forget(span_id) - - def saw_event(self, span_id: str, event: Any) -> None: - if isinstance(event, _STARTS): - self._awaiting_end.add(span_id) - elif isinstance(event, _ENDS): - self._awaiting_end.discard(span_id) - if span_id not in self._running: - self.forget(span_id) - def forget(self, span_id: str) -> None: - self._nearest_created.pop(span_id, None) - self._running.discard(span_id) - self._awaiting_end.discard(span_id) + self._parents.pop(span_id, None) def clear(self) -> None: - self._nearest_created.clear() - self._running.clear() - self._awaiting_end.clear() + self._parents.clear() _skipped = _SkippedLlmCalls() @@ -130,7 +116,7 @@ def prepare_to_exit_span( **kwargs: Any, ) -> Any: if id_ in _skipped: - _skipped.returned(id_) + _skipped.forget(id_) return None return super().prepare_to_exit_span(id_, bound_args, instance, result, **kwargs) @@ -147,13 +133,29 @@ def prepare_to_drop_span( return None return super().prepare_to_drop_span(id_, bound_args, instance, err, **kwargs) + def knows(self, span_id: str) -> bool: + """Whether OpenInference has a span for this id, open or still streaming.""" + with self.lock: + if span_id in self.open_spans: + return True + return self._export_queue.find(span_id) is not None + class _SkipLlmEventHandler(EventHandler): """OpenInference's event handler, ignoring events of LLM calls with no span.""" def handle(self, event: Any, **kwargs: Any) -> Any: if event.span_id in _skipped: - _skipped.saw_event(event.span_id, event) + return event + # A stream returned by a call with no span: the call is gone, and its + # later events would otherwise be logged as a missing span. + span_handler = self._span_handler + if ( + event.span_id + and isinstance(event, _STREAM_EVENTS) + and isinstance(span_handler, _SkipLlmSpanHandler) + and not span_handler.knows(event.span_id) + ): return event return super().handle(event, **kwargs) diff --git a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py index 40b0d702..57b9a262 100644 --- a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py +++ b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py @@ -17,8 +17,18 @@ import httpx import pytest -from llama_index.core.llms import CompletionResponse, MockLLM +from llama_index.core.instrumentation.events import BaseEvent +from llama_index.core.instrumentation.events.exception import ExceptionEvent +from llama_index.core.instrumentation.events.llm import ( + LLMChatEndEvent, + LLMChatInProgressEvent, + LLMChatStartEvent, + LLMCompletionEndEvent, + LLMCompletionInProgressEvent, +) +from llama_index.core.llms import ChatMessage, ChatResponse, CompletionResponse, MockLLM from openinference.instrumentation.llama_index import LlamaIndexInstrumentor +from openinference.instrumentation.llama_index import _handler as _oi_handler from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor, TracerProvider from uipath.core.tracing import UiPathSpanUtils from uipath.runtime import UiPathRuntimeContext @@ -118,6 +128,23 @@ def recorder() -> Iterator[_Recorder]: instrumentor.uninstrument() +@pytest.fixture +def missing_span_warnings() -> Iterator[list[str]]: + """OpenInference's "Open span is missing" warnings, read off its logger. + + Not via caplog: other tests in the suite leave logging disabled or not + propagating, which would make an assertion on caplog pass vacuously. + """ + seen: list[str] = [] + + def record(msg: object, *args: Any, **kwargs: Any) -> None: + if "Open span is missing" in str(msg): + seen.append(str(msg)) + + with patch.object(_oi_handler.logger, "warning", side_effect=record): + yield seen + + async def _run(llm: MockLLM) -> Any: return await _AskWorkflow(llm=llm, timeout=10).run() @@ -169,13 +196,14 @@ async def test_skipped_spans_are_forgotten_when_the_call_ends( await _run(llm) assert not _llm_spans._skipped - async def test_streamed_call_is_forgotten_once_the_stream_ends( + async def test_streamed_call_is_forgotten_when_it_returns( self, recorder: _Recorder, caplog: pytest.LogCaptureFixture ) -> None: with caplog.at_level(logging.WARNING): stream = await MockLLM(max_tokens=None).astream_complete("a b c") - # The call has returned, but iterating still emits its events. - assert _llm_spans._skipped + # The call has returned: nothing is kept, though iterating still + # emits its events. + assert not _llm_spans._skipped chunks = [chunk.delta async for chunk in stream] assert "".join(c or "" for c in chunks) == "a b c" @@ -211,6 +239,75 @@ def test_abandoned_sync_stream_closes_without_warnings( assert not [r for r in caplog.records if "Open span is missing" in r.message] assert not _llm_spans._skipped + async def test_async_stream_never_read_keeps_nothing( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + # Never iterated, so no end event will ever come for it. + stream = await MockLLM(max_tokens=None).astream_complete("a b c") + assert not _llm_spans._skipped + del stream + gc.collect() + for _ in range(5): + await asyncio.sleep(0) + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + def test_sync_stream_never_read_keeps_nothing( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = MockLLM(max_tokens=None).stream_complete("a b c") + assert not _llm_spans._skipped + del stream + gc.collect() + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + @pytest.mark.parametrize( + "event", + [ + LLMChatInProgressEvent( + messages=[], response=ChatResponse(message=ChatMessage()) + ), + LLMChatEndEvent(messages=[], response=None), + LLMCompletionInProgressEvent( + prompt="", response=CompletionResponse(text="") + ), + LLMCompletionEndEvent(prompt="", response=CompletionResponse(text="")), + ExceptionEvent(exception=GeneratorExit()), + ], + ids=lambda e: type(e).__name__, + ) + def test_late_stream_event_of_unknown_span_is_ignored( + self, recorder: _Recorder, missing_span_warnings: list[str], event: Any + ) -> None: + # What a skipped call's stream emits after the call has returned. + event.span_id = "MockLLM.stream_chat-gone" + LlamaIndexInstrumentor()._event_handler.handle(event) + + assert not missing_span_warnings + + @pytest.mark.parametrize( + "event", + [ + LLMChatStartEvent(messages=[], additional_kwargs={}, model_dict={}), + BaseEvent(), + ], + ids=lambda e: type(e).__name__, + ) + def test_other_events_of_unknown_span_still_reach_openinference( + self, recorder: _Recorder, missing_span_warnings: list[str], event: Any + ) -> None: + # Only stream events are ignored: anything else for a span OpenInference + # doesn't know is still reported as missing. + event.span_id = "Something.else-gone" + LlamaIndexInstrumentor()._event_handler.handle(event) + + assert missing_span_warnings + @pytest.mark.parametrize("value", ["true", "TRUE", "1", "yes"]) async def test_client_llm_spans_env_keeps_span_and_drops_traceparent( self, recorder: _Recorder, monkeypatch: pytest.MonkeyPatch, value: str From b70b39dd7823540665d1503d6d42224e2f50c333 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Tue, 10 Nov 2026 16:34:14 +0200 Subject: [PATCH 5/5] test(llamaindex): narrow the instrumentor's event handler for mypy Co-Authored-By: Claude Opus 5.5 --- .../tests/runtime/test_trace_context.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py index 57b9a262..e363c73a 100644 --- a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py +++ b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py @@ -145,6 +145,12 @@ def record(msg: object, *args: Any, **kwargs: Any) -> None: yield seen +def _event_handler() -> _oi_handler.EventHandler: + handler = LlamaIndexInstrumentor()._event_handler + assert handler is not None + return handler + + async def _run(llm: MockLLM) -> Any: return await _AskWorkflow(llm=llm, timeout=10).run() @@ -286,7 +292,7 @@ def test_late_stream_event_of_unknown_span_is_ignored( ) -> None: # What a skipped call's stream emits after the call has returned. event.span_id = "MockLLM.stream_chat-gone" - LlamaIndexInstrumentor()._event_handler.handle(event) + _event_handler().handle(event) assert not missing_span_warnings @@ -304,7 +310,7 @@ def test_other_events_of_unknown_span_still_reach_openinference( # Only stream events are ignored: anything else for a span OpenInference # doesn't know is still reported as missing. event.span_id = "Something.else-gone" - LlamaIndexInstrumentor()._event_handler.handle(event) + _event_handler().handle(event) assert missing_span_warnings