Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions packages/uipath-llamaindex/pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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.1, <2.16.0",
"uipath-platform>=0.3.2, <0.4.0",
"uipath-runtime>=0.13.5, <0.14.0",
]
classifiers = [
Expand Down
44 changes: 44 additions & 0 deletions packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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__)
Expand Down Expand Up @@ -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)


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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__)
Expand Down Expand Up @@ -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
Expand Down
192 changes: 192 additions & 0 deletions packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
"""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.
"""

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,
LLMChatInProgressEvent,
LLMCompletionEndEvent,
LLMCompletionInProgressEvent,
)
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

# 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 with no span that are running, and where they nest instead.

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._parents: dict[str, Optional[str]] = {}

def __contains__(self, span_id: object) -> bool:
return span_id in self._parents

def __len__(self) -> int:
return len(self._parents)

def skip(self, span_id: str, parent_id: Optional[str]) -> None:
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._parents:
return self._parents[span_id]
return span_id

def forget(self, span_id: str) -> None:
self._parents.pop(span_id, None)

def clear(self) -> None:
self._parents.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(id_)
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)

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:
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)


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
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand All @@ -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,
)
Expand Down Expand Up @@ -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(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,12 +36,6 @@
"attributes": {
"openinference.span.kind": "TOOL"
}
},
{
"name": ["UiPathChatBedrockConverse.achat", "UiPathOpenAI.achat", "UiPathVertex.achat"],
"attributes": {
"openinference.span.kind": "LLM"
}
}
]
}
Loading
Loading