Errors

Tracing raises the logger’s exception types for everything it shares with the logger — initialization, delivery, closing — plus one of its own for misuse of the tracing API.

Exception	When	Data at risk?
MetranaTracingError	The API is used out of order: a body recorded twice on one span, a span ended before it started, a child opened with no enclosing span and no parent=, a trace opened without a step on a run-anchored tracer (or with one on a project-anchored tracer), a kind-named body on a root of another kind.	No — nothing was sent.
MetranaValidationError	The engine rejects an update at start() or end(): a name over 512 bytes, an attribute under a span’s own field name (status, step, …), an attribute value over 64 KiB, a body that is not UTF-8.	No — the update was refused before enqueue.
MetranaNotInitializedError	tracing.init() without a target and without a run to take it from; get_tracer() with no tracer, no run, or tracing disabled. A trace opened with no tracer is not an error: it is inert, warned about once (see Switching off, and sampling).	No.
MetranaLoggerClosedError	An update after tracing.close().	No.
MetranaEventQueueFullError	Under Backpressure.Raise, the send queue was full for enqueue_timeout_secs.	The one update was not enqueued.
MetranaSenderError	The tracer stopped because delivery gave up under AllOrCrash; every later call raises it.	Yes — see Guarantees & retries.
MetranaTimeoutError	flush() ran out of time.	No — the data is still in flight or on the spool.
MetranaClosingError	close() failed, in particular on a deadline that expired with data still not durable.	Likely, for what was in flight.

TypeError and ValueError follow their usual meaning for wrong argument types and values (a non-integer step, a non-mapping attributes, a negative token_count, a sample_rate outside 0.0 to 1.0).

An exception raised by your code inside a span’s block is not a tracing error: the span closes with status ERROR and an exception attribute, and the exception propagates unchanged. The trace’s root counts such spans in its error_count attribute. A cancellation — an asyncio task cancelled, a generator closed early — closes the span CANCELLED instead, and is not counted. Under METRANA_TRACING_DISABLED no tracing error reaches instrumented code at all: the nodes are inert. With nothing initialized, traces and @op calls are inert too, but a child span opened with no enclosing trace still raises MetranaTracingError, as it would with tracing on.