Sentry implements data interfaces for storing structured data. At its core, an interface describes what it’s storing, and optionally how its data should be rendered.

Within the client, interfaces are referenced by their full Python module path. For example, if you were sending data for the sentry.interfaces.Message class, it would look like this in your JSON packet:

    // etc.
    "message": "Hello world"
    "sentry.interfaces.Message": {
        "message": "Hello world"


As of protocol version 4, most built-in interface types are aliases for easier reference. For example, instead of using the key ‘sentry.interfaces.Exception’, you can send the key ‘exception’.

The mapping is as follows:

* 'exception' => 'sentry.interfaces.Exception'
* 'request' => 'sentry.interfaces.Http'
* 'user' => 'sentry.interfaces.User'
* 'stacktrace' => 'sentry.interfaces.Stacktrace'
* 'template' => 'sentry.interfaces.Template'

Provided Interfaces

class sentry.interfaces.Message(message, params=(), **kwargs)[source]

A standard message consisting of a message arg, and an optional params arg for formatting.

If your message cannot be parameterized, then the message interface will serve no benefit.

  • message must be no more than 1000 characters in length.
>>> {
>>>     "message": "My raw message with interpreted strings like %s",
>>>     "params": ["this"]
>>> }
class sentry.interfaces.Exception(*args, **kwargs)[source]

An exception consists of a list of values. In most cases, this list contains a single exception, with an optional stacktrace interface.

Each exception has a mandatory value argument and optional type and module arguments describing the exception class type and module namespace.

You can also optionally bind a stacktrace interface to an exception. The spec is identical to sentry.interfaces.Stacktrace.

>>> [{
>>>     "type": "ValueError",
>>>     "value": "My exception value",
>>>     "module": "__builtins__"
>>>     "stacktrace": {
>>>         # see sentry.interfaces.Stacktrace
>>>     }
>>> }]

Values should be sent oldest to newest, this includes both the stacktrace and the exception itself.


This interface can be passed as the ‘exception’ key in addition to the full interface path.

class sentry.interfaces.Stacktrace(frames, **kwargs)[source]

A stacktrace contains a list of frames, each with various bits (most optional) describing the context of that frame. Frames should be sorted from oldest to newest.

The stacktrace contains an element, frames, which is a list of hashes. Each hash must contain at least the filename attribute. The rest of the values are optional, but recommended.

Additionally, if the list of frames is large, you can explicitly tell the system that you’ve omitted a range of frames. The frames_omitted must be a single tuple two values: start and end. For example, if you only removed the 8th frame, the value would be (8, 9), meaning it started at the 8th frame, and went until the 9th (the number of frames omitted is end-start). The values should be based on a one-index.

The list of frames should be ordered by the oldest call first.

Each frame must contain the following attributes:

The relative filepath to the call


The name of the function being called


Platform-specific module path (e.g. sentry.interfaces.Stacktrace)

The following additional attributes are supported:

The line number of the call
The column number of the call
The absolute path to filename
Source code in filename at lineno
A list of source code lines before context_line (in order) – usually [lineno - 5:lineno]
A list of source code lines after context_line (in order) – usually [lineno + 1:lineno + 5]
Signifies whether this frame is related to the execution of the relevant code in this stacktrace. For example, the frames that might power the framework’s webserver of your app are probably not relevant, however calls to the framework’s library once you start handling code likely are.
A mapping of variables which were available within this frame (usually context-locals).
>>> {
>>>     "frames": [{
>>>         "abs_path": "/real/file/"
>>>         "filename": "file/",
>>>         "function": "myfunction",
>>>         "vars": {
>>>             "key": "value"
>>>         },
>>>         "pre_context": [
>>>             "line1",
>>>             "line2"
>>>         ],
>>>         "context_line": "line3",
>>>         "lineno": 3,
>>>         "in_app": true,
>>>         "post_context": [
>>>             "line4",
>>>             "line5"
>>>         ],
>>>     }],
>>>     "frames_omitted": [13, 56]
>>> }


This interface can be passed as the ‘stacktrace’ key in addition to the full interface path.

class sentry.interfaces.Template(filename, context_line, lineno, pre_context=None, post_context=None, abs_path=None, **kwargs)[source]

A rendered template (generally used like a single frame in a stacktrace).

The attributes filename, context_line, and lineno are required.

>>>  {
>>>     "abs_path": "/real/file/name.html"
>>>     "filename": "file/name.html",
>>>     "pre_context": [
>>>         "line1",
>>>         "line2"
>>>     ],
>>>     "context_line": "line3",
>>>     "lineno": 3,
>>>     "post_context": [
>>>         "line4",
>>>         "line5"
>>>     ],
>>> }


This interface can be passed as the ‘template’ key in addition to the full interface path.

class sentry.interfaces.Http(url, method=None, data=None, query_string=None, cookies=None, headers=None, env=None, **kwargs)[source]

The Request information is stored in the Http interface. Two arguments are required: url and method.

The env variable is a compounded dictionary of HTTP headers as well as environment information passed from the webserver. Sentry will explicitly look for REMOTE_ADDR in env for things which require an IP address.

The data variable should only contain the request body (not the query string). It can either be a dictionary (for standard HTTP requests) or a raw request body.

>>>  {
>>>     "url": "http://absolute.uri/foo",
>>>     "method": "POST",
>>>     "data": {
>>>         "foo": "bar"
>>>     },
>>>     "query_string": "hello=world",
>>>     "cookies": "foo=bar",
>>>     "headers": {
>>>         "Content-Type": "text/html"
>>>     },
>>>     "env": {
>>>         "REMOTE_ADDR": ""
>>>     }
>>>  }


This interface can be passed as the ‘request’ key in addition to the full interface path.

class sentry.interfaces.User(id=None, email=None, username=None, ip_address=None, **kwargs)[source]

An interface which describes the authenticated User for a request.

You should provide at least either an id (a unique identifier for an authenticated user) or ip_address (their IP address).

All other data is.

>>> {
>>>     "id": "unique_id",
>>>     "username": "my_user",
>>>     "email": ""
>>>     "ip_address": ""
>>> }
class sentry.interfaces.Query(query, engine=None, **kwargs)[source]

A SQL query with an optional string describing the SQL driver, engine.

>>> {
>>>     "query": "SELECT 1"
>>>     "engine": "psycopg2"
>>> }

Table Of Contents

Related Topics

This Page