exception_handling

Module

Decorators for resilient ingestion/telemetry operations.

These decorators should ONLY be used for fire-and-forget operations where failures should not crash the user’s application (e.g., trace ingestion, span logging).

DO NOT use for resource management operations (CRUD) - those should raise exceptions so users get clear feedback about failures.

async_warn_catch_exception

def async_warn_catch_exception(logger: Logger=logging.getLogger(__name__),
                               exceptions: tuple[type[Exception], ...]=INFRASTRUCTURE_EXCEPTIONS) -> Callable

Decorator for resilient asynchronous ingestion/telemetry operations.

Catches infrastructure exceptions (network errors, timeouts) and logs them as warnings instead of raising. Returns None when an exception is caught.

Use this decorator ONLY for fire-and-forget operations where failures should not crash the user’s application (e.g., async trace ingestion).

DO NOT use for resource management operations (CRUD) - those should raise.

Arguments

• logger (Logger): The logger to use for warning messages. Defaults to module logger.
• exceptions (tuple[type[Exception], ...]): Tuple of exception types to catch. Defaults to INFRASTRUCTURE_EXCEPTIONS.

Returns

• Callable: A decorator that wraps the async function with exception handling.

Examples

@async_warn_catch_exception()
async def ingest_trace(trace_data: dict) -> None:
    # Network errors will be caught and logged, not raised
    await api_client.post("/traces", json=trace_data)

retry_on_transient_http_error

def retry_on_transient_http_error(func: Callable) -> Callable

Decorator for backoff retry logic on transient HTTP errors.

This decorator is designed to work WITH the backoff library. It catches GalileoHTTPException and decides whether to re-raise (triggering a retry) or return None (giving up silently).

Retryable errors (re-raised for backoff):

• 404: Record not found (eventual consistency)
• 408: Request timeout
• 422: Parent record not found yet
• 429: Rate limited
• 500+: Server errors

Non-retryable errors (returns None, logs error):

• 401: Unauthorized
• 403: Forbidden
• 400: Bad request
• Other client errors

Arguments

• func (Callable): An async function to wrap with retry logic.

Returns

• Callable: The wrapped async function.

Examples

@backoff.on_exception(backoff.expo, Exception, max_tries=5)
@retry_on_transient_http_error
async def update_trace(request: TraceUpdateRequest) -> None:
    await api_client.update_trace(request)

Notes

This decorator only works with async functions. It’s designed to be used as the innermost decorator, with backoff as the outer decorator.

warn_catch_exception

def warn_catch_exception(logger: Logger=logging.getLogger(__name__),
                         exceptions: tuple[type[Exception], ...]=INFRASTRUCTURE_EXCEPTIONS) -> Callable

Decorator for resilient synchronous ingestion/telemetry operations.

Catches infrastructure exceptions (network errors, timeouts) and logs them as warnings instead of raising. Returns None when an exception is caught.

Use this decorator ONLY for fire-and-forget operations where failures should not crash the user’s application (e.g., trace ingestion).

DO NOT use for resource management operations (CRUD) - those should raise.

Arguments

• logger (Logger): The logger to use for warning messages. Defaults to module logger.
• exceptions (tuple[type[Exception], ...]): Tuple of exception types to catch. Defaults to INFRASTRUCTURE_EXCEPTIONS.

Returns

• Callable: A decorator that wraps the function with exception handling.

Examples

@warn_catch_exception()
def ingest_trace(trace_data: dict) -> None:
    # Network errors will be caught and logged, not raised
    api_client.post("/traces", json=trace_data)