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

## Syntax

```py
newrelic.agent.profile_trace(name=None, group=None, label=None, params=None, terminal=False)
```

Used to instrument a function and the functions inside of it to a particular depth for functions that aren't instrumented by default.

## Description

`profile_trace` is a decorator for adding to functions. Adding this decorator lets you collect additional [transaction](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction) information (including transaction trace information).

The `profile_trace` decorator can be used on functions 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.

You can use the decorator in conjunction with existing decorators, including those for static and class methods. When nesting multiple decorators, have the `profile_trace` decorator as the outermost decorator.

## Alternate call forms [#alternate]

For setups where you cannot use the decorator, these alternate call forms are available:

### The wrapper

If you know in advance where the specific functions you want to trace are, you could use the `profile_trace` decorator. However, if you **don't** know all the functions that need to be traced (for example, if they're being looked up dynamically as part of a routing system), then you must use the `ProfileTraceWrapper` to wrap the function at the time of registration or at the time of calling.

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

`wrap_profile_trace` is used for wrapping functions outside of the code they're declared in. For example: you might use this to instrument library code that you don't want to modify.

For more about the differences between these call formats, see [Different call formats](https://docs.newrelic.com/docs/python-agent-api-different-call-forms).

## Parameters

### Parameters for decorator [#main-parameters]

```py
newrelic.agent.profile_trace(name=None, group=None, label=None, params=None, depth=3)
```

This call includes these parameters:

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` _string_ or _function_  | Optional. The function name. Could be a function that accepts the same parameters as the function being wrapped. If not set, defaults to the captured name of the function.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `group` _string_ or _function_ | Optional. The `group` represents the naming structure for the `name` parameter. This is used in the UI for segregating the [transaction types](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/transactions-page#tx_functions). If not supplied, the group will default to `Function` in expectation that the name is of the form `module:class.function` or `module:function` and represents the name of the function being executed. If you are creating a custom group, it's recommended you prefix it with `Python/`. Could be a function that accepts the same parameters as the function being wrapped. |
| `label` _string_ or _function_ | Optional. Adds a callout-style flag to the segment in a transaction trace. Default is `None`. Could be a function that accepts the same parameters as the function being wrapped.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `params` _dict_ or _function_  | Optional. Custom parameters to add to the segment in transaction traces. Could be a function that accepts the same parameters as the function being wrapped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `depth` _int_                  | Optional. Defaults to 3. The stack depth to add segments to inside the function.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### Wrapper parameters

```py
newrelic.agent.ProfileTraceWrapper(wrapped, name=None, group=None, label=None, params=None)
```

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

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wrapped` _function_           | Required. The function being wrapped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `name` _string_ or _function_  | Optional. The function name. Could be a function that accepts the same parameters as the function being wrapped. If not set, defaults to the captured name of the function.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `group` _string_ or _function_ | Optional. The `group` represents the naming structure for the `name` parameter. This is used in the UI for segregating the [transaction types](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/transactions-page#tx_functions). If not supplied, the group will default to `Function` in expectation that the name is of the form `module:class.function` or `module:function` and represents the name of the function being executed. If you are creating a custom group, it's recommended you prefix it with `Python/`. Could be a function that accepts the same parameters as the function being wrapped. |
| `label` _string_ or _function_ | Optional. Adds a callout-style flag to the segment in a transaction trace. Default is `None`. Could be a function that accepts the same parameters as the function being wrapped.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `params` _dict_ or _function_  | Optional. Custom parameters to add to the segment in transaction traces. Could be a function that accepts the same parameters as the function being wrapped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `depth` _int_                  | Optional. Defaults to 3. The stack depth to add segments to inside the function.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

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

```py
newrelic.agent.wrap_profile_trace(module, object_path, name=None, group=None, label=None, params=None, depth=3)
```

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

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

## Examples

### `profile_trace` example [#trace_example]

An example of using the `profile_trace` decorator:

```py
import newrelic.agent

@newrelic.agent.profile_trace(depth=7)
def find_node(tree, value):
    if tree.value == value:
        return tree
    for node in tree.children:
        found_node = find_node(node, value)
        if found_node:
            return found_node
```

In the above example the profile trace is wrapped around a recursive function. Function
traces will be added up to 7 recursive stack calls deep into the function.

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

An example of using the `ProfileTraceWrapper`:

```py
import newrelic.agent

def find_node(tree, value):
    if tree.value == value:
        return tree
    for node in tree.children:
        found_node = find_node(node, value)
        if found_node:
            return found_node

find_node = newrelic.agent.ProfileTraceWrapper(find_node, depth=7)
```

If you want to name the metric after the endpoint name (rather than naming the metric based on the identifier for the function being called), you can supply the name to use plus an alternate metric path prefix when the `ProfileTraceWrapper` object is created.

```py
import newrelic.agent

def find_node(tree, value):
    if tree.value == value:
        return tree
    for node in tree.children:
        found_node = find_node(node, value)
        if found_node:
            return found_node

find_node = newrelic.agent.ProfileTraceWrapper(find_node, name="find_node", group="Python/Profile", depth=7)
```

If you want to name the metric dynamically (rather than naming the metric based on the identifier for the function being called), you can supply the name as a function when the `ProfileTraceWrapper` object is created.

```py
import newrelic.agent

def find_node(tree, value):
    if tree.value == value:
        return tree
    for node in tree.children:
        found_node = find_node(node, value)
        if found_node:
            return found_node

find_node = newrelic.agent.ProfileTraceWrapper(find_node, name=lambda tree, value: f"find_node_{value}", depth=7)
```