structlog-sentry

Warnings

• breaking In `v2.2.0`, the `SentryProcessor` constructor changed from accepting a `hub` argument (for `sentry_sdk.Hub`) to a `scope` argument (for `sentry_sdk.Client` or `sentry_sdk.Scope`).
  Fix: Replace `SentryProcessor(hub=...)` with `SentryProcessor(scope=...)`.
• breaking As of `v2.0.0`, the `as_extra` argument for `SentryProcessor` was renamed to `as_context` due to Sentry SDK's deprecation of 'extra' in favor of 'context'.
  Fix: Update `as_extra=True/False` to `as_context=True/False` in `SentryProcessor` initialization.
• breaking In `v2.0.0`, the `SentryJSONProcessor` class was removed. Users previously relying on this for JSON output must now configure `SentryProcessor` and potentially disable the default `sentry-sdk` logging integration to prevent duplicate events.
  Fix: Remove `SentryJSONProcessor`. Use `SentryProcessor` and consider passing `integrations=[sentry_sdk.integrations.logging.LoggingIntegration(event_level=None, level=None)]` to `sentry_sdk.init()` for JSON logging setups.
• breaking In `v2.0.0`, the `level` argument in `SentryProcessor` was renamed to `event_level` (controlling which log levels are sent to Sentry as events). A new `level` argument was introduced to control the log level of breadcrumbs.
  Fix: Rename `level` to `event_level` for event reporting. If breadcrumb level control is needed, use the new `level` argument: `SentryProcessor(event_level=logging.ERROR, level=logging.INFO)`.
• gotcha The `structlog.stdlib.add_log_level` and `structlog.stdlib.add_logger_name` processors must be placed *before* `SentryProcessor` in your `structlog.configure` processor chain for `SentryProcessor` to correctly access and use these log attributes.
  Fix: Adjust the order of processors in `structlog.configure()` to ensure `add_log_level` and `add_logger_name` come before `SentryProcessor`.
• gotcha If you are using `structlog.processors.format_exc_info`, place `SentryProcessor` *before* it in the processor chain. `format_exc_info` removes `exc_info` from the event dictionary, which `SentryProcessor` needs to correctly capture exception details.
  Fix: Reorder processors: `SentryProcessor(...)`, then `structlog.processors.format_exc_info`.
• gotcha When combining `structlog-sentry` with `sentry-sdk`'s default `LoggingIntegration` (which is often implicitly active), you might experience duplicate log events in Sentry, especially with JSON logging.
  Fix: Explicitly disable `sentry-sdk`'s `LoggingIntegration` when initializing the Sentry SDK by passing `integrations=[sentry_sdk.integrations.logging.LoggingIntegration(event_level=None, level=None)]` to `sentry_sdk.init()`.

Install

• pip install structlog-sentry Install latest version

Imports

• SentryProcessor

  from structlog_sentry import SentryProcessor

Quickstart

This quickstart demonstrates how to configure `structlog` to use `SentryProcessor` to send structured logs and exceptions to Sentry. Ensure `sentry_sdk.init()` is called with your DSN and `structlog.stdlib.add_log_level` (and optionally `add_logger_name`) are placed before `SentryProcessor`.

import sentry_sdk
import structlog
import logging
import os

from structlog_sentry import SentryProcessor

sentry_sdk.init(
    dsn=os.environ.get('SENTRY_DSN', 'YOUR_SENTRY_DSN_HERE'),
    # Optional: Disable Sentry SDK's default logging integration if structlog-sentry handles all Sentry logging
    # integrations=[sentry_sdk.integrations.logging.LoggingIntegration(event_level=None, level=None)]
)

structlog.configure(
    processors=[
        structlog.stdlib.add_logger_name,  # Optional, but recommended. Must be before SentryProcessor
        structlog.stdlib.add_log_level,    # Required. Must be before SentryProcessor
        SentryProcessor(event_level=logging.ERROR), # Sends events ERROR or higher to Sentry
        structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
    ],
    logger_factory=structlog.stdlib.LoggerFactory(),
    wrapper_class=structlog.stdlib.BoundLogger,
)

# Standard library logging setup (optional, for non-structlog compatible handlers)
# import sys
# logging.basicConfig(
#     format="%(message)s",
#     stream=sys.stdout,
#     level=logging.INFO,
# )

log = structlog.get_logger()

try:
    1 / 0
except ZeroDivisionError:
    log.error("A division by zero error occurred!", operation="calculate_ratio", user_id=42)

log.info("User activity log.", action="login", username="testuser")