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

## Syntax

```py
newrelic.agent.message_transaction(library, destination_type, destination_name, application, routing_key=None, exchange_type=None, headers=None, queue_name=None, reply_to=None, correlation_id=None)
```

Report message functions as transactions.

## Requirements

Agent version 2.88.0.72 or higher.

## Description

This decorator returns a [partial](https://docs.python.org/3.12/library/functools.html#functools.partial) of `MessageTransactionWrapper` that can be used as a decorator for a messaging function. When used, the returned decorator records a message transaction and its message-related [attributes](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#attribute).

If the decorator will not work in your application, you can use one of the following:

-   **The context manager**: The context manager form is `MessageTransaction`. It takes the same parameters as the decorator.
-   **The wrapper**: The wrapper form is `MessageTransactionWrapper`. 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_transaction`. This applies the `MessageTransactionWrapper` 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 when these different calls should be used, 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_transaction and MessageTransaction [#decorator-context-mgr-parameters]

```py
newrelic.agent.message_transaction(library, destination_type, destination_name, application, routing_key=None, exchange_type=None, headers=None, queue_name=None, reply_to=None, correlation_id=None)
```

```py
newrelic.agent.MessageTransaction(library, destination_type, destination_name, application, routing_key=None, exchange_type=None, headers=None, queue_name=None, reply_to=None, correlation_id=None)
```

The decorator and context manager use these parameters:

| Parameter                                 | Description                                                                                                                                                                 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `library` _string_ or _function_          | Required. The name (or type) of message broker in use. 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.                                |
| `application` _Application_               | Required. An application instance, as returned by [`application`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/application).                         |
| `routing_key` _string_ or _function_      | Optional. The routing key of the message.                                                                                                                                   |
| `exchange_type` _string_ or _function_    | Optional. The exchange type of the message.                                                                                                                                 |
| `headers` _dictionary_ or _function_      | Optional. The headers of the message.                                                                                                                                       |
| `queue_name` _string_ or _function_       | Optional. The queue name property of the message.                                                                                                                           |
| `reply_to` _string_ or _function_         | Optional. The `replyTo` property of the message.                                                                                                                            |
| `correlation_id` _string_ or _function_   | Optional. The `correlationID` property of the message.                                                                                                                      |

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

```py
newrelic.agent.MessageTransactionWrapper(wrapped, library, destination_type, destination_name, application, routing_key=None, exchange_type=None, headers=None, queue_name=None, reply_to=None, correlation_id=None)
```

The `MessageTransactionWrapper` takes all of the same parameters as the [decorator](#decorator-context-mgr-parameters) in addition to this `wrapped` parameter:

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

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

```py
newrelic.agent.wrap_message_transaction(module, object_path, library, destination_type, destination_name, application, routing_key=None, exchange_type=None, headers=None, queue_name=None, reply_to=None, correlation_id=None)
```

This takes all of the parameters that the [decorator](#decorator-context-mgr-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

The decorator `message_transaction` returns a `MessageTransactionWrapper` partial.

## Examples

### message_transaction example [#decorator-example]

An example of the decorator:

```py
mt = message_transaction('library', 'Exchange', 'x', routing_key='foo.bar')

@mt
def foo():
    pass
```

### MessageTransaction example [#context-mgr-example]

An example using the context manager:

```py
def callback(method, properties, body):
    with MessageTransaction('library', 'Exchange', 'x', application=app):
        pass
```

### MessageTransactionWrapper example [#wrapper-example]

An example using the wrapper:

```py
basic_consume_wrapper = newrelic.agent.MessageTransactionWrapper(basic_consume_register_callback, 'library', 'Queue', 'x')

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

### wrap_message_transaction example [#path-based-example]

An example using the path-based wrapper:

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