Syntax
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 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
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
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.
Parameters
Parameters for decorator
newrelic.agent.profile_trace(name=None, group=None, label=None, params=None, depth=3)This call includes these parameters:
Parameter | Description |
|---|---|
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. |
string or function | Optional. The If not supplied, the group will default to |
string or function | Optional. Adds a callout-style flag to the segment in a transaction trace. Default is |
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. |
int | Optional. Defaults to 3. The stack depth to add segments to inside the function. |
Wrapper parameters
newrelic.agent.ProfileTraceWrapper(wrapped, name=None, group=None, label=None, params=None)Parameters for the wrapper include all parameters for profile_trace and a wrapped parameter:
Parameter | Description |
|---|---|
function | Required. The function being wrapped. |
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. |
string or function | Optional. The If not supplied, the group will default to |
string or function | Optional. Adds a callout-style flag to the segment in a transaction trace. Default is |
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. |
int | Optional. Defaults to 3. The stack depth to add segments to inside the function. |
Path-based wrapping parameters
newrelic.agent.wrap_profile_trace(module, object_path, name=None, group=None, label=None, params=None, depth=3)Parameters include all parameters for profile_trace and these parameters:
Parameter | Description |
|---|---|
object | Required. The module containing the function to be instrumented. |
string | The path to the location of the function. |
Examples
profile_trace example
An example of using the profile_trace decorator:
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_nodeIn 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
An example of using the ProfileTraceWrapper:
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.
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.
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)