refactor(sentry_integration): enhance error handling and telemetry across services

- Integrated `capture_exception_safe` in various modules to improve exception tracking with additional context, enhancing observability during error occurrences.
- Updated error handling in the EmojiManager, HotReload, and GitHubService to capture and report errors with specific operation context.
- Streamlined exception logging across multiple services, ensuring unexpected errors are reported to Sentry while maintaining appropriate logging levels for expected behaviors.
- Added metrics recording for command execution, database operations, and API calls to improve performance tracking and observability.

Author: kzndotsh

src/tux/services/emoji_manager.py

@@ -14,6 +14,8 @@
 from discord.ext import commands
 from loguru import logger
 
+from tux.services.sentry import capture_exception_safe
+
 # --- Configuration Constants ---
 
 DEFAULT_EMOJI_ASSETS_PATH = Path(__file__).parents[3] / "assets" / "emojis"
@@ -84,9 +86,16 @@ def _read_emoji_file(file_path: Path) -> bytes | None:
         return None
 
     except Exception as e:
-        logger.exception(
+        logger.error(
             f"An unexpected error occurred reading file '{file_path}': {e}",
         )
+        capture_exception_safe(
+            e,
+            extra_context={
+                "operation": "read_local_file",
+                "file_path": str(file_path),
+            },
+        )
         return None
 
 
@@ -188,16 +197,30 @@ async def init(self) -> bool:
                 logger.error(f"Failed to fetch application emojis during init: {e}")
                 self._initialized = False
                 return False
-            except discord.DiscordException:
-                logger.exception(
+            except discord.DiscordException as e:
+                logger.error(
                     "Unexpected Discord error during emoji cache initialization.",
                 )
+                capture_exception_safe(
+                    e,
+                    extra_context={
+                        "operation": "emoji_cache_initialization",
+                        "error_type": "DiscordException",
+                    },
+                )
                 self._initialized = False
                 return False
-            except Exception:
-                logger.exception(
+            except Exception as e:
+                logger.error(
                     "Unexpected non-Discord error during emoji cache initialization.",
                 )
+                capture_exception_safe(
+                    e,
+                    extra_context={
+                        "operation": "emoji_cache_initialization",
+                        "error_type": "non-Discord",
+                    },
+                )
                 self._initialized = False
                 return False
 
@@ -268,9 +291,16 @@ async def _create_discord_emoji(
         except ValueError as e:
             logger.error(f"Invalid value for creating emoji '{name}': {e}")
         except Exception as e:
-            logger.exception(
+            logger.error(
                 f"An unexpected error occurred creating emoji '{name}': {e}",
             )
+            capture_exception_safe(
+                e,
+                extra_context={
+                    "operation": "create_emoji",
+                    "emoji_name": name,
+                },
+            )
 
         return None
 
@@ -425,9 +455,16 @@ async def _delete_discord_emoji(self, name: str) -> bool:
         except discord.HTTPException as e:
             logger.error(f"Failed to delete application emoji '{name}': {e}")
         except Exception as e:
-            logger.exception(
+            logger.error(
                 f"An unexpected error occurred deleting emoji '{name}': {e}",
             )
+            capture_exception_safe(
+                e,
+                extra_context={
+                    "operation": "delete_emoji",
+                    "emoji_name": name,
+                },
+            )
 
         finally:
             # Always remove from cache if it was found initially

src/tux/services/hot_reload/service.py

@@ -153,7 +153,8 @@ async def _reload_extension_with_monitoring(self, extension: str) -> None:
         self._reload_stats["total_reloads"] += 1
 
         try:
-            with sentry_sdk.configure_scope() as scope:
+            # Use push_scope for isolated scope to avoid polluting current scope
+            with sentry_sdk.push_scope() as scope:
                 scope.set_tag("extension", extension)
                 scope.set_tag("reload_type", "hot_reload")
 

src/tux/services/sentry/__init__.py

@@ -60,12 +60,21 @@
 # Set initial user to None
 sentry_sdk.set_user(None)
 
+from .metrics import (
+    record_api_metric,
+    record_cache_metric,
+    record_cog_metric,
+    record_command_metric,
+    record_database_metric,
+    record_task_metric,
+)
 from .utils import (
     capture_api_error,
     capture_cog_error,
     capture_database_error,
     capture_exception_safe,
     capture_tux_exception,
+    convert_httpx_error,
 )
 
 __all__ = [
@@ -97,11 +106,19 @@
     "capture_exception_safe",
     "capture_span_exception",
     "capture_tux_exception",
+    "convert_httpx_error",
     # Instrumentation and tracking
     "instrument_bot_commands",
     "safe_set_name",
     "track_command_end",
     "track_command_start",
+    # Metrics functions
+    "record_api_metric",
+    "record_cache_metric",
+    "record_cog_metric",
+    "record_command_metric",
+    "record_database_metric",
+    "record_task_metric",
 ]
 
 
@@ -284,7 +301,7 @@ def get_current_span(self) -> Any | None:
         """
         return get_current_span()
 
-    def start_transaction(self, op: str, name: str, description: str = "") -> Any:
+    def start_transaction(self, op: str, name: str) -> Any:
         """
         Start a new Sentry transaction.
 
@@ -294,33 +311,31 @@ def start_transaction(self, op: str, name: str, description: str = "") -> Any:
             The operation type.
         name : str
             The transaction name.
-        description : str, optional
-            A description of the transaction.
 
         Returns
         -------
         Any
             The started transaction object.
         """
-        return start_transaction(op, name, description)
+        return start_transaction(op, name)
 
-    def start_span(self, op: str, description: str = "") -> Any:
+    def start_span(self, op: str, name: str = "") -> Any:
         """
         Start a new Sentry span.
 
         Parameters
         ----------
         op : str
             The operation name for the span.
-        description : str, optional
-            A description of the span.
+        name : str, optional
+            The name of the span.
 
         Returns
         -------
         Any
             The started span object.
         """
-        return start_span(op, description)
+        return start_span(op, name)
 
     def add_breadcrumb(
         self,

src/tux/services/sentry/cog.py

@@ -51,7 +51,7 @@ async def on_app_command_completion(self, interaction: discord.Interaction) -> N
             set_command_context(interaction)
             set_user_context(interaction.user)
 
-            # Track completion
+            # Track completion (command_type will be determined in track_command_end)
             track_command_end(interaction.command.qualified_name, success=True)
 
     async def cog_load(self) -> None:

src/tux/services/sentry/config.py

@@ -88,11 +88,24 @@ def report_signal(signum: int, _frame: FrameType | None) -> None:
             signal.SIGINT.value: "SIGINT",
         }.get(signum, f"SIGNAL_{signum}")
 
-        sentry_sdk.capture_message(
-            f"Received {signal_name}, initiating graceful shutdown",
-            level="info",
+        # Add more context to the message to avoid "(No error message)" in Sentry
+        message = (
+            f"Received {signal_name}, initiating graceful shutdown. "
+            f"This is a normal shutdown signal, not an error."
         )
 
+        scope.set_context(
+            "signal_details",
+            {
+                "signal_number": signum,
+                "signal_name": signal_name,
+                "shutdown_type": "graceful",
+                "is_error": False,
+            },
+        )
+
+        sentry_sdk.capture_message(message, level="info")
+
         logger.info(f"Signal {signal_name} reported to Sentry")
 
 

src/tux/services/sentry/context.py

@@ -22,25 +22,55 @@
 
 
 def set_user_context(user: discord.User | discord.Member) -> None:
-    # sourcery skip: extract-method
-    """Set user context for Sentry events."""
+    """
+    Set user context for Sentry events using Discord user information.
+
+    This function identifies users in Sentry using their Discord user ID as the
+    primary identifier. This enables user-based filtering, grouping, and analytics
+    in Sentry, allowing you to see which users encountered errors.
+
+    Parameters
+    ----------
+    user : discord.User | discord.Member
+        The Discord user to set as context. Must have an `id` attribute.
+
+    Notes
+    -----
+    The user ID (Discord snowflake) is used as Sentry's user identifier, enabling:
+    - User-based error grouping and filtering
+    - User impact analysis (how many users affected)
+    - User-specific error tracking
+    - User analytics in Sentry Insights
+
+    Additional Discord-specific data is included as custom user attributes:
+    - Username and display name for better identification
+    - Guild information (if member)
+    - Permissions and roles (if member)
+    - Bot/system flags
+    """
     if not is_initialized():
         return
 
+    # Primary identifier: Discord user ID (required by Sentry)
     user_data = {
-        "id": str(user.id),
-        "username": user.name,
-        "display_name": user.display_name,
-        "bot": user.bot,
-        "system": getattr(user, "system", False),
+        "id": str(user.id),  # Discord user ID - used as unique identifier in Sentry
+        "username": user.name,  # Discord username
+        "display_name": user.display_name,  # Display name (nickname or username)
+        "bot": user.bot,  # Whether user is a bot
+        "system": getattr(user, "system", False),  # Whether user is a system user
     }
 
+    # Additional Discord-specific context (if member with guild)
     if isinstance(user, discord.Member) and user.guild:
-        user_data["guild_id"] = str(user.guild.id)
-        user_data["guild_name"] = user.guild.name
-        user_data["guild_member_count"] = str(user.guild.member_count)
-        user_data["guild_permissions"] = str(user.guild_permissions.value)
-        user_data["top_role"] = user.top_role.name if user.top_role else None
+        user_data.update(
+            {
+                "guild_id": str(user.guild.id),
+                "guild_name": user.guild.name,
+                "guild_member_count": str(user.guild.member_count),
+                "guild_permissions": str(user.guild_permissions.value),
+                "top_role": user.top_role.name if user.top_role else None,
+            },
+        )
         if user.joined_at:
             user_data["joined_at"] = user.joined_at.isoformat()
 
@@ -86,9 +116,11 @@ def track_command_end(
     if not is_initialized():
         return
 
+    execution_time_ms = 0.0
     if start_time := _command_start_times.pop(command_name, None):
         execution_time = time.perf_counter() - start_time
-        set_tag("command.execution_time_ms", round(execution_time * 1000, 2))
+        execution_time_ms = round(execution_time * 1000, 2)
+        set_tag("command.execution_time_ms", execution_time_ms)
 
     set_tag("command.success", success)
     if error:
@@ -102,6 +134,19 @@ def track_command_end(
             },
         )
 
+    # Record metrics for command execution
+    # Note: command_type detection would require passing context, defaulting to "unknown"
+    # This can be enhanced later by modifying track_command_end signature
+    from .metrics import record_command_metric  # noqa: PLC0415
+
+    record_command_metric(
+        command_name=command_name,
+        execution_time_ms=execution_time_ms,
+        success=success,
+        error_type=type(error).__name__ if error else None,
+        command_type="unknown",  # Could be enhanced to detect prefix/slash from context
+    )
+
 
 def _set_command_context_from_ctx(ctx: commands.Context[commands.Bot]) -> None:
     """Set context from a command context."""