datastore_trace

For general information on how the Python agent API calls relate to each other, see the API guide.

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:

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

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.

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

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

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

Parameter Description

wrapped

function

Required. The function being wrapped.

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:

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.

Example(s)

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')

For more help

Recommendations for learning more: