0
# Raven
1
2
Raven is the official legacy Python client for Sentry, providing comprehensive error tracking and exception monitoring for Python applications. It automatically captures and reports unhandled exceptions, supports extensive framework integrations, and provides detailed diagnostic information for debugging and monitoring production applications.
3
4
## Package Information
5
6
- **Package Name**: raven
7
- **Language**: Python
8
- **Installation**: `pip install raven`
9
- **Python Versions**: 2.6–2.7 & 3.3–3.7, PyPy, Google App Engine
10
11
## Core Imports
12
13
```python
14
from raven import Client
15
```
16
17
Common imports for specific integrations:
18
19
```python
20
from raven.conf import setup_logging
21
from raven.handlers.logging import SentryHandler
22
from raven.contrib.django.client import DjangoClient
23
from raven.contrib.flask import Sentry
24
```
25
26
## Basic Usage
27
28
```python
29
from raven import Client
30
31
# Initialize client with your Sentry DSN
32
client = Client('https://public_key:secret_key@sentry.io/project_id')
33
34
# Capture an exception
35
try:
36
1/0
37
except ZeroDivisionError:
38
client.captureException()
39
40
# Capture a message
41
client.captureMessage('Something went wrong!')
42
43
# Add context information
44
client.user_context({'id': 123, 'email': 'user@example.com'})
45
client.tags_context({'version': '1.0', 'environment': 'production'})
46
client.extra_context({'request_id': 'abc123'})
47
48
# Capture with context
49
try:
50
process_payment()
51
except Exception:
52
client.captureException()
53
```
54
55
## Architecture
56
57
Raven uses a modular architecture with several key components:
58
59
- **Client**: Core class managing event capture, processing, and transmission
60
- **Transport Layer**: Handles HTTP communication with Sentry servers (sync/async)
61
- **Event Processing**: Captures different event types (exceptions, messages, queries)
62
- **Data Processing**: Sanitizes and transforms data before transmission
63
- **Context Management**: Thread-local storage for user data, tags, and breadcrumbs
64
- **Framework Integrations**: Drop-in support for Django, Flask, and other frameworks
65
66
## Capabilities
67
68
### Core Client
69
70
The main Client class provides the primary interface for capturing and sending events to Sentry, with comprehensive configuration options and context management.
71
72
```python { .api }
73
class Client:
74
def __init__(self, dsn=None, raise_send_errors=False, transport=None,
75
install_sys_hook=True, install_logging_hook=True,
76
hook_libraries=None, enable_breadcrumbs=True,
77
_random_seed=None, **options): ...
78
def captureException(self, exc_info=None, **kwargs): ...
79
def captureMessage(self, message, **kwargs): ...
80
def captureQuery(self, query, params=(), engine=None, **kwargs): ...
81
def captureBreadcrumb(self, **kwargs): ...
82
```
83
84
[Core Client](./core-client.md)
85
86
### Framework Integrations
87
88
Comprehensive integrations with popular Python web frameworks including Django, Flask, Bottle, Celery, and others, providing automatic error capture and framework-specific context.
89
90
```python { .api }
91
# Django
92
class DjangoClient(Client): ...
93
94
# Flask
95
class Sentry:
96
def __init__(self, app=None, **kwargs): ...
97
def init_app(self, app, **kwargs): ...
98
```
99
100
[Framework Integrations](./framework-integrations.md)
101
102
### Logging Integration
103
104
Native Python logging integration with configurable handlers that automatically capture log records as Sentry events, supporting filtering and custom formatting.
105
106
```python { .api }
107
class SentryHandler(logging.Handler):
108
def __init__(self, client=None, **kwargs): ...
109
def emit(self, record): ...
110
111
def setup_logging(handler, exclude=None): ...
112
```
113
114
[Logging Integration](./logging-integration.md)
115
116
### Transport Layer
117
118
Multiple transport implementations for different environments and performance requirements, including synchronous, threaded, and async framework-specific transports.
119
120
```python { .api }
121
class HTTPTransport: ...
122
class ThreadedHTTPTransport: ...
123
class RequestsHTTPTransport: ...
124
class ThreadedRequestsHTTPTransport: ...
125
class GeventedHTTPTransport: ...
126
class TwistedHTTPTransport: ...
127
class TornadoHTTPTransport: ...
128
class EventletHTTPTransport: ...
129
```
130
131
[Transport Layer](./transport-layer.md)
132
133
### Data Processing
134
135
Customizable data processors for sanitizing sensitive information, transforming data structures, and controlling what information is sent to Sentry.
136
137
```python { .api }
138
class SanitizePasswordsProcessor: ...
139
class SanitizeKeysProcessor: ...
140
class RemovePostDataProcessor: ...
141
class RemoveStackLocalsProcessor: ...
142
```
143
144
[Data Processing](./data-processing.md)
145
146
### Context Management
147
148
Thread-local context management for maintaining user information, tags, extra data, and breadcrumbs throughout the application lifecycle.
149
150
```python { .api }
151
class Context:
152
def activate(self, sticky=False): ...
153
def merge(self, data, activate=True): ...
154
def clear(self, deactivate=None): ...
155
```
156
157
[Context Management](./context-management.md)
158
159
### Breadcrumb System
160
161
Automatic and manual breadcrumb collection for tracking user actions and application state leading up to errors, with customizable recording and filtering.
162
163
```python { .api }
164
class BreadcrumbBuffer:
165
def record(self, timestamp=None, level=None, message=None, **kwargs): ...
166
def clear(self): ...
167
168
def record(**kwargs): ...
169
def install_logging_hook(): ...
170
```
171
172
[Breadcrumb System](./breadcrumb-system.md)
173
174
## Types
175
176
```python { .api }
177
class ClientState:
178
ONLINE = 1
179
ERROR = 0
180
181
def should_try(self): ...
182
183
class DummyClient(Client):
184
"""No-op client that discards all messages"""
185
def send(self, **kwargs): ...
186
```