Guide to using the Python agent API

New Relic for Python provides an API for customizing and extending your New Relic monitoring. You can use the Python agent API to:

  • Manually instrument an unsupported framework or third-party system
  • Add instrumentation to supplement New Relic's default, out-of-the-box monitoring

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 doesn't require you to change your application code. The API, though, 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.

Overview of types of calls

Here is an overview of the types of API calls available:

To see a list of all available calls, see All Python agent API calls.

Monitor transactions and segments

The New Relic Python agent supports most of the common WSGI web frameworks (for a list, see Python agent compatibility and requirements). If your framework is supported, web requests will automatically 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...

For supported frameworks, web transactions should be captured automatically. If you don't have a supported framework, you can use the wsgi_application function to monitor your WSGI entry point.

Monitor non-web transactions...

Non-web transactions are classified as background tasks by the New Relic Python agent. Use background_task to capture non-web transactions.

Capture more details about a transaction...

Your transaction traces may not have the level of detail that you'd like. You can use function_trace to capture more function-level detail in transactions.

Ignore a transaction...

See ignore_transaction. To prevent a transaction from producing a transaction trace, see suppress_transaction_trace. To end a transaction before the agent would end it automatically, use end_of_transaction.

Add and edit transaction metadata

Sometimes, the code you are targeting is visible in the New Relic UI, but some details of the method are not useful. For example, the default name might not be helpful (perhaps it is causing a metric grouping issue), or you want to add custom attributes to your transactions so you can filter them in Insights. 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 (like a customer's subscription level) to transactions...

Add custom attributes to your transactions using add_custom_parameter. See Custom data for more API calls used for reporting custom data.

Mark a transaction as a background job...

You can convert a web transaction into a background task so that it shows up as a Non-web transaction in the UI, with set_background_task.

Prevent a transaction from affecting your Apdex score...

Use suppress_apdex_metric.

Report custom events and custom metric data

New Relic data comes in two primary forms: metric data and event data. Metric data is used for numeric time-based measurements; for example, "connections per minute." Event data is used for capturing discrete event information; events have key-value attributes attached to them and can be analyzed and queried in New Relic Insights. For more about the differences between these data types, see Data collection.

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...

To report a single metric, use record_custom_metric. To report a set of metrics, use record_custom_metrics.

Report an exception as an error in the New Relic UI...

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.

Tag events with metadata for more detailed analysis in Insights or error analytics...

Use add_custom_parameter to add attributes.

Generate metrics from data sources and data factories...

You can generate metrics with a pull-style API rather than the push-style API implemented by record_custom_metric(). Use register_data_source, data_source_generator, and data_source_factory.

Message-related calls

These API calls allow you to collect performance data on your message-passing architecture or service (for example, RabbitMQ). Use of these calls requires 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.

Agent management: configuration settings, initialization, and shutdown

These calls are related to managing the behavior of the agent, initializing the agent and integrating it, and referencing or changing configuration settings:

If you want to...

Do this...

Initialize agent as part of advanced integration process...

Use initialize to initialize the Python agent with a specific configuration file.

Get reference to the application object...

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

Get reference to configuration settings...

You may want to use the Python agent configuration settings to control the agent's behavior. Use global_settings to get a reference to config file and environment variable settings and make changes to those settings. Use application_settings to get reference to all the settings, including server-side configuration from the New Relic UI.

Shutdown 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

New Relic Browser can be added automatically to your pages or deployed on specific pages by copy/pasting the Javascript snippet. For more about installing Browser, see Install Browser.

You can also control the New Relic Browser agent via APM agent API calls. For more information, see New Relic Browser and the Python agent. Browser-related calls include:

If you want to...

Do this...

Monitor specific views with New Relic Browser...

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

Disable Browser monitoring for specific views...

Use disable_browser_autorum.

Other calls

This has been a look at some of the most useful calls, organized by function. To see a list of all available calls, see All Python agent API calls.

For more help

Join the discussion about Python in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.