Decorators#

The with_sentry decorator and its runtime configuration dataclass.

Sentry SDK initialization decorators.

This module provides decorators for initializing the Sentry SDK with automatic error tracking and monitoring capabilities. The decorators handle Sentry initialization, tag setting, exception capture, and event flushing.

Functions:: with_sentry: Decorator that initializes Sentry SDK and sets tags for a function.

Example

Basic usage:

from core_sentry.base import SentryConfig
from core_sentry.decorators.base import with_sentry

@with_sentry(config=SentryConfig(dsn="https://...", env="production"))
def my_function():
    return "Hello World"

ETL/script usage with automatic exception capture and flush on exit:

@with_sentry(
    config=SentryConfig(
        dsn="https://...",
        env="production",
        tags={"service": "etl-pipeline", "version": "1.0.0"},
        traces_sample_rate=0.5,
    ),
    capture_exceptions=True,
    flush=True,
    flush_timeout=5.0,
)
def run_etl():
    pass

Features:

Automatic Sentry SDK initialization with provided configuration
Tag management for enhanced error tracking and filtering
Prevention of duplicate initialization when Sentry is already configured
Support for all standard Sentry SDK configuration options
Optional automatic exception capture before re-raising
Optional event flush on function exit (success or failure)

class core_sentry.decorators.base.SentryRuntimeConfig(capture_exceptions: bool = False, flush: bool = False, flush_timeout: float = 2.0, tags: Dict[str, str] | None = None, extra: Dict[str, Any] | None = None)[source]#

Bases: object

Runtime behavior configuration for the init_sentry decorator.

Parameters:

capture_exceptions – When True, any unhandled exception raised by the wrapped function is captured and sent to Sentry before being re-raised. Defaults to False.
flush – When True, pending Sentry events are flushed after the wrapped function exits (whether it succeeded or raised). Recommended for short-lived scripts and ETLs. Defaults to False.
flush_timeout – Maximum seconds to wait for the event queue to drain when flush=True. Defaults to 2.0.
tags – Per-capture tags attached to every exception event sent via this decorator. Do not affect subsequent captures outside the decorator.
extra – Per-capture extra context attached to every exception event sent via this decorator. Do not affect subsequent captures outside the decorator.

Example:

SentryRuntimeConfig(
    capture_exceptions=True,
    flush=True,
    flush_timeout=5.0,
    tags={"job": "daily-sync"},
    extra={"rows_processed": 9999},
)

capture_exceptions: bool = False#

flush: bool = False#

flush_timeout: float = 2.0#

tags: Dict[str, str] | None = None#

extra: Dict[str, Any] | None = None#

__init__(capture_exceptions: bool = False, flush: bool = False, flush_timeout: float = 2.0, tags: Dict[str, str] | None = None, extra: Dict[str, Any] | None = None) → None#

core_sentry.decorators.base.with_sentry(_func: Callable | None = None, *, config: SentryConfig, runtime_config: SentryRuntimeConfig = SentryRuntimeConfig(capture_exceptions=False, flush=False, flush_timeout=2.0, tags=None, extra=None)) → Callable | Callable[[Callable], Callable][source]#

Decorator that initializes the Sentry SDK before the wrapped function runs.

Basic usage:

@with_sentry(config=SentryConfig(dsn="SomeDSN", env="production"))
def my_function():
    pass

Use capture_exceptions=True and flush=True on functions where you want to ensure proper error tracking, every unhandled exception is explicitly captured with its full context and all events are guaranteed to be delivered before the function ends.

@with_sentry(
    config=SentryConfig(
        dsn="SomeDSN",
        env="production",
        tags={"service": "etl-pipeline"},
    ),
    runtime_config=SentryRuntimeConfig(
        capture_exceptions=True,
        flush=True,
        tags={"job": "daily-sync"},
        extra={"rows_processed": 9999},
    ),
)
def run_etl():
    pass

Parameters:

_func – Internal that allows the decorator to be used without parentheses.
config – Sentry SDK configuration. See SentryConfig.
runtime_config – Decorator runtime behavior,exception capture, flush, and per-event tags/extra. See SentryRuntimeConfig. Defaults to SentryRuntimeConfig() (all flags off, no tags/extra).

Note

Both flags default to False because the Sentry SDK already captures unhandled exceptions via sys.excepthook and flushes via an atexit handler. Set them to True for ETLs and short-lived scripts running in containers, where a SIGKILL or OOM kill can prevent atexit from running and where per-invocation tags and extra context matter.

Decorators#

This Page