[DX] GAP-20: @traced decorator is undiscoverable — not exported from top-level package and not documented

[AlexBizon]

Summary

The @traced decorator in uipath.core.tracing.decorators provides OpenTelemetry span wrapping with LLM Ops integration, but is not re-exported from the top-level uipath package and is not mentioned in any SDK documentation, README, or sample. It must be discovered by grepping the installed package.

What the Decorator Does

• Wraps sync, async, generator, and async generator functions with OpenTelemetry spans
• Ships span data to llmopstenant_/api/Traces/spans (visible in Orchestrator's LLM Ops UI)
• Records input attributes before execution and output attributes after
• Records exceptions and sets span status to ERROR on failure
• Supports hide_input=True / hide_output=True to redact sensitive data
• span_type="tool" emits OpenInference tool-call semantics
• recording=False creates a non-sampled span (propagates context to children but is not sent)

Usage (found by grepping the installed package)

from uipath.core.tracing.decorators import traced

@traced(span_type="tool", name="extract_invoice_data")
def extract_invoice_data(blob_file_path: str) -> dict:
    ...

Current State

• Not importable from uipath or uipath.platform
• Not mentioned in any README, getting-started guide, or API reference
• Not mentioned in any samples
• Must be discovered by reading uipath/core/tracing/decorators.py directly

Suggested Fix

1. Re-export from the top-level package: from uipath import traced
2. Add to the SDK documentation alongside the services reference
3. Add a section in the agent getting-started guide: "Tracing tool calls"
4. Add a sample showing @traced on LangGraph tool functions with the result in LLM Ops

Agents that call tools are the primary audience — having tool calls appear as proper spans in the trace tree is high-value and directly supported but completely invisible.

Impact

• Severity: Low (hidden capability, not a bug)
• Significant value left on the table — developers instrument their own logging/timing instead