• /
  • Log in
  • Free account
Docs

external_trace (Python agent API)

Syntax

newrelic.agent.external_trace(library, url, method=None)

Report calls to external services as transaction trace segments.

Description

external_trace is used to add more detail to your transaction traces in the form of additional segments. Any calls reported with external_trace will appear on the externals tab in APM. external_trace returns a partial of ExternalTraceWrapper that can be used as a decorator for a function that calls an external service.

The external_trace decorator can be used on generators and coroutines with agent version 2.102.0.85 or higher. Timing of these objects begins when consumption starts, and ends when the object is exhausted or goes out of scope. This is a change from earlier versions where the metric represented the time taken to create the generator or coroutine object itself.

If you cannot use the decorator in your application, you can use one of these other call formats:

  • The context manager: The context manager form is ExternalTrace.
  • The wrapper: The wrapper form is ExternalTraceWrapper. It can be used to return a wrapped function without the use of a decorator.
  • The path-based wrapper: The path-based wrapper form is wrap_external_trace. This applies the ExternalTraceWrapper to a given object through monkey patching. This takes the same parameters as the decorator plus an additional module and object_path parameter.

For an explanation of the uses of these different call formats, see Different call formats. See Examples for call examples.

Parameters

Parameters for external_trace

newrelic.agent.external_trace(library, url, method=None)

The external_trace decorator uses these parameters:

Parameter

Description

library

string or function

Required. The name (or type) of the external library in use. Pass either a string that defines it or a function that returns it.

url

string or function

Required. The URL that has been requested by the library call. Pass either a string that defines it or a function that returns it.

method

string or function

Optional. The method defining the type of call being made. These are typically get, post, put, or delete.

Parameters for ExternalTrace

newrelic.agent.ExternalTrace(library, url, method=None)

The ExternalTrace context manager takes all of the parameters taken by external_trace.

Parameters for ExternalTraceWrapper

newrelic.agent.ExternalTraceWrapper(wrapped, library, url, method=None)

The ExternalTraceWrapper takes all of the same parameters as the decorator in addition to an initial wrapped parameter:

Parameter

Description

wrapped

function

Required. The external call function to attribute to the external time.

Parameters for wrap_external_trace

newrelic.agent.wrap_external_trace(module, object_path, library, url, method=None)

The wrap_external_trace takes all of the parameters that the decorator does in addition to a module parameter and an object_path parameter:

Parameter

Description

module

object

Required. The module containing the object to be wrapped.

object_path

string

Required. The path to the object to be wrapped.

Return values

external_trace returns a ExternalTraceWrapper() partial.

Examples

external_trace example

An example of using external_trace:

@external_trace('library', 'http://example.com', 'get')
def foo():
pass

An example of using external_trace on a native coroutine:

@external_trace('library', 'http://example.com', 'get')
async def foo():
pass

ExternalTrace example

An example of using the ExternalTrace context manager:

def fetch_example_dot_com():
with ExternalTrace('library', 'http://example.com', 'get'):
pass

ExternalTraceWrapper example

An example of using the ExternalTraceWrapper:

wrapped_fetch_example_dot_com = newrelic.agent.ExternalTraceWrapper(fetch_example_dot_com, 'library', 'http://example.com', 'get')
response = wrapped_fetch_example_dot_com()

wrap_external_trace example

An example of using the wrap_external_trace path-based wrapper:

wrap_external_trace('module', 'Foo.bar', 'library', 'http://example.com', 'get')

For more help

If you need more help, check out these support and learning resources:

Docs
Create issueEdit page
Copyright © 2021 New Relic Inc.