sentry ¶

Sentry Integration Manager.

This module provides the SentryManager class, a centralized wrapper for all interactions with the Sentry SDK. Its primary responsibilities include:

Initialization: Configuring and initializing the Sentry SDK with the appropriate DSN, release version, and environment settings.
Graceful Shutdown: Handling OS signals (SIGTERM, SIGINT) to ensure that all pending Sentry events are flushed before the application exits.
Context Management: Providing methods to enrich Sentry events with contextual data, such as user information, command details, and custom tags.
Event Capturing: Offering a simplified interface (capture_exception, capture_message) for sending events to Sentry.

Modules:

cog –

Sentry integration cog for command tracking and context enrichment.
config –

Sentry configuration and setup.
context –

Context management for Sentry events.
handlers –

Event filtering and processing handlers for Sentry.
tracing –

Sentry Instrumentation Utilities for Tracing and Performance Monitoring.
utils –

Sentry utility functions for specialized error reporting.

Classes:

DummySpan –

A no-op (dummy) span object for when the Sentry SDK is not initialized.
DummyTransaction –

A no-op (dummy) transaction object for when Sentry is not initialized.
SentryManager –

Handles all interactions with the Sentry SDK for the bot.

Functions:

set_command_context –

Set command context for Sentry events.
set_context –

Set context data in the current Sentry scope.
set_tag –

Set a tag in the current Sentry scope.
set_user_context –

Set user context for Sentry events.
track_command_end –

Track command execution end and performance metrics.
track_command_start –

Track command execution start time.
add_breadcrumb –

Add a breadcrumb to the current Sentry scope.
capture_span_exception –

Capture an exception in the current span with consistent error handling.
enhanced_span –

Enhanced context manager for creating a Sentry span with initial data.
finish_transaction_on_error –

Finish the current transaction with error status.
get_current_span –

Get the current active Sentry span.
instrument_bot_commands –

Automatically instruments all bot commands with Sentry transactions.
safe_set_name –

Safely set the name on a span or transaction object.
set_setup_phase_tag –

Set a setup phase tag on the span.
set_span_attributes –

Set multiple tags and data attributes on the current active Sentry span.
span –

Wrap a function with a Sentry span.
start_span –

Context manager for creating a Sentry span for a block of code.
start_transaction –

Context manager for creating a Sentry transaction for a block of code.
transaction –

Wrap a function with a Sentry transaction.
capture_api_error –

Capture an API-related error with context.
capture_cog_error –

Capture a cog-related error with context.
capture_database_error –

Capture a database-related error with context.
capture_exception_safe –

Safely capture an exception with optional context and locals.
capture_tux_exception –

Capture a TuxError with specialized context.

Classes¶

DummySpan ¶

Python

DummySpan()

A no-op (dummy) span object for when the Sentry SDK is not initialized.

This class mimics the interface of a Sentry span but performs no actions, allowing instrumentation code (with start_span(...)) to run without errors even if Sentry is disabled.

Initialize the dummy span.

Returned by: Subclassed by:

Used by:

Yielded by:

Methods:

set_tag –

No-op tag setter.
set_data –

No-op data setter.
set_status –

No-op status setter.
set_name –

No-op name setter.

Functions¶

set_tag ¶

Python

set_tag(*args: Any, **kwargs: Any) -> DummySpan

No-op tag setter.

Returns:

DummySpan –

Returns self for method chaining.

set_data ¶

Python

set_data(*args: Any, **kwargs: Any) -> DummySpan

No-op data setter.

Returns:

DummySpan –

Returns self for method chaining.

set_status ¶

Python

set_status(*args: Any, **kwargs: Any) -> DummySpan

No-op status setter.

Returns:

DummySpan –

Returns self for method chaining.

set_name ¶

Python

set_name(name: str) -> DummySpan

No-op name setter.

Returns:

DummySpan –

Returns self for method chaining.

DummyTransaction ¶

Python

DummyTransaction()

Bases: DummySpan

A no-op (dummy) transaction object for when Sentry is not initialized.

This inherits from DummySpan and provides a safe fallback for the start_transaction context manager.

Initialize the dummy span.

Returned by:

Yielded by:

Methods:

set_tag –

No-op tag setter.
set_data –

No-op data setter.
set_status –

No-op status setter.
set_name –

No-op name setter.

Functions¶

set_tag ¶

Python

set_tag(*args: Any, **kwargs: Any) -> DummySpan

No-op tag setter.

Returns:

DummySpan –

Returns self for method chaining.

set_data ¶

Python

set_data(*args: Any, **kwargs: Any) -> DummySpan

No-op data setter.

Returns:

DummySpan –

Returns self for method chaining.

set_status ¶

Python

set_status(*args: Any, **kwargs: Any) -> DummySpan

No-op status setter.

Returns:

DummySpan –

Returns self for method chaining.

set_name ¶

Python

set_name(name: str) -> DummySpan

No-op name setter.

Returns:

DummySpan –

Returns self for method chaining.

SentryManager ¶

Python

SentryManager()

Handles all interactions with the Sentry SDK for the bot.

This class acts as a singleton-like manager (though not strictly enforced) for initializing Sentry, capturing events, and managing performance monitoring transactions.

Initialize the SentryManager.

Methods:

setup –

Initialize Sentry SDK with configuration.
flush –

Flush pending Sentry events.
report_signal –

Report signal reception to Sentry.
flush_async –

Flush pending Sentry events asynchronously.
capture_exception –

Capture an exception and send it to Sentry.
capture_message –

Capture a message and send it to Sentry.
set_tag –

Set a tag in the current Sentry scope.
set_context –

Set context data in the current Sentry scope.
finish_transaction_on_error –

Finish the current transaction with error status.
set_user_context –

Set user context for Sentry events.
set_command_context –

Set command context for Sentry events.
get_current_span –

Get the current active Sentry span.
start_transaction –

Start a new Sentry transaction.
start_span –

Start a new Sentry span.
add_breadcrumb –

Add a breadcrumb to the current Sentry scope.
track_command_start –

Track command execution start time.
track_command_end –

Track command execution end and performance metrics.

Attributes:

is_initialized (bool) –

Check if Sentry is initialized.

Attributes¶

is_initialized `property` ¶

Python

is_initialized: bool

Check if Sentry is initialized.

Functions¶

setup `staticmethod` ¶

Python

setup() -> None

Initialize Sentry SDK with configuration.

flush `staticmethod` ¶

Python

flush() -> None

Flush pending Sentry events.

report_signal `staticmethod` ¶

Python

report_signal(signum: int, frame: Any = None) -> None

Report signal reception to Sentry.

flush_async `async` `staticmethod` ¶

Python

flush_async(flush_timeout: float = 10.0) -> None

Flush pending Sentry events asynchronously.

capture_exception ¶

Python

capture_exception(
    error: Exception | None = None,
    *,
    contexts: dict[str, dict[str, Any]] | None = None,
    tags: dict[str, Any] | None = None,
    user: User | Member | None = None,
    command_context: ContextOrInteraction | None = None,
    extra: dict[str, Any] | None = None,
    level: LogLevelStr = "error",
    fingerprint: list[str] | None = None,
) -> None

Capture an exception and send it to Sentry.

Parameters:

error (Exception | None, default: None ) –

The exception to capture. If None, captures the current exception.
contexts (dict[str, dict[str, Any]] | None, default: None ) –

Additional context data to include.
tags (dict[str, Any] | None, default: None ) –

Tags to add to the event.
user (User | Member | None, default: None ) –

User context to include.
command_context (ContextOrInteraction | None, default: None ) –

Command or interaction context.
extra (dict[str, Any] | None, default: None ) –

Extra data to include.
level (LogLevelStr, default: 'error' ) –

The severity level of the event.
fingerprint (list[str] | None, default: None ) –

Custom fingerprint for grouping events.

capture_message ¶

Python

capture_message(message: str, level: LogLevelStr = 'info') -> None

Capture a message and send it to Sentry.

Parameters:

message (str) –

The message to capture.
level (LogLevelStr, default: 'info' ) –

The severity level of the message.

set_tag ¶

Python

set_tag(key: str, value: Any) -> None

Set a tag in the current Sentry scope.

Parameters:

key (str) –

The tag key.
value (Any) –

The tag value.

set_context ¶

Python

set_context(key: str, value: dict[str, Any]) -> None

Set context data in the current Sentry scope.

Parameters:

key (str) –

The context key.
value (dict[str, Any]) –

The context data.

finish_transaction_on_error ¶

Python

finish_transaction_on_error() -> None

Finish the current transaction with error status.

set_user_context ¶

Python

set_user_context(user: User | Member) -> None

Set user context for Sentry events.

Parameters:

user (User | Member) –

The Discord user to set as context.

set_command_context ¶

Python

set_command_context(ctx: ContextOrInteraction) -> None

Set command context for Sentry events.

Parameters:

ctx (ContextOrInteraction) –

The command context or interaction.

get_current_span ¶

Python

get_current_span() -> Any | None

Get the current active Sentry span.

Returns:

Any | None –

The current span, or None if no span is active.

start_transaction ¶

Python

start_transaction(op: str, name: str, description: str = '') -> Any

Start a new Sentry transaction.

Parameters:

op (str) –

The operation type.
name (str) –

The transaction name.
description (str, default: '' ) –

A description of the transaction.

Returns:

Any –

The started transaction object.

start_span ¶

Python

start_span(op: str, description: str = '') -> Any

Start a new Sentry span.

Parameters:

op (str) –

The operation name for the span.
description (str, default: '' ) –

A description of the span.

Returns:

Any –

The started span object.

add_breadcrumb ¶

Python

add_breadcrumb(
    message: str,
    category: str = "default",
    level: LogLevelStr = "info",
    data: dict[str, Any] | None = None,
) -> None

Add a breadcrumb to the current Sentry scope.

Parameters:

message (str) –

The breadcrumb message.
category (str, default: 'default' ) –

The breadcrumb category.
level (LogLevelStr, default: 'info' ) –

The breadcrumb level.
data (dict[str, Any] | None, default: None ) –

Additional data for the breadcrumb.

track_command_start ¶

Python

track_command_start(command_name: str) -> None

Track command execution start time.

Parameters:

command_name (str) –

The name of the command being executed.

track_command_end ¶

Python

track_command_end(
    command_name: str, success: bool, error: Exception | None = None
) -> None

Track command execution end and performance metrics.

Parameters:

command_name (str) –

The name of the command that finished.
success (bool) –

Whether the command executed successfully.
error (Exception | None, default: None ) –

The error that occurred, if any.

Functions¶

set_command_context ¶

Python

set_command_context(ctx: ContextOrInteraction) -> None

Set command context for Sentry events.

set_context ¶

Python

set_context(key: str, value: dict[str, Any]) -> None

Set context data in the current Sentry scope.

set_tag ¶

Python

set_tag(key: str, value: Any) -> None

Set a tag in the current Sentry scope.

set_user_context ¶

Python

set_user_context(user: User | Member) -> None

Set user context for Sentry events.

track_command_end ¶

Python

track_command_end(
    command_name: str, success: bool, error: Exception | None = None
) -> None

Track command execution end and performance metrics.

track_command_start ¶

Python

track_command_start(command_name: str) -> None

Track command execution start time.

add_breadcrumb ¶

Python

add_breadcrumb(
    message: str,
    category: str = "default",
    level: str = "info",
    data: dict[str, Any] | None = None,
) -> None

Add a breadcrumb to the current Sentry scope.

capture_span_exception ¶

Python

capture_span_exception(exception: Exception, **extra_data: Any) -> None

Capture an exception in the current span with consistent error handling.

This consolidates the common pattern of setting span status and data when an exception occurs.

Parameters:

exception (Exception) –

The exception to capture.
**extra_data (Any, default: {} ) –

Additional data to attach to the span.

enhanced_span ¶

Python

enhanced_span(
    op: str, name: str = "", **initial_data: Any
) -> Generator[DummySpan | Any]

Enhanced context manager for creating a Sentry span with initial data.

This extends the basic start_span with the ability to set initial tags and data, reducing boilerplate in calling code.

Parameters:

op (str) –

The operation name for the span.
name (str, default: '' ) –

The name for the span.
**initial_data (Any, default: {} ) –

Initial data to set on the span.

Yields:

Union[DummySpan, Span] –

The Sentry span object or a dummy object if Sentry is not initialized.

finish_transaction_on_error ¶

Python

finish_transaction_on_error() -> None

Finish the current transaction with error status.

get_current_span ¶

Python

get_current_span() -> Any | None

Get the current active Sentry span.

Returns:

Any | None –

The current span if Sentry is initialized, None otherwise.

instrument_bot_commands ¶

Python

instrument_bot_commands(bot: Bot) -> None

Automatically instruments all bot commands with Sentry transactions.

This function iterates through all registered commands on the bot and wraps their callbacks with the @transaction decorator. This ensures that every command invocation is captured as a Sentry transaction.

Parameters:

bot (Bot) –

The instance of the bot whose commands should be instrumented.

safe_set_name ¶

Python

safe_set_name(obj: Any, name: str) -> None

Safely set the name on a span or transaction object.

This helper is used because the set_name method may not always be present on all span-like objects from Sentry, so this avoids potential AttributeError exceptions.

Parameters:

obj (Any) –

The span or transaction object.
name (str) –

The name to set.

set_setup_phase_tag ¶

Python

set_setup_phase_tag(span: Any, phase: str, status: str = 'starting') -> None

Set a setup phase tag on the span.

Parameters:

span (Any) –

The Sentry span to tag
phase (str) –

The phase name (e.g., "database", "cogs")
status (str, default: 'starting' ) –

The status ("starting" or "finished")

set_span_attributes ¶

Python

set_span_attributes(attributes: dict[str, Any]) -> None

Set multiple tags and data attributes on the current active Sentry span.

This helper function simplifies attaching context to a span by accepting a dictionary of attributes. Keys are automatically treated as tags.

Parameters:

attributes (dict[str, Any]) –

A dictionary where keys are the attribute names and values are the attribute values to set on the span.

span ¶

Python

span(
    op: str, description: str | None = None
) -> Callable[[Callable[P, R]], Callable[P, R]]

Wrap a function with a Sentry span.

This should be used on functions called within an existing transaction. It automatically handles both sync and async functions, captures execution time, and records success or failure status.

Parameters:

op (str) –

The operation name for the span (e.g., 'db.query.fetch').
description (Optional[str], default: None ) –

A description of what the span is doing. Defaults to the function's name.

Returns:

Callable –

The decorated function.

start_span ¶

Python

start_span(op: str, name: str = '') -> Generator[DummySpan | Any]

Context manager for creating a Sentry span for a block of code.

Example: with start_span("db.query", "Fetching user data"): ...

Parameters:

op (str) –

The operation name for the span.
name (str, default: '' ) –

The name of the span.

Yields:

Union[DummySpan, Span] –

The Sentry span object or a dummy object if Sentry is not initialized.

start_transaction ¶

Python

start_transaction(
    op: str, name: str, description: str = ""
) -> Generator[DummyTransaction | Any]

Context manager for creating a Sentry transaction for a block of code.

Example: with start_transaction("task", "process_daily_report"): ...

Parameters:

op (str) –

The operation name for the transaction.
name (str) –

The name for the transaction.
description (str, default: '' ) –

A description of what the transaction is doing.

Yields:

Union[DummyTransaction, Transaction] –

The Sentry transaction object or a dummy object if Sentry is not initialized.

transaction ¶

Python

transaction(
    op: str, name: str | None = None, description: str | None = None
) -> Callable[[Callable[P, R]], Callable[P, R]]

Wrap a function with a Sentry transaction.

This handles both synchronous and asynchronous functions automatically. It captures the function's execution time, sets the status to 'ok' on success or 'internal_error' on failure, and records exceptions.

Parameters:

op (str) –

The operation name for the transaction (e.g., 'db.query').
name (Optional[str], default: None ) –

The name for the transaction. Defaults to the function's qualified name.
description (Optional[str], default: None ) –

A description of what the transaction is doing.

Returns:

Callable –

The decorated function.

capture_api_error ¶

Python

capture_api_error(
    error: Exception,
    *,
    endpoint: str | None = None,
    status_code: int | None = None,
    response_data: dict[str, Any] | None = None,
) -> None

Capture an API-related error with context.

capture_cog_error ¶

Python

capture_cog_error(
    error: Exception,
    *,
    cog_name: str,
    command_name: str | None = None,
    event_name: str | None = None,
) -> None

Capture a cog-related error with context.

capture_database_error ¶

Python

capture_database_error(
    error: Exception,
    *,
    query: str | None = None,
    table: str | None = None,
    operation: str | None = None,
) -> None

Capture a database-related error with context.

capture_exception_safe ¶

Python

capture_exception_safe(
    error: Exception,
    *,
    extra_context: dict[str, Any] | None = None,
    capture_locals: bool = False,
) -> None

Safely capture an exception with optional context and locals.

capture_tux_exception ¶

Python

capture_tux_exception(
    error: TuxError,
    *,
    command_name: str | None = None,
    user_id: str | None = None,
    guild_id: str | None = None,
) -> None

Capture a TuxError with specialized context.

sentry ¶

Classes¶

DummySpan ¶

Functions¶

set_tag ¶

set_data ¶

set_status ¶

set_name ¶

DummyTransaction ¶

Functions¶

set_tag ¶

set_data ¶

set_status ¶

set_name ¶

SentryManager ¶

Attributes¶

is_initialized property ¶

Functions¶

setup staticmethod ¶

flush staticmethod ¶

report_signal staticmethod ¶

flush_async async staticmethod ¶

capture_exception ¶

capture_message ¶

set_tag ¶

set_context ¶

finish_transaction_on_error ¶

set_user_context ¶

set_command_context ¶

get_current_span ¶

start_transaction ¶

start_span ¶

add_breadcrumb ¶

track_command_start ¶

track_command_end ¶

Functions¶

set_command_context ¶

set_context ¶

set_tag ¶

set_user_context ¶

track_command_end ¶

track_command_start ¶

add_breadcrumb ¶

capture_span_exception ¶

enhanced_span ¶

finish_transaction_on_error ¶

get_current_span ¶

instrument_bot_commands ¶

safe_set_name ¶

set_setup_phase_tag ¶

set_span_attributes ¶

span ¶

start_span ¶

start_transaction ¶

transaction ¶

capture_api_error ¶

capture_cog_error ¶

capture_database_error ¶

capture_exception_safe ¶

capture_tux_exception ¶

is_initialized `property` ¶

setup `staticmethod` ¶

flush `staticmethod` ¶

report_signal `staticmethod` ¶

flush_async `async` `staticmethod` ¶