Debugging Python Errors

One of Sentry’s more powerful features comes with languages like Python. In Python, PHP, and the JVM, we’re able to introspect more deeply into the runtime and give you additional data about each frame in your call stack. At a high level, this lets you know things like calling arguments to your functions, allowing you to more easily reproduce and understand an error. Let’s dive into what this looks like, and how it works under the hood.

We’ll start with what a Python error might typically look like in your terminal, or in a standard logging system:

TypeError: expected string or buffer
  File "sentry/", line 309, in process_single_stacktrace
    processable_frame, processing_task)
  File "sentry/lang/native/", line 196, in process_frame
    in_app = (in_app and not self.sym.is_internal_function(raw_frame.get('function')))
  File "sentry/lang/native/", line 278, in is_internal_function
    return is not None

While this gives us an idea of the type and location of the error, it unfortunately doesn’t help us understand what is truly causing it. It’s possible that it’s passing an integer or a NoneType, but, realistically, it could be any number of things. Guessing at it will only get us so far, and we really need to know what function actually is.

An easy and often very accessible option to do this would be to add some logging. There’s a few different entry points where we could put logging, which makes it easier to implement. It also lets us ensure we specifically get the answer we want. For example, we want to figure out what the type of function is:

import logging
# ...
logging.debug("function is of type %s", type(function))

Another benefit of logging like this is that it could carry over to production. The consequence is generally you’re not recording DEBUG level log statements in production as the volume can be significant and not very useful. It also often requires you to plan ahead to ensure you’re logging the various failure cases that could happen and the appropriate context with each.

For the sake of this tutorial, let’s assume we can’t do this in production, didn’t plan ahead for it, and, instead, are trying to debug and reproduce this in development.

The Python Debugger

The Python Debugger (PDB) is a tool that allows you to step through your callstack using breakpoints. The tool itself is inspired by GNU’s Debugger (GDB) and, while powerful, often can be overwhelming if you’re not familiar with it. It’s definitely an experience that will get easier with repetition, and we’re only going to go into a few high level concepts with it for our example.

So the first thing we’d want to do is instrument our code to add a breakpoint. In our example above, we could actually instrument ourselves. That’s not always the case, as sometimes the exception happens in third party code. No matter where you instrument it, you’ll still be able to jump up and down the stack. Let’s start by changing that code:

def is_internal_function(self, function):
    # add a breakpoint for PDB
        return is not None
    except Exception:
        import pdb; pdb.set_trace()

We’re limiting this to the exception, as it’s common you’ll have code that runs successfully most of the time, sometimes in a loop, and you wouldn’t want to pause execution on every single iteration.

Once we’ve hit this breakpoint (which is what set_trace() is registering), we’ll be dropped into a special shell-like environment:

# ...

This is the PDB console, and it works similar to the Python shell. In addition to being able to run most Python code, we’re also executing under a specific context within our call stack. That location is the entry point. Rather, it’s where you called set_trace(). In the above example, we’re right where we need to be, so we can easily grab the type of function:

(Pdb) type(function)
<type 'NoneType'>

Of course, we could also simply grab all locally scoped variables using one of Python’s builtins:

(Pdb) locals()
{..., 'function': None, ...}

In some cases we may have to navigate up and down the stack to get to the frame where the function is executing. For example, if our set_trace() instrumentation had dropped us higher up in the stack, potentially at the top frame, we would use down to jump into the inner frames until we hit a location that had the information needed:

(Pdb) down
-> in_app = (in_app and not self.sym.is_internal_function(raw_frame.get('function')))
(Pdb) down
-> return is not None
(Pdb) type(function)
<type 'NoneType'>

So we’ve identified the problem: function is a NoneType. While that doesn’t really tell us why it’s that way, it at least gives us valuable information to speed up our test cases.

Debugging in Production

So PDB works great in development, but what about production? Let’s look a bit more deeply at what Python gives us to answer that question.

The great thing about the CPython runtime — that’s the standard runtime most people use — is it allows easy access to the current call stack. While some other runtimes (like PyPy) will provide similar information, it’s not guaranteed. When you hit an exception the stack is exposed via sys.exc_info(). Let’s look at what that gives us for a typical exception:

>>> try:
...   1 / 0
... except:
...   import sys; sys.exc_info()
(<type 'exceptions.ZeroDivisionError'>,
    ZeroDivisionError('integer division or modulo by zero',),
    <traceback object at 0x105da1a28>)

We’re going to avoid going too deep into this, but we’ve got a tuple of three pieces of information: the class of the exception, the actual instance of the exception, and a traceback object. The bit we care about here is the traceback object. Of note, you can also grab this information outside of exceptions using the traceback module. There’s some documentation on using these structures, but let’s just dive in ourselves to try and understand them. Within the traceback object we’ve got a bunch of information available to us, though it’s going to take a bit of work — and magic — to access:

>>> exc_type, exc_value, tb = exc_info
>>> tb.tb_frame
<frame object at 0x105dc0e10>

Once we’ve got a frame, CPython exposes ways to get stack locals — that is all scoped variables to that executing frame. For example, look at the following code:

def foo(bar=None):
    foo = "bar"
    1 / 0

Let’s generate an exception with that code:

    exc_type, exc_value, tb = sys.exc_info()

And finally, let’s access the locals via f_locals on the <frame> object:

>>> from pprint import pprint
>>> pprint(tb.tb_frame.f_locals)
{'__builtins__': <module '__builtin__' (built-in)>,
    '__doc__': None,
    '__name__': '__main__',
    '__package__': None,
    'exc_info': (<type 'exceptions.ZeroDivisionError'>,
                ZeroDivisionError('integer division or modulo by zero',),
                <traceback object at 0x105cd4fc8>),
    'foo': <function foo at 0x105cf50c8>,
    'history': '/Users/dcramer/.pythonhist',
    'os': <module 'os' from 'lib/python2.7/'>,
    'pprint': <function pprint at 0x105cf52a8>,
    'print_function': _Feature((2, 6, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 65536),
    'readline': <module 'readline' from 'lib/python2.7/lib-dynload/'>,
    'stack': [],
    'sys': <module 'sys' (built-in)>,
    'tb': <traceback object at 0x105da1a28>,
    'tb_next': None,
    'write_history': <function write_history at 0x105cf2c80>}

What we see above isn’t actually that useful. The reason being is that we’re one level up in our scope, so we’re seeing foo defined, but nothing actually relevant to the function call itself. This won’t always be true, but in our trivial example it is. To find the information we’re looking for, we’ll need to go one level deeper:

>>> inner_frame = tb.tb_next.tb_frame
>>> pprint(inner_frame.f_locals)
{'bar': None, 'foo': 'bar'}

You can quickly understand how this might be useful when we go back to our original TypeError. In that case, with the above introspection, we find out that function, which is expected to be a string, is actually set to a NoneType. We know that because Sentry has captured this error for us, and automatically extracts stack locals for every frame:

This was one of the first features we built in Sentry and, to this day, it remains as one of the most valuable debugging components we can provide. While we’re not able to always give you the details needed to reproduce an exception, in our experience it’s very rare that we actually need to manually instrument something to understand the context and, ultimately, resolve the issue.

If you’re curious about the full implementation, which also utilizes other various components form Python’s traceback structure, you can always take a look at our Python SDK’s source code on GitHub. In PHP and the JVM, the approach is slightly different due to the runtimes and, if you’re interested, you’ll also find those repositories on Sentry’s GitHub. If you’re using Sentry, we’ll generally automatically instrument things for you, though the JVM requires a little bit of configuration (docs coming soon).

Introducing Forge

Our core belief at Sentry centers around being able to ship software more quickly. Not only is it something we practice, but it’s the reason we believe in our product so much. But helping developers quickly recover from mistakes is just a small part of the global shift towards more observability, agility, and user-focus. We’re ultimately working alongside myriad other tools to ensure teams can rapidly and effectively iterate on product. Forge is our way of bringing together more people who care about this mission.

We’re organizing a 2-day event this fall, October 29–31, in beautiful Napa Valley (just north of San Francisco). We’ve invited a number of great speakers who are solving real problems and moving our industry forward. And you won’t have to worry about picking which talks to attend — a single track of technical content will range from observability and microservices to automation and continuous deployment.

Forge is the first event of its kind: for software people, by software people, about the future of building and using software. We’re expecting approximately 200 attendees and, given the demand, we’re asking people to register their interest before we open up ticket sales. This helps us ensure diversity is a core value of the conference and plan according to demand. If Forge sounds like the event for you, make sure you register early!

We’ll be sharing more details over the coming weeks, including the full speaker list, evening events, sponsors, and other news related news to Forge. As a sneak peek into the content, we’re proud to announce the first round of confirmed speakers: Alex Sexton and Kiran Bhattaram from Stripe, Dan McKinley from MailChimp, Christine Yen from Honeycomb, Ben Sigelman from LightStep, and Guillermo Rauch from Zeit.

Does Forge sound like the event for you?

Register now

Notice of (Internet) Address Change

As part of continuing projects to increase the reliability of, the IP addresses associated with the service will be changing soon. These changes may require customer-side updates to firewall rules to continue uninterrupted service.

Specifically, firewall rules that restrict traffic based on IP addresses will have to be changed for the following circumstances:

  • Firewalls between an application monitored by Sentry and the Sentry service (
  • Firewalls between Sentry’s service and:
    • web servers or CDNs that serve JavaScript source and/or source map files
    • servers configured to receive webhook HTTP requests

If neither of these apply, no changes are needed. We hope you continue to use and enjoy Sentry!

We plan to migrate all traffic to the addresses below, starting on June 21, 2017.

Inbound Address


When a Sentry client SDK transmits errors to, DNS will return the above IP address alongside the existing service addresses. If you have previously configured network rules between your application servers and the Internet to limit outbound requests, those rules will need to be updated to add this new address.

Outbound Addresses


When configured by customers, also sends web requests to its customers’ servers. The most frequent requests Sentry makes are to fetch JavaScript source files and source maps, but we also connect using webhooks and other integrations. If you have configured network rules that only allow inbound requests from specific addresses, you will need to update those rules to include the additional addresses.

Alternative Methods of Authentication

In order to alleviate some of the pains caused with updating these addresses, Sentry provides the ability to append a token to our outbound request headers. You may configure this token by going to your Project Settings, and scrolling down to “Security Token” where you’ll find the following form:

By default, all outbound requests are appended with the X-Sentry-Token header using the security token as the value. This token can be verified by a webserver or a proxy, denying all traffic that does not match. Here’s an example for using nginx to deny unauthorized requests:

    map $http_x_sentry_token $from_sentry {
      f48e8f0eb1c911e493090025902d9efc 1;
      default 0;

    location / {
      if ($from_sentry = '0') { return 403; }

Note that both the header name and token value can be configured to suit your preferences.

Moving forward, we strongly encourage your organization to use this authentication method instead of IP whitelisting.

Welcome James Andrews

Join us in welcoming James Andrews (weeeee our first intern) to the team!

James will be joining us this summer to work with the operations team on Freight, a service that supercharges our deploy process. He is currently a computer science student at San Francisco State University. Before coming to Sentry, James worked as a customer support engineer at Bootstrap Themes. He’s a professional milly rocker. When he’s not blasting “Magnolia” by Playboi Carti in the office, you can probably find him at your local Philz Coffee planning his next move.

New and Improved Java SDK Released

Today we’re announcing the first release of the new and improved Java SDK, sentry-java. This is a major refactoring (and renaming) of the previous Java client, raven-java, which aims to add first class support for features like breadcrumbs and integrations other than logging frameworks, such as Android applications.


The original Java SDK, raven-java, started as a log4j appender that sent error level logs and exceptions to Sentry. From there it was expanded to work with other logging frameworks, but using many of the features outside of a logging framework was either a pain or completely impossible. In addition, the appenders are lazily initialized and so features that need a working Sentry client before an event was sent, such as breadcrumbs, were impossible to use even when combined with a logging framework.

What’s New

The new Java SDK takes a wholly different approach that focuses on a simple and re-usable Java client that just happens to also be used to implement the logging integrations. For example, add sentry-java to your dependency manager of choice (note that the group name and artifact have changed):


Then use it directly from Java:

    import io.sentry.Sentry;
    public class Application {
        public static void main(String[] args) {
            // init manually with a DSN, this can be provided in a number of
            // other ways, check the docs!
            Sentry.init("your dsn");
            // record a breadcrumb
            Sentry.record(new BreadcrumbBuilder().setMessage("User made an action!").build());

            // set the current user
            Sentry.setUser(new UserBuilder().setEmail("").build());
            try {
            } catch (Exception e) {
                // send an event to Sentry

This example is using a new static API where you don’t have to manage your own client instance. What’s nice is that the logging integrations use the exact same system, so you can set breadcrumbs or the current user and those will be correctly propagated when you log an error.

Note that there are many ways to configure your DSN and other options. Passing the DSN in directly is the least flexible choice and should be a last resort in most cases. See the new documentation for more information on the different configuration methods that are available. Note that configuration of logging integrations has changed – check the docs for your logging framework of choice!


One major benefit of having a plain Java client is that sentry-java works great on Android. If you use the provided AndroidSentryClientFactory and pass in your application’s context, the SDK will automatically attach all kinds of useful information to your events such as device name, battery level, OS version, screen resolution, network connectivity, and more.

For example, in your app/build.gradle:

    compile 'io.sentry:sentry-android:1.0.0'

And then in your main activity class:

    import io.sentry.Sentry;
    public class MainActivity extends Activity {
        public void onCreate(Bundle savedInstanceState) {
            Context ctx = this.getApplicationContext();
            Sentry.init("your dsn", new AndroidSentryClientFactory(ctx));
            try {
            } catch (Exception e) {
                // send an event to Sentry

After the initialization above, Sentry will automatically catch unhandled exceptions, and will even cache them to disk for sending later if the user’s network is disabled. See the Android documentation for more information.

The new SDK is also used by our React Native integration on Android for crashes that occur in Java code.

Learn More

Take a look at the sentry-java project on GitHub to learn more about how things are implemented, and see the documentation for details on using it with Sentry.

If you’re not yet a Sentry user, you can try Sentry for free. If that’s not your cup of tea, it’s all open source on GitHub.