--- title: Guide to using the Python agent API source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/guide-using-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](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api). For a description of all our available APIs, see [Introduction to APIs](https://docs.newrelic.com/docs/apis/getting-started/introduction-new-relic-apis). ## Custom instrumentation or API [#custom-instrumentation] If your goal is [custom instrumentation](#instrumentation), consider using the [configuration file method](https://docs.newrelic.com/docs/agents/python-agent/custom-instrumentation/python-custom-instrumentation-config-file), 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](https://docs.newrelic.com/docs/release-notes/agent-release-notes/python-release-notes). ## Monitor transactions and segments [#transaction-segments] The Python agent is [compatible with most of the common WSGI web frameworks](https://docs.newrelic.com/docs/agents/python-agent/getting-started/compatibility-requirements-python-agent). If the agent supports your framework, web requests automatically will be captured as [transactions](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction) and displayed in the New Relic UI. A transaction can also have function-level segments that are captured as part of a [transaction trace](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#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](https://docs.newrelic.com/docs/agents/python-agent/getting-started/compatibility-requirements-python-agent). If you do not have a supported framework, you can use the [`wsgi_application`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/wsgi_application) function to monitor your WSGI entry point. | | Monitor ASGI web transactions | The Python agent automatically captures web transactions for [supported frameworks](https://docs.newrelic.com/docs/agents/python-agent/getting-started/compatibility-requirements-python-agent). If you do not have a supported framework, you can use the [`asgi_application`](https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/asgi_application) function to monitor your ASGI entry point. | | Monitor non-web transactions | The Python agent classifies [non-web transactions](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/monitor-background-processes-other-non-web-transactions) as background tasks. To capture non-web transactions, use [`background_task`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/background_task). | | Capture more details about a transaction | If your [transaction traces](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/introduction-transaction-traces) do not have the level of detail you want: - Use [`function_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/function_trace) to capture more function-level detail in transactions. - Use [`datastore_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/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`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/ignore_transaction). - To prevent a transaction from producing a transaction trace, use [`suppress_transaction_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/suppress_transaction_trace). - To end a transaction before the agent would end it automatically, use [`end_of_transaction`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/end-of-transaction). | ## Dynamically name segments and segment attributes [#dynamically-name-segments-and-segment-attributes] To dynamically name segments and segment attribute values, use custom instrumentation API calls, which accept a function instead of a static value for various parameters. Before agent version 13.0.0, you could also do this in the configuration file using a lambda function. This is now only supported in custom instrumentation API calls. The following API calls support dynamic naming: - [`background_task`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/backgroundtask-python-agent-api) - [`database_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/databasetrace-python-agent-api) - [`external_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/externaltrace-python-agent-api) - [`function_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/functiontrace-python-agent-api) - [`generator_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/generatortrace-python-agent-api) - [`memcache_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/memcachetrace-python-agent-api) - [`profile_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/profiletrace-python-agent-api) - [`web_transaction`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/web_transaction-python-agent-api) ## Add and edit transaction metadata [#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](https://docs.newrelic.com/docs/agents/manage-apm-agents/troubleshooting/metric-grouping-issues#video). - You want to add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-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`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/current_transaction). This is required by some other Python agent API calls. | | Change the name of a transaction | Use [`set_transaction_name`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/set_transaction_name). | | Add metadata (such as a customer's subscription level) to transactions | Add [custom attributes](https://docs.newrelic.com/docs/new-relic-solutions/get-started/glossary/#attribute) to your transactions using [`add_custom_attribute`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/add_custom_attribute), or use other API calls to [report custom data](#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](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/getting-started/glossary#non-web-transaction) in the UI, use [`set_background_task`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/set_background_task). | | Prevent a transaction from affecting your [Apdex score](https://docs.newrelic.com/docs/apm/new-relic-apm/apdex/view-your-apdex-score) | Use [`suppress_apdex_metric`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/suppress_apdex_metric). | ## See related logs [#logs] To see logs directly within the context of your application's errors and traces, use the [`get_linking_metadata`](https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/getlinkingmetadata-python-agent-api/) API call to annotate your logs. For more information about correlating log data with other telemetry data, see our [logs in context](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-python/) documentation. ## Report custom events and custom metric data [#custom-data] The agent [reports data](https://docs.newrelic.com/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-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](https://docs.newrelic.com/docs/query-your-data/explore-query-data/explore-data/introduction-querying-new-relic-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`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/record_custom_event). | | Report time-based metrics on application performance | - To report a single metric, use [`record_custom_metric`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/record_custom_metric). - To report a set of metrics, use [`record_custom_metrics`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/recordcustommetrics-python-agent-api). | | 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`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/noticeerror-python-agent-api/). | | Report query string parameters | For security reasons, query string parameters associated with web transactions are disabled by default. Use [`capture_request_params`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/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`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/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`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/register_data_source) - [`data_source_generator`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/data_source_generator) - [`data_source_factory`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/data_source_factory) | ## Message-related calls [#messaging] These API calls allow you to collect performance data on your message-passing architecture or service; for example, [RabbitMQ](https://www.rabbitmq.com/). To use these calls, make sure you have Python [agent version 2.88.0.72 or higher](https://docs.newrelic.com/docs/release-notes/agent-release-notes/python-release-notes). | If you want to... | Do this... | | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Report messages as a [transaction](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction) | Use [`message_transaction`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/message_transaction). | | Report message details as transaction trace segments | Use [`message_trace`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/message-trace). | > #### ⚠️ IMPORTANT > > The agent does not collect message queue parameters when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. ## Implement distributed tracing [#distributed-tracing] These APIs require [distributed tracing to be enabled](https://docs.newrelic.com/docs/enable-distributed-tracing). Services and applications monitored by our agents will automatically pass distributed tracing context to each other when using a [supported framework](https://docs.newrelic.com/docs/agents/python-agent/getting-started/instrumented-python-packages#web-frameworks). 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_headers`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/acceptdistributedtraceheaders-python-agent-api) when creating a transaction. [Supported external web services libraries](https://docs.newrelic.com/docs/agents/python-agent/getting-started/instrumented-python-packages#external-web-services) will automatically call [`insert_distributed_trace_headers`](https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/insertdistributedtraceheaders-python-agent-api) 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](https://docs.newrelic.com/docs/enable-distributed-tracing#agent-apis). | If you want to... | Do this... | | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create a distributed trace header with the New Relic payload to be sent to a called service. | Use [`newrelic.agent.insert_distributed_trace_headers`](https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/insertdistributedtraceheaders-python-agent-api). | | Accept distributed trace headers containing the New Relic payload sent from the first service; this will link these services together in a trace | Use [`accept_distributed_trace_headers`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/acceptdistributedtraceheaders-python-agent-api). | ## Agent configuration, initialization, shutdown [#mgmt] These calls help you manage Python agent behavior, such as initializing and integrating the agent, and referencing or changing [configuration](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-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](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-integration#manual-integration), use [`initialize`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/initialize). | | Get a reference to the `application` object | The [`application`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/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](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-configuration). - To get a reference to config file and environment variable settings and make changes to them, use [`global_settings`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/global_settings). - To get a reference to **all** settings, including [server-side configuration](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/configure-agent#ssc) from our UI, use [`application_settings`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/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`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/shutdown_agent). | ## Control the Browser monitoring agent [#browser] You can [install the browser monitoring agent](https://docs.newrelic.com/docs/browser/new-relic-browser/installation-configuration/add-apps-new-relic-browser) by automatically adding it to your pages or by deploying it on specific pages by copying and pasting the browser monitoring 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](https://docs.newrelic.com/docs/agents/python-agent/supported-features/page-load-timing-python). | 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 [`get_browser_timing_header`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/get_browser_timing_header). | | Disable monitoring of specific page views | To disable browser monitoring for specific page views, use [`disable_browser_autorum`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/disable_browser_autorum). |