Starlette

Learn about using Sentry with Starlette.

The Starlette integration adds support for the Starlette Framework.

Install sentry-sdk from PyPI with the starlette extra:

Copied
pip install --upgrade 'sentry-sdk[starlette]'

If you have the starlette package in your dependencies, the Starlette integration will be enabled automatically when you initialize the Sentry SDK.

Copied
from starlette.applications import Starlette
from starlette.routing import Route

sentry_sdk.init(...)  # same as above

async def trigger_error(request):
    division_by_zero = 1 / 0

app = Starlette(routes=[
    Route("/sentry-debug", trigger_error),
])

When you point your browser to http://localhost:8000/sentry-debug a transaction will be created in the Performance section of sentry.io. Additionally, an error event will be sent to sentry.io and will be connected to the transaction.

It takes a couple of moments for the data to appear in sentry.io.

  • By default, all exceptions leading to an Internal Server Error are reported. The HTTP status codes to report on are configurable via the failed_request_status_codes option.

  • Request data is attached to all events: HTTP method, URL, headers, form data, JSON payloads. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set send_default_pii to True.

  • If enable_tracing or a traces_sample_rate is set, then performance information is also reported, which you can see on the Performance page of sentry.io.

By adding StarletteIntegration explicitly to your sentry_sdk.init() call you can set options for StarletteIntegration to change its behavior:

Copied
from sentry_sdk.integrations.starlette import StarletteIntegration

sentry_sdk.init(
    # ...
    integrations=[
        StarletteIntegration(
            transaction_style="endpoint",
            failed_request_status_codes=[403, range(500, 599)],
            middleware_spans=False,
        )
    ],
)

You can pass the following keyword arguments to StarletteIntegration():

  • transaction_style:

    Copied
    async def product_detail(request):
    return JSONResponse({...})

app = Starlette(routes=[
    Route('/catalog/product/{product_id}', product_detail),
])

    In the above code, the transaction name will be:

    • "/catalog/product/{product_id}" if you set transaction_style="url".
    • "product_detail" if you set transaction_style="endpoint"

    The default is "url".

  • failed_request_status_codes:

    A list of integers or containers (objects that allow membership checks via in) of integers that will determine which status codes should be reported to Sentry.

    Examples of valid failed_request_status_codes:

    • [500] will only send events on HTTP 500.
    • [400, range(500, 599)] will send events on HTTP 400 as well as the 500-599 range.
    • [500, 503] will send events on HTTP 500 and 503.

    The default is [range(500, 599)].

  • middleware_spans:

    Create spans and track performance of all middleware in your Starlette project. Set to False to disable.

    The default is True.

  • Starlette: 0.19.1+
  • Python: 3.7+
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").