tdfs4ds.utils.tracing

tdfs4ds.utils.tracing

Optional tracing of the tdfs4ds agents (Opik).

Off by default. With tdfs4ds.TRACING = 'opik' (env TDFS4DS_TRACING=opik), every consumer-agent and query-optimizer run gets an OpikTracer callback in its LangGraph run config. LangChain hands the run config down to every node and every nested LLM / tool call, so a turn becomes one Opik trace with a span per node and per model call, grouped into an Opik thread by the conversation's thread_id.

Where the traces go is Opik's own configuration, never a tdfs4ds setting: the Opik SDK reads its OPIK_URL_OVERRIDE / OPIK_API_KEY / OPIK_WORKSPACE variables or the file written by opik configure (on Teradata AI Studio the AgentOps platform injects them). tdfs4ds reads none of them itself; it only names the project (tdfs4ds.OPIK_PROJECT_NAME).

Contract: :func:run_callbacks never raises and returns [] whenever tracing is off, the opik package is missing, or the tracer cannot be built, so tracing can never break a turn. A tracer is a callback, never a decorator: the AgentOps entrypoint must stay a bare coroutine.

logger module-attribute

logger = getLogger('tdfs4ds')

_WARNED module-attribute

_WARNED: set = set()

_TELEMETRY_SET module-attribute

_TELEMETRY_SET = False

_warn_once

_warn_once(key: str, message: str) -> None

tracing_backend

tracing_backend() -> Optional[str]

The requested backend ('opik') or None when tracing is off.

_vendor_telemetry_off

_vendor_telemetry_off() -> None

Keep the Opik SDK's own reporting off unless OPIK_VENDOR_TELEMETRY.

Seen live: with its defaults the Opik SDK posts product analytics to stats.comet.com and sets up Sentry error reporting at import opik. Turning tdfs4ds tracing on means "send my traces to my Opik", not "report usage to the vendor", so tdfs4ds switches both off -- by WRITING Opik's own switches before the import (Sentry is configured at import time) and by registering an analytics rule; it never reads an unprefixed variable. tdfs4ds.OPIK_VENDOR_TELEMETRY = True leaves Opik's defaults alone.

_opik_tracer_class

_opik_tracer_class()

run_callbacks

run_callbacks(graph: Any = None, *, thread_id: Optional[str] = None, kind: str = 'agent', metadata: Optional[dict] = None) -> List[Any]

Callbacks to put in a LangGraph run config (config["callbacks"]).

graph is the compiled LangGraph (its drawing is attached to the trace when it can be obtained); kind tags the trace (consumer_agent, query_optimizer). Returns [] when tracing is off or unavailable.

flush_callbacks

flush_callbacks(callbacks: Optional[Iterable[Any]]) -> None

Send what the tracers buffered (end of a turn). Never raises.

tracing_status

tracing_status() -> dict

What :func:run_callbacks would do, without building a tracer.

{"backend", "installed", "configured", "detail"} -- never a value of a setting (used by check_configuration).