---
title: "Advanced Usage"
url: https://docs.sentry.io/platforms/python/legacy-sdk/advanced/
---

# Advanced Usage | Sentry for Python

##### Deprecation Warning

A new Python SDK has superseded this deprecated version. Sentry preserves this documentation for customers using the old client. We recommend using the [updated Python SDK](https://docs.sentry.io/platforms/python.md) for new projects.

This covers some advanced usage scenarios for raven Python.

## [Alternative Installations](https://docs.sentry.io/platforms/python/legacy-sdk/advanced.md#alternative-installations)

If you want to use the latest git version you can get it from [the GitHub repository](https://github.com/getsentry/raven-python):

```bash
git clone https://github.com/getsentry/raven-python
pip install raven-python
```

Certain additional features can be installed by defining the feature when `pip` installing it. For instance to install all dependencies needed to use the Flask integration, you can depend on `raven[flask]`:

```bash
pip install raven[flask]
```

For more information refer to the individual integration documentation.

## [Configuring the Client](https://docs.sentry.io/platforms/python/legacy-sdk/advanced.md#configuring-the-client)

Settings are specified as part of the initialization of the client. The client is a class that can be instantiated with a specific configuration and all reporting can then happen from the instance of that object. Typically an instance is created somewhere globally and then imported as necessary.

```python
from raven import Client

# Read configuration from the ``SENTRY_DSN`` environment variable
client = Client()

# Manually specify a DSN
client = Client('___DSN___')
```

A reasonably configured client should generally include a few additional settings:

```python
import os
import raven

client = raven.Client(
    dsn='___DSN___',

    # inform the client which parts of code are yours
    # include_paths=['my.app']
    include_paths=[__name__.split('.', 1)[0]],

    # pass along the version of your application
    # release='my-project-name@2.3.12'
    # release=raven.fetch_package_version('my-app')
    release=raven.fetch_git_sha(os.path.dirname(__file__)),
)
```

*(New in version 5.2.0: The `fetch_package_version` and `fetch_git_sha` helpers.)*

## [Client Arguments](https://docs.sentry.io/platforms/python/legacy-sdk/advanced.md#client-arguments)

The following are valid arguments which may be passed to the Raven client:

`dsn`

A Sentry compatible DSN as mentioned before:

```python
dsn = '___DSN___'
```

`transport`

The HTTP transport class to use. By default this is an asynchronous worker thread that runs in-process.

For more information see [*Transports*](https://docs.sentry.io/platforms/python/legacy-sdk/transports.md).

`site`

An optional, arbitrary string to identify this client installation:

```python
site = 'my site name'
```

`name`

This will override the `server_name` value for this installation. Defaults to `socket.gethostname()`:

```python
name = 'sentry_rocks_' + socket.gethostname()
```

`release`

The version of your application. This will map up into a Release in Sentry:

```python
release = '1.0.3'
```

`environment`

The environment your application is running in:

```python
environment = 'staging'
```

`tags`

Default tags to send with events:

```python
tags = {'site': 'foo.com'}
```

`exclude_paths`

Extending this allow you to ignore module prefixes when we attempt to discover which function an error comes from (typically a view):

```python
exclude_paths = [
    'django',
    'sentry',
    'raven',
    'lxml.objectify',
]
```

`include_paths`

For example, in Django this defaults to your list of `INSTALLED_APPS`, and is used for drilling down where an exception is located:

```python
include_paths = [
    'django',
    'sentry',
    'raven',
    'lxml.objectify',
]
```

`ignore_exceptions`

A list of exceptions to ignore:

```python
ignore_exceptions = [
    'Http404',
    'django.exceptions.http.Http404',
    'django.exceptions.*',
    ValueError,
]
```

Each item can be either a string or a class. String declaration is strict (ie. does not work for child exceptions) whereas class declaration handle inheritance (ie. child exceptions are also ignored).

`sample_rate`

The sampling factor to apply to events. A value of 0.00 will deny sending any events, and a value of 1.00 will send 100% of events.

```python
# send 50% of events
sample_rate = 0.5
```

`list_max_length`

The maximum number of items a list-like container should store.

If an iterable is longer than the specified length, the left-most elements up to length will be kept. This affects sets as well, which are unordered.

```python
list_max_length = 50
```

`string_max_length`

The maximum characters of a string that should be stored.

If a string is longer than the given length, it will be truncated down to the specified size:

```python
string_max_length = 200
```

`auto_log_stacks`

Should Raven automatically log frame stacks (including locals) for all calls as it would for exceptions:

```python
auto_log_stacks = True
```

`processors`

A list of processors to apply to events before sending them to the Sentry server. Useful for sending additional global state data or sanitizing data that you want to keep off of the server:

```python
processors = (
    'raven.processors.SanitizePasswordsProcessor',
)
```

`sanitize_keys`

A required set of keys to sanitize when using `raven.processors.SanitizeKeysProcessor` in `processors`:

```python
sanitize_keys = ["sensitive_key_1", "sensitive_key_2"]
```

## [Sanitizing Data](https://docs.sentry.io/platforms/python/legacy-sdk/advanced.md#sanitizing-data)

Several processors are included with Raven to assist in data sanitization. These are configured with the `processors` value.

`raven.processors.SanitizePasswordsProcessor`

Removes all keys which resemble `password`, `secret`, or `api_key` within stack trace contexts, HTTP bits (such as cookies, POST data, the querystring, and environment), and extra data.

`raven.processors.RemoveStackLocalsProcessor`

Removes all stack trace context variables. This will cripple the functionality of Sentry, as you’ll only get raw tracebacks, but it will ensure no local scoped information is available to the server.

`raven.processors.RemovePostDataProcessor`

Removes the `body` of all HTTP data.

`raven.processors.SanitizeKeysProcessor`

Removes all keys provided in the configurable set `sanitize_keys`, which must be provided as a client argument.

## [Custom Grouping Behavior](https://docs.sentry.io/platforms/python/legacy-sdk/advanced.md#custom-grouping-behavior)

In some cases you may see issues where Sentry groups multiple events together when they should be separate entities. In other cases, Sentry simply doesn’t group events together because they’re so sporadic that they never look the same.

Both of these problems can be addressed by specifying the `fingerprint` attribute.

For example, if you have HTTP 404 (page not found) errors, and you’d prefer they deduplicate by taking into account the URL:

```python
client.captureException(fingerprint=['{{ default }}', 'http://my-url/'])
```

For more information, see [Customize Grouping with Fingerprints](https://docs.sentry.io/concepts/data-management/event-grouping.md).

## [Sampling Messages](https://docs.sentry.io/platforms/python/legacy-sdk/advanced.md#sampling-messages)

There are two ways to sample messages:

* Add sample\_rate to the Client object - This sends a percentage of messages the reaching the Client to Sentry

```python
client = Client('___DSN___', sample_rate=0.5) # send 50% of events
```

* Sample individual messages

```python
client = Client('___DSN___') # No sample_rate provided

try:
    1 / 0
except ZeroDivisionError:
    client.captureException(sample_rate=0.5) # Send 50% of this event
```

Alternatively, if you have SentryHandler configured in your logging stack, you can send `sample_rate` in the `extra` kwarg in each log like this

```python
some_logger.warning('foo', extra={'sample_rate': 0.5}) # Send 50% of this event
```

## [A Note on uWSGI](https://docs.sentry.io/platforms/python/legacy-sdk/advanced.md#a-note-on-uwsgi)

If you’re using uWSGI you will need to add `enable-threads` to the default invocation, or you will need to switch off of the threaded default transport.