Sentry Python SDK

Warnings

• breaking Hub class removed in v2.0.0 (Jan 2024). All Hub-based patterns (Hub.current, configure_scope, push_scope via Hub) raise AttributeError. Massive volume of pre-2024 tutorials use Hub.
  Fix: Replace Hub.current.configure_scope() with sentry_sdk.new_scope(). Replace Hub.current.capture_exception() with sentry_sdk.capture_exception().
• breaking enable_tracing parameter deprecated. Still works but logs DeprecationWarning. Will be removed in next major version.
  Fix: Replace enable_tracing=True with traces_sample_rate=1.0
• gotcha Omitting traces_sample_rate means NO performance data (transactions/spans) is sent to Sentry — only errors. Default is 0.0. Many devs wonder why traces are missing.
  Fix: Add traces_sample_rate=0.1 (10%) for production or traces_sample_rate=1.0 for development.
• gotcha before_send returning None silently drops the event. Sentry logs 'before send dropped event' at INFO level — easy to miss if not watching logs.
  Fix: before_send must return the event dict to send it. Return None only when intentionally filtering.
• gotcha set_measurement() deprecated in favor of set_data() on spans. Will be removed in next major version.
  Fix: span.set_data('key', value) instead of span.set_measurement('key', value)
• gotcha sentry_sdk.init() must be called before any framework initialization (before app = FastAPI(), before Django setup). Calling it after means some auto-instrumentation is missed.
  Fix: Call sentry_sdk.init() at the very top of your entry point, before importing framework app objects.
• gotcha In async apps (FastAPI, async Django), sentry_sdk.init() should be called inside an async context or at module level before the event loop starts to ensure async instrumentation works correctly.
  Fix: Initialize at module level before app creation, not inside async startup handlers.

Install

• pip install sentry-sdk Python (base)
• pip install 'sentry-sdk[fastapi]' With FastAPI integration
• pip install 'sentry-sdk[django]' With Django integration

Imports

• sentry_sdk.init

  import sentry_sdk
  
  sentry_sdk.init(
      dsn='https://KEY@oNNN.ingest.sentry.io/PROJECT_ID',
      traces_sample_rate=1.0,   # 0.0-1.0 — required for performance
      environment='production',
      release='myapp@1.0.0',
      send_default_pii=False,   # do not send PII by default
  )
  
  # Capture exceptions
  try:
      1 / 0
  except ZeroDivisionError:
      sentry_sdk.capture_exception()
  
  # Capture message
  sentry_sdk.capture_message('Something happened', level='warning')
  
  # Add context
  with sentry_sdk.new_scope() as scope:
      scope.set_tag('component', 'checkout')
      scope.set_user({'id': '123', 'email': 'user@example.com'})
      sentry_sdk.capture_exception()

  Hub class removed in v2.0. Use sentry_sdk.new_scope() or sentry_sdk.push_scope(). enable_tracing deprecated — use traces_sample_rate=1.0.
• Framework integrations

  import sentry_sdk
  from sentry_sdk.integrations.fastapi import FastApiIntegration
  from sentry_sdk.integrations.sqlalchemy import SqlalchemyIntegration
  from sentry_sdk.integrations.celery import CeleryIntegration
  
  sentry_sdk.init(
      dsn='https://KEY@oNNN.ingest.sentry.io/PROJECT_ID',
      traces_sample_rate=0.1,  # 10% of transactions
      integrations=[
          FastApiIntegration(),
          SqlalchemyIntegration(),
          CeleryIntegration(),
      ]
  )

  Integrations must be imported and instantiated. Many are auto-detected but explicitly passing them ensures correct configuration.

Quickstart

Sentry Python SDK — error capture, context, and performance tracing.

# pip install sentry-sdk
import sentry_sdk

sentry_sdk.init(
    dsn='https://KEY@oNNN.ingest.sentry.io/PROJECT_ID',
    traces_sample_rate=1.0,
    environment='production',
    release='1.0.0',
    before_send=lambda event, hint: event  # return None to drop event
)

# Automatic exception capture — unhandled exceptions sent automatically

# Manual exception capture
try:
    result = 1 / 0
except Exception as e:
    sentry_sdk.capture_exception(e)

# Add user context
sentry_sdk.set_user({'id': '42', 'email': 'user@example.com'})

# Add tags
sentry_sdk.set_tag('payment_provider', 'razorpay')

# Add extra data
sentry_sdk.set_extra('order_id', 'ord_123')

# Breadcrumbs
sentry_sdk.add_breadcrumb(
    category='auth',
    message='User logged in',
    level='info'
)

# Performance tracing
with sentry_sdk.start_transaction(op='task', name='process_order'):
    with sentry_sdk.start_span(op='db', description='fetch order'):
        pass  # your DB call here