datastore_trace (Python agent API)

Syntax

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 in the form of additional segments. Any calls reported with datastore_trace will appear on the APM Databases page. datastore_trace returns a 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. See Examples for call examples.

Parameters

Parameters for decorator

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

This call includes these parameters:

Parameters for context manager

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 from datastore_trace plus the additional host, port_path_or_id, and database_name parameters.

Wrapper parameters

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

Parameters for the wrapper include all parameters for datastore_trace and a wrapped parameter:

Path-based wrapping parameters

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

Parameters include all parameters for datastore_trace and these parameters:

Return values

datastore_trace returns a DatastoreTraceWrapper() partial.

Examples

datastore_trace example

An example of using the datastore_trace decorator:

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:

import newrelic.agent

class _Database(UserDict.DictMixin):

    ...

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

Context manager example

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

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

An example of using the DatastoreTraceWrapper:

import newrelic.agent

class _Database(UserDict.DictMixin):

    ...

    def _get(self, key):
        ...


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