---
title: "Logs"
description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry using the Python SDK."
url: https://docs.sentry.io/platforms/python/logs/
---

# Set Up Logs for Python

## Set up with Sentry CLI

Set up the Sentry Python SDK with the Sentry CLI. Install the CLI with one of these commands, then follow the Sentry CLI docs to finish setup.

**cURL**

```bash
curl https://cli.sentry.dev/install -fsS | bash
```

**PowerShell**

```powershell
irm https://cli.sentry.dev/install.ps1 | iex
```

**Homebrew**

```bash
brew install getsentry/tools/sentry
```

**npx**

```bash
npx sentry@latest
```

[Learn more about the Sentry CLI](https://cli.sentry.dev/)

With Sentry Structured Logs, you can send text-based log information from your applications to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes.

## [Requirements](https://docs.sentry.io/platforms/python/logs.md#requirements)

Logs for Python are supported in Sentry Python SDK version `2.35.0` and above.

```bash
pip install "sentry-sdk"
```

*Other available variations of the above snippet: uv*

## [Setup](https://docs.sentry.io/platforms/python/logs.md#setup)

Logging is enabled by default, no extra configuration needed.

```python
sentry_sdk.init(
    dsn="https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
)
```

## [Usage](https://docs.sentry.io/platforms/python/logs.md#usage)

Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `sentry_sdk.logger` APIs.

The `logger` namespace exposes six methods that you can use to log messages at different log levels: `trace`, `debug`, `info`, `warning`, `error`, and `fatal`.

You can send structured messages by using the `{attribute_name}` placeholder syntax. The properties of this message will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.

```python
import sentry_sdk

sentry_sdk.init(...)

sentry_sdk.logger.trace('Starting database connection {database}', database="users")
sentry_sdk.logger.debug('Cache miss for user {user_id}', user_id=123)
sentry_sdk.logger.info('Updated global cache')
sentry_sdk.logger.warning('Rate limit reached for endpoint {endpoint}', endpoint='/api/results/')
sentry_sdk.logger.error('Failed to process payment. Order: {order_id}. Amount: {amount}', order_id="or_2342", amount=99.99)
sentry_sdk.logger.fatal('Database {database} connection pool exhausted', database="users")
```

You can also pass additional attributes directly to the logging functions via the `attributes` kwarg.

```python
sentry_sdk.logger.error(
    'Payment processing failed',
    attributes={
        'payment.provider': 'stripe',
        'payment.method': 'credit_card',
        'payment.currency': 'USD',
        'user.subscription_tier': 'premium'
    }
)
```

##### Attribute value types

Attribute values should be primitives — strings, numbers, or booleans. Sentry's log storage only retains these scalar types, so other values are handled inconsistently. A `list` or `tuple` of same-typed scalars (for example `[1, 2, 3]`) is sent as an array, which is **not currently stored** and shows up empty in the Logs UI. Mixed lists and `dict`s are stored as their string representation. To keep a complex value searchable, serialize it to a string before logging, for example `json.dumps(workflow_ids)`.

### [Shared Attributes](https://docs.sentry.io/platforms/python/logs.md#shared-attributes)

Use `sentry_sdk.set_attribute` to attach attributes that are automatically included on all logs, metrics, and spans (only in [stream mode](https://docs.sentry.io/platforms/python/tracing/streamed-spans.md)). These write to the isolation scope, so they apply for the current request or session:

```python
import sentry_sdk

sentry_sdk.set_attribute("org_id", user.org_id)
sentry_sdk.set_attribute("user_tier", user.tier)
```

To target a broader or narrower scope instead, see [Attributes](https://docs.sentry.io/platforms/python/enriching-events/attributes.md).

## [Options](https://docs.sentry.io/platforms/python/logs.md#options)

#### [before\_send\_log](https://docs.sentry.io/platforms/python/logs.md#before_send_log)

To filter logs, or update them before they are sent to Sentry, you can use the `before_send_log` option.

```python
import sentry_sdk
from sentry_sdk.types import Log, Hint
from typing import Optional

def before_log(log: Log, _hint: Hint) -> Optional[Log]:
    # Filter out all info level logs
    if log["severity_text"] == "info":
        return None
    return log

sentry_sdk.init(
    dsn="https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
    before_send_log=before_log,
)
```

The `before_send_log` function receives a log object, and should return the log object if you want it to be sent to Sentry, or `None` if you want to discard it.

The log dict has the following keys:

* `severity_text`: (`str` - one of `trace`, `debug`, `info`, `warning`, `error`, `fatal`) The log level.
* `severity_number`: (`int`) The log level as a number ranging from 1 to 24, as per the OpenTelemetry specification of [`SeverityNumber`](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber).
* `body`: (`str`) The log message.
* `attributes`: (`dict[str, str | bool | float | int]`) Additional attributes to be sent with the log.
* `time_unix_nano`: (`int`) The timestamp of the log in nanoseconds since the Unix epoch.
* `trace_id`: (`Optional[str]`) The trace ID of the trace this log belongs to.

## [Best Practices](https://docs.sentry.io/platforms/python/logs.md#best-practices)

### [Wide Events Over Scattered Logs](https://docs.sentry.io/platforms/python/logs.md#wide-events-over-scattered-logs)

Instead of many thin logs that are hard to correlate, emit one comprehensive log per operation with all relevant context.

This makes debugging dramatically faster — one query returns everything about a specific order, user, or request.

```python
# ❌ Scattered thin logs
sentry_sdk.logger.info("Starting checkout")
sentry_sdk.logger.info("Validating cart")
sentry_sdk.logger.info("Processing payment")
sentry_sdk.logger.info("Checkout complete")

# ✅ One wide event with full context
sentry_sdk.logger.info(
    "Checkout completed",
    attributes={
        "order_id": order.id,
        "user_id": user.id,
        "user_tier": user.subscription,
        "cart_value": cart.total,
        "item_count": len(cart.items),
        "payment_method": "stripe",
        "duration_ms": (time.time() - start_time) * 1000,
    }
)
```

### [Include Business Context](https://docs.sentry.io/platforms/python/logs.md#include-business-context)

Add attributes that help you prioritize and debug:

* **User context** — tier, account age, lifetime value
* **Transaction data** — order value, item count
* **Feature state** — active feature flags
* **Request metadata** — endpoint, method, duration

This lets you filter logs by high-value customers or specific features.

```python
sentry_sdk.logger.info(
    "API request completed",
    attributes={
        # User context
        "user_id": user.id,
        "user_tier": user.plan,  # "free" | "pro" | "enterprise"
        "account_age_days": user.age_days,

        # Request data
        "endpoint": "/api/orders",
        "method": "POST",
        "duration_ms": 234,

        # Business context
        "order_value": 149.99,
        # Join lists into a string — array values aren't stored as attributes
        "feature_flags": ",".join(["new-checkout", "discount-v2"]),
    }
)
```

### [Consistent Attribute Naming](https://docs.sentry.io/platforms/python/logs.md#consistent-attribute-naming)

Pick a naming convention and stick with it across your codebase. Inconsistent names make queries impossible.

**Recommended:** Use `snake_case` for custom attributes to match Python conventions.

```python
# ❌ Inconsistent naming
{"user": "123"}
{"userId": "123"}
{"user_id": "123"}
{"UserID": "123"}

# ✅ Consistent snake_case
{
    "user_id": "123",
    "order_id": "456",
    "cart_value": 99.99,
    "item_count": 3,
}
```

## [Default Attributes](https://docs.sentry.io/platforms/python/logs.md#default-attributes)

The Python SDK automatically sets several default attributes on all log entries to provide context and improve debugging:

### [Core Attributes](https://docs.sentry.io/platforms/python/logs.md#core-attributes)

* `environment`: The environment set in the SDK if defined. This is sent from the SDK as `sentry.environment`.
* `release`: The release set in the SDK if defined. This is sent from the SDK as `sentry.release`.
* `sdk.name`: The name of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.name`.
* `sdk.version`: The version of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.version`.

### [Message Template Attributes](https://docs.sentry.io/platforms/python/logs.md#message-template-attributes)

If the log was parameterized, Sentry adds the message template and parameters as log attributes.

* `message.template`: The parameterized template string. This is sent from the SDK as `sentry.message.template`.
* `message.parameter.X`: The parameters to fill the template string. X can either be the number that represent the parameter's position in the template string (`sentry.message.parameter.0`, `sentry.message.parameter.1`, etc) or the parameter's name (`sentry.message.parameter.item_id`, `sentry.message.parameter.user_id`, etc). This is sent from the SDK as `sentry.message.parameter.X`.

### [Server Attributes](https://docs.sentry.io/platforms/python/logs.md#server-attributes)

* `server.address`: The address of the server that sent the log. Equivalent to `server_name` that gets attached to Sentry errors.

### [User Attributes](https://docs.sentry.io/platforms/python/logs.md#user-attributes)

If user information is available in the current scope, the following attributes are added to the log:

* `user.id`: The user ID.
* `user.name`: The username.
* `user.email`: The email address.

### [Integration Attributes](https://docs.sentry.io/platforms/python/logs.md#integration-attributes)

If a log is generated by an SDK integration, the SDK will set additional attributes to help you identify the source of the log.

* `origin`: The origin of the log. This is sent from the SDK as `sentry.origin`.

## [Other Logging Integrations](https://docs.sentry.io/platforms/python/logs.md#other-logging-integrations)

Available integrations:

* [Standard library logging](https://docs.sentry.io/platforms/python/integrations/logging.md)
* [Loguru](https://docs.sentry.io/platforms/python/integrations/loguru.md)

If there's an integration you would like to see, open a [new issue on GitHub](https://github.com/getsentry/sentry-python/issues/new/choose).
