record_exception

For general information on how the Python agent API calls relate to each other, see the API guide.

newrelic.agent.record_exception(exc=None, value=None, tb=None, params={}, ignore_errors=[], application=None)
Records details of a Python exception as an error.

Description

By default, the Python agent only reports unhandled exceptions. Use record_exception to record any Python exception as an error, which can then be found in New Relic APM and in Insights. If no parameters are provided, the details of the exception currently being handled will be used.

You can record up to five distinct exceptions per transaction, and up to 20 total exceptions across all transactions per harvest cycle.

When record_exception() is called within the context of a monitored web request or background task, the details of the exception will be reported against the application that the request or task is being reported to.

If called outside of the context of a monitored web request or background task, the call will be ignored unless the application keyword argument is provided and an application object corresponding to the application against which the exception should be recorded is provided. A suitable application object can be obtained using the newrelic.agent.application() function.

Parameters

In almost all cases, record_exception will require no parameters.

Parameter Description

exc

class object

Optional and rarely used. The exception type of the exception being handled (a class object). One of three values (exc, value, and tb) returned from sys.exc_info(). If you want to pass any of these parameters, all three must be set and and cannot be set to None. If you only pass one of these values, the call will not work.

value

int, string, other

Optional and rarely used. The exception parameter. One of three values (exc, value, and tb) returned from sys.exc_info(). If you want to pass any of these parameters, all three must be set and and cannot be set to None. If you only pass one of these values, the call will not work.

tb

object

Optional and rarely used. A traceback object that encapsulates the call stack at the point where the exception originally occurred. One of three values (exc, value, and tb) returned from sys.exc_info(). If you want to pass any of these parameters, all three must be set and and cannot be set to None. If you only pass one of these values, the call will not work.

params

dict

Optional. Custom attributes to add to the error event (in addition to any custom attributes already added to the transaction). If high security mode is enabled, this will not work.

ignore_errors

string

Optional. Errors to ignore can be passed in the form module:class. Useful when certain types of exceptions should always be ignored and never recorded.

application

application object

Optional. If called outside of the context of a monitored web request or background task, the call will be ignored unless the application object is provided.

Return value(s)

None.

Example(s)

Simple example of reporting exceptions

In large majority of cases, you won't need to pass any paramters. You would just call the following where you want to report an exception:

newrelic.agent.record_exception()

Call with sys.exc_info() tuple and additional parameters

An example of record_exception using sys.exc_info() data:

def complex_ignore_errors(exc, val, tb):
   # do some logic here
   return False

newrelic.agent.record_exception(params={'my_special_exception': True}, ignore_errors=complex_ignore_errors)

Example using callback

If you need to filter exceptions dynamically based on the attributes of a specific exception type, you can supply a callback function:

def _ignore_errors(exc, value, tb): 
    if instance(value, HTTPError): 
        if value.status == 404: 
            return True

newrelic.agent.record_exception(ignore_errors=_ignore_errors) 

If the exception is to be ignored, set the return value for the callable to True. Return False if the exception should never be ignored regardless of any other checks, and None if subsequent checks and inbuilt rules should determine if the exception should be ignored. A callback would normally return either True or None.

For more help

Recommendations for learning more: