Guide to using the Python agent API

The New Relic Python agent API allows you to customize and extend your APM monitoring. Use the Python agent API to:

  • Manually instrument an unsupported framework or third-party system.
  • Add instrumentation to supplement New Relic's default monitoring.

This document describes some of the available Python API calls. For a description of all available New Relic APIs, see Introduction to APIs.

Custom instrumentation or API

If your goal is custom instrumentation, consider using the configuration file method, which allows you to add functions and class methods to the config file that will be auto-instrumented by New Relic. The benefit of the config-file method is that it does not require you to change your application code.

However, the Python agent API is much more powerful and is best for setting up more complex and tailored instrumentation. To ensure you have access to the full API functionality, update to the latest Python agent.

Monitor transactions and segments

The New Relic Python agent is compatible with most of the common WSGI web frameworks. If the agent supports your framework, web requests automatically will be captured as transactions and displayed in the New Relic UI. A transaction can also have function-level segments that are captured as part of a transaction trace.

Use these methods to monitor web transactions, non-web transactions, and transaction segments:

If you want to... Do this...

Monitor WSGI web transactions

The Python agent automatically captures web transactions for supported frameworks. If you do not have a supported framework, you can use the wsgi_application function to monitor your WSGI entry point.

Monitor non-web transactions

The Python agent classifies non-web transactions as background tasks. To capture non-web transactions, use background_task.

Capture more details about a transaction

If your transaction traces do not have the level of detail you want:

Ignore a transaction

Use any of these options:

Add and edit transaction metadata

Sometimes the code you target is visible in the New Relic UI, but some details of the method are not useful. For example:

Use these calls when you want to change the metadata of an existing transaction:

If you want to... Do this...

Get reference to current transaction

To return an object representing the current transaction, use current_transaction. This is required by some other Python agent API calls.

Change the name of a transaction

Use set_transaction_name.

Add metadata (such as a customer's subscription level) to transactions

Add custom attributes to your transactions using add_custom_parameter, or use other API calls to report custom data.

Mark a transaction as a background job

To convert a web transaction into a background task so that it appears as a non-web transaction in the UI, use set_background_task.

Prevent a transaction from affecting your Apdex score

Use suppress_apdex_metric.

Report custom events and custom metric data

New Relic receives data in two primary forms:

  • Metric data measures numeric, time-based values; for example, connections per minute.
  • Event data captures discrete event information. Events have key-value attributes attached to them. You can analyze and query event data in New Relic Insights.

Use these methods to create new event data and new metric data:

If you want to... Do this...

Send data about an event for use in New Relic Insights

Use record_custom_event.

Report time-based metrics on application performance

Report an exception as an error in the New Relic UI

By default, the Python agent only reports unhandled exceptions. To report a Python exception as an error, use record_exception.

Report query string parameters

For security reasons, query string parameters associated with web transactions are disabled by default. Use capture_request_params to enable them.

Tag events with metadata

To add attributes to events for more detailed analysis in Insights or error analytics, use add_custom_parameter.

Generate metrics from data sources and data factories

To generate metrics with a pull-style API rather than the push-style API implemented by record_custom_metric(), use these API calls:

Message-related calls

These API calls allow you to collect performance data on your message-passing architecture or service; for example, RabbitMQ. To use these calls, make sure you have New Relic Python agent version 2.88.0.72 or higher.

If you want to... Do this...

Report messages as a New Relic transaction

Use message_transaction.

Report message details as transaction trace segments

Use message_trace.

Implement distributed tracing

These APIs require distributed tracing to be enabled.

New Relic-monitored services and applications will automatically pass distributed tracing context to each other when using a supported framework. When not using a supported framework, you will need to use the distributed tracing APIs to manually accept this context.

Supported web frameworks (for example, Flask, Django, Tornado) will automatically call accept_distributed_trace_payload when creating a transaction. Supported external web services libraries will automatically call create_distributed_trace_payload before making an external HTTP call.

For general instructions on how to use the calls below to implement distributed tracing, see Use distributed tracing APIs.

If you want to... Do this...

Create a payload to be sent to a called service.

Use create_distributed_trace_payload.

Accept a payload sent from the first service; this will link these services together in a trace

Use accept_distributed_trace_payload.

Agent configuration, initialization, shutdown

These calls help you manage Python agent behavior, such as initializing and integrating the agent, and referencing or changing configuration settings:

If you want to... Do this...

Initialize the agent

To initialize the Python agent with a specific configuration file as part of advanced integration process, use initialize.

Get a reference to the application object

The application object represents a New Relic-monitored application and is used by some Python agent API calls.

Get a reference to configuration settings

To control the Python agent's behavior, you can use configuration settings.

Shut down the agent

To forcibly shut down the agent instead of allowing it to make the standard final attempt to upload data, use shutdown_agent.

Control the New Relic Browser agent

You can install New Relic Browser by automatically adding it to your pages or by deploying it on specific pages by copying and pasting the Browser JavaScript snippet. You can also control the New Relic Browser agent by using APM agent API calls. For more information, see New Relic Browser and the Python agent.

If you want to... Do this...

Monitor specific page views

To inject the Browser header and footer JavaScript snippets into views you want to monitor, use both get_browser_timing_header and get_browser_timing_footer.

Disable monitoring of specific page views

To disable Browser monitoring for specific page views, use disable_browser_autorum.

For more help

Recommendations for learning more: