Guide to using the Python agent API

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

Manually instrument an unsupported framework or third-party system.
Add instrumentation to supplement the agent's default monitoring.

This document describes some of the available Python API calls. For a description of all our available 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 the agent. 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 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 ASGI web transactions	The Python agent automatically captures web transactions for supported frameworks. If you do not have a supported framework, you can use the `asgi_application` function to monitor your ASGI 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: Use `function_trace` to capture more function-level detail in transactions. Use `datastore_trace` to capture more detail about datastore calls.
Ignore a transaction	Use any of these options: To ignore a transaction altogether, use `ignore_transaction`. To prevent a transaction from producing a transaction trace, use `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 target is visible in our UI, but some details of the method are not useful. For example:

The default name is not helpful, or it is causing a metric grouping issue.
You want to add custom attributes to your transactions so you can filter them when querying.

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_attribute`, 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`.

See related logs

To see logs directly within the context of your application's errors and traces, use the get_linking_metadata API call to annotate your logs. For more information about correlating log data with other telemetry data, see our logs in context documentation.

Report custom events and custom metric data

The agent reports 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.

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 when querying your data.	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	By default, the Python agent only reports unhandled exceptions. To report a Python exception as an error, use `notice_error`.
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 querying or error analytics, use `add_custom_attribute`.
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: `register_data_source` `data_source_generator` `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. To use these calls, make sure you have Python agent version 2.88.0.72 or higher.

If you want to...	Do this...
Report messages as a transaction	Use `message_transaction`.
Report message details as transaction trace segments	Use `message_trace`.

Important

The agent does not collect message queue parameters when high security mode is enabled.

Implement distributed tracing

These APIs require distributed tracing to be enabled.

Services and applications monitored by our agents 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 an agent-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. To get a reference to config file and environment variable settings and make changes to them, use `global_settings`. To get a reference to all settings, including server-side configuration from our UI, use `application_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 Browser monitoring agent

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

If you want to...	Do this...
Monitor specific page views	To inject the browser agent 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`.

Custom instrumentation or API .css-21sua1{background:none;border:none;width:0;padding:0;}