---
title: external_trace (Python agent API)
source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/externaltrace-python-agent-api
---

## Syntax

```py
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](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction-trace) 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](https://docs.python.org/3.12/library/functools.html#functools.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](https://docs.newrelic.com/docs/python-agent-api-different-call-forms). See [Examples](#examples) for call examples.

## Parameters

### Parameters for external_trace [#main-parameters]

```py
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 [#context-mgr-parameters]

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

The `ExternalTrace` context manager takes all of the [parameters](#main-parameters) taken by `external_trace`.

### Parameters for ExternalTraceWrapper [#wrapper-parameters]

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

The `ExternalTraceWrapper` takes all of the same parameters as the [decorator](#main-parameters) in addition to an initial `wrapped` parameter:

| Parameter                        | Description                                                                                                                                                                                                                   |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wrapped` _function_             | Required. The external call function to attribute to the external time.                                                                                                                                                       |
| `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 accepts the same parameters as the function being wrapped and returns the library.                       |
| `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 accepts the same parameters as the function being wrapped and returns the URL.                         |
| `method` _string_ or _function_  | Optional. The method defining the type of call being made. These are typically `get`, `post`, `put`, or `delete`.  Could be a function that accepts the same parameters as the function being wrapped and returns the method. |

### Parameters for wrap_external_trace [#path-based-parameters]

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

The `wrap_external_trace` takes all of the parameters that the [decorator](#main-parameters) 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 [#decorator-example]

An example of using `external_trace`:

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

An example of using `external_trace` on a native coroutine:

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

### ExternalTrace example [#context-mgr-example]

An example of using the `ExternalTrace` context manager:

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

### ExternalTraceWrapper example [#wrapper-example]

An example of using the `ExternalTraceWrapper`:

```py
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 [#path-based-example]

An example of using the `wrap_external_trace` path-based wrapper:

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