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

## Syntax

```py
newrelic.agent.message_trace(library, operation, destination_type, destination_name, params={})
```

Report messaging functions as transaction trace segments.

## Requirements

Agent version 2.88.0.72 or higher.

## Description

[`message_transaction`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/message_transaction) (and its associated calls) report message functions as [transactions](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction). `message_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. `message_trace` returns a [partial](https://docs.python.org/3.12/library/functools.html#functools.partial) of `MessageTraceWrapper` that can be used as a decorator for a message function.

The `message_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 `MessageTrace`. It takes the same parameters as the decorator.
-   **The wrapper**: The wrapper form is `MessageTraceWrapper`. 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_message_trace`. This applies the `MessageTraceWrapper` 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 message_trace [#main-parameters]

```py
newrelic.agent.message_trace(library, operation, destination_type, destination_name, params={})
```

The `message_trace` decorator uses these parameters:

| Parameter                                 | Description                                                                                                                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `library` _string_ or _function_          | Required. The name (or type) of the type of message broker in use. Pass either a string which defines it or a function which returns it.                                      |
| `operation` _string_ or _function_        | Required. Either `Produce` or `Consume` as indicated by the operation occurring in the traced function. Pass either a string which defines it or a function which returns it. |
| `destination_type` _string_ or _function_ | Required. The type of destination targeted by the operation. Pass either a string which defines it or a function which returns it. This is typically `Exchange` or `Queue`.   |
| `destination_name` _string_ or _function_ | Required. The name of the destination being targeted by the operation. Pass either a string which defines it or a function which returns it.                                  |
| `params` _dictionary_                     | Optional. Additional details pertaining to the operation. These are typically `routing_key`, `correlation_id`, `reply_to`, `queue_name`, or `headers`.                        |

### Parameters for MessageTrace [#context-mgr-parameters]

```py
newrelic.agent.MessageTrace(library, operation, destination_type, destination_name, params={})
```

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

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

```py
newrelic.agent.MessageTraceWrapper(wrapped, library, operation, destination_type, destination_name, params={})
```

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

| Parameter            | Description                                                               |
| -------------------- | ------------------------------------------------------------------------- |
| `wrapped` _function_ | Required. The messaging function to attribute to the message broker time. |

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

```py
newrelic.agent.wrap_message_trace(module, object_path, library, operation, destination_type, destination_name, params={})
```

The `wrap_message_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

`message_trace` returns a `MessageTraceWrapper()` partial.

## Examples

### message_trace example [#decorator-example]

An example of using `message_trace`:

```py
@message_trace('library', 'Consume', 'Exchange', 'x')
def foo():
    pass
```

An example of using `message_trace` decorator with a native coroutine:

```py
@message_trace('library', 'Consume', 'Exchange', 'x')
async def foo():
    pass
```

### MessageTrace example [#context-mgr-example]

An example of using the `MessageTrace` context manager:

```py
def basic_get(queue, no_ack=False):
    with MessageTrace('library', 'Consume', 'Exchange', 'x'):
        pass
```

### MessageTraceWrapper example [#wrapper-example]

An example of using the `MessageTraceWrapper`:

```py
wrapped_basic_get = newrelic.agent.MessageTraceWrapper(basic_get, 'library', 'Consume', 'Queue', 'x')

method_frame, header_frame, body = wrapped_basic_get('queue')
```

### wrap_message_trace example [#path-based-example]

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

```py
wrap_message_trace('module', 'Foo.bar', 'library', 'Produce', 'Exchange', 'x')
```