TraceroAI

Delivery and failures

Tracing must never slow down or break your application. How the SDK makes sure of it.

Traces go onto an in-memory queue and a background thread sends them, so tracing adds well under a millisecond to your request, and a slow or unreachable TraceroAI never holds your code up.

When sending fails#

The SDK never raises into your code when a send fails. Timeouts, 429s and 5xx responses are retried with backoff (3 times by default); after that the failure is logged on the traceroai logger and your code carries on. A rejected request (401, 413, 422) isn't retried, because retrying won't help.

To see what's happening:

Python
import logging
logging.getLogger("traceroai").setLevel(logging.DEBUG)

Short-lived processes#

Scripts, serverless handlers and tests can exit before the queue is sent. Call client.flush() before exiting. An exit hook also flushes for up to 2 seconds.

Retries never duplicate#

The client picks each trace's id, and a retried send reuses it, so the server never stores a trace twice.

A full queue#

The queue holds 1,000 traces by default (max_queue_size). When it's full, new traces are dropped and counted in client.dropped_traces rather than using more memory.

Turning it off#

TRACEROAI_ENABLED=false (or enabled=False) makes every send a no-op, which is useful in tests. For code that must know when a trace fails, use background=False, raise_on_error=True, and sends raise TraceroError.