• /
  • EnglishEspañol日本語한국어Português
  • Log inStart now

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:

Ignore a transaction

Use any of these options:

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:

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

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:

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.

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.