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

## Syntax

```py
newrelic.agent.datastore_trace(product, target, operation)
```

Used to instrument calls to datastores.

## Description

`datastore_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 `datastore_trace` will appear on the [APM Databases page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/databases-slow-queries-page). `datastore_trace` returns a [partial](https://docs.python.org/3.12/library/functools.html#functools.partial) of `DatastoreTraceWrapper` that can be used as a decorator for a function to time calls to your datastore.

The `datastore_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 `DatastoreTrace`.
-   **The wrapper**: The wrapper form is `DatastoreTraceWrapper`. 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_datastore_trace`. This applies the `DatastoreTraceWrapper` 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 decorator [#main-parameters]

```py
newrelic.agent.datastore_trace(product, target, operation)
```

This call includes these parameters:

| Parameter            | Description                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `product` _string_   | Required. The name of the vendor. Example: `Postgres`, `Redis`.                                                                       |
| `target` _string_    | Required. The name of the collection or table. If there is no target, `None` should be used.                                          |
| `operation` _string_ | Required. The name of the datastore operation. Examples: `select`, `get`, `insert`, `rollback`. If not provided, defaults to `other`. |

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

```py
newrelic.agent.DatastoreTrace(product, target, operation, host=None, port_path_or_id=None, database_name=None)
```

Parameters for the context manager includes all of the [parameters](#main-parameters) from `datastore_trace` plus the additional `host`, `port_path_or_id`, and `database_name` parameters.

| Parameter                  | Description                                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `host` _string_            | Optional. The hostname or IP of the datastore server.                                                                             |
| `port_path_or_id` _string_ | Optional. The port used to connect to the datastore server. If connecting with a unix socket, this can be the path to the socket. |
| `database_name` _string_   | Optional. The name of the database.                                                                                               |

### Wrapper parameters

```py
newrelic.agent.DatastoreTraceWrapper(wrapped, product, target, operation)
```

Parameters for the wrapper include all [parameters](#main-parameters) for `datastore_trace` and a `wrapped` parameter:

| Parameter            | Description                           |
| -------------------- | ------------------------------------- |
| `wrapped` _function_ | Required. The function being wrapped. |

### Path-based wrapping parameters [#path-wrap-parameters]

```py
newrelic.agent.wrap_datastore_trace(module, object_path, product, target, operation)
```

Parameters include all [parameters](#main-parameters) for `datastore_trace` and these parameters:

| Parameter              | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `module` _object_      | Required. The module containing the function to be instrumented. |
| `object_path` _string_ | Required. The path to the location of the function.              |

## Return values

`datastore_trace` returns a `DatastoreTraceWrapper()` partial.

## Examples

### `datastore_trace` example [#trace_example]

An example of using the `datastore_trace` decorator:

```py
import newrelic.agent

class _Database(UserDict.DictMixin):

    ...

    @newrelic.agent.datastore_trace('Redis', None, 'get')
    def _get(self, key):
        ...
```

An example of using the `datastore_trace` decorator with native coroutines:

```py
import newrelic.agent

class _Database(UserDict.DictMixin):

    ...

    @newrelic.agent.datastore_trace('Redis', None, 'get')
    async def _get(self, key):
        ...
```

### Context manager example [#context-mgr-example]

An example of using the `DatastoreTrace` context manager: This will give timings for how long it takes to do \`custom_action\`.

```py
import newrelic.agent


def complex_query(a, b, c):
    with Connection(host, port, db) as conn:
        with newrelic.agent.DatastoreTrace(
            product="Custom Product",
            target=None,
            operation="custom",
            host=host,
            port_path_or_id=port,
            database_name=db,
        ):

            conn.custom_action()
```

### Wrapper example [#trace-wrap-example]

An example of using the `DatastoreTraceWrapper`:

```py
import newrelic.agent

class _Database(UserDict.DictMixin):

    ...

    def _get(self, key):
        ...


_Database._get = newrelic.agent.DatastoreTraceWrapper(
    _Database._get, "Redis", None, "get"
)
```