Observability
=============

Top-level ``taimoe.platform.init`` configures observability automatically. Use
native traces and spans to describe Agent, model, and tool work:

.. code-block:: python

   from taimoe.platform import trace

   with trace(
       "support-conversation",
       session_id="session-123",
       agent_id="support",
       team_id="customer-success",
   ) as run:
       with run.span("lookup-order", span_type="tool") as span:
           span.set_input({"order_id": "A-123"})
           result = lookup_order("A-123")
           span.set_output(result)

       with run.span("draft-answer", span_type="model") as span:
           answer = generate_answer(result)
           span.set_usage(prompt_tokens=120, completion_tokens=45, cost_usd=0.001)
           span.set_output(answer)

The outer trace exports its completed span batch when the context exits.
Nested spans preserve ``parent_span_id``. Exceptions mark the active span as
an error and are re-raised.

Decorators
----------

``track_agent`` creates an Agent trace when none is active. ``track_action``
adds a child span to the current trace. Both support synchronous and async
functions.

.. code-block:: python

   from taimoe.platform import track_action, track_agent

   @track_agent("support")
   async def run_support(message: str) -> str:
       return await retrieve_and_answer(message)

   @track_action("retrieve")
   async def retrieve_and_answer(message: str) -> str:
       ...

Export behavior
---------------

By default, telemetry export failure is non-fatal so observability does not
break Agent execution. Configure observability directly with
``raise_on_export_error=True`` only when a test or controlled environment must
fail closed.

Install ``taimoe-platform[otel]`` to mirror native Taimoe spans into the active
OpenTelemetry provider. W3C-compatible trace and span IDs allow the same
execution to correlate with downstream APM systems.

Avoid placing secrets or unfiltered personal data in span input, output, or
attributes. The SDK serializes and truncates values, but data classification
remains the caller's responsibility.