web_transaction (Python agent API)

Syntax

newrelic.agent.web_transaction(application=None, name=None, group=None, scheme=None, host=None, port=None, request_method=None, request_path=None, query_string=None, headers=None)

Used to instrument a web transaction.

Requirements

Agent version 4.16.0.116 or higher

Description

This Python decorator can be used to instrument web transactions. Transactions marked with this decorator are shown in the APM UI under web transactions and are separate from non-web transactions.

If you cannot use the decorator, one of these call formats may be more useful:

The wrapper: If you know in advance where the specific functions you want to track are, you can use the web_transaction decorator. But 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 WebTransactionWrapper to wrap the function at the time of registration or at the time of calling.
The path-based wrapper: The path-based wrapper form is wrap_web_transaction.

For more on the differences between and uses of these function forms, see Variable call formats.

Parameters

Decorator parameters

newrelic.agent.web_transaction(application=None, name=None, group=None, scheme=None, host=None, port=None, request_method=None, request_path=None, query_string=None, headers=None)

Parameters for these calls:

Parameter	Description
`application` Application instance	Optional. The application under which the data will be reported. If left without a value, the application specified in the agent configuration (config file or environment variable) will be used. For more on generating an application object, see the `application()` method.
`name` string or function	Optional. The name of the transaction. Could be a function that accepts a callable_name parameter. The default value is `None`. By default, the name will be the name of the function the decorator has been applied to but you can override this by supplying this name.
`group` string or function	Optional. The `group` represents the naming structure for the `name` parameter. This is used in the UI to set the transaction type. If not supplied, the group defaults 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, we recommend you prefix it with `Python/`. Could be a function that accepts the same parameters as the function being wrapped.
`scheme` string or function	Optional. The scheme portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.
`host` string or function	Optional. The host portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.
`port` integer or function	Optional. The port portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.
`request_method` string or function	Optional. The HTTP request method, such as GET or POST. Could be a function that accepts the same parameters as the function being wrapped.
`request_path` string or function	Optional. The remainder of the request URL's path. Could be a function that accepts the same parameters as the function being wrapped.
`query_string` string or function	Optional. The portion of the request URL that follows the question mark. Could be a function that accepts the same parameters as the function being wrapped.
`headers` iterable or dict or function	Optional. The HTTP request headers An iterable of [name, value] two-item iterables or dict of `{name:value}`, where name is the header name, and value is the header value. Could be a function that accepts the same parameters as the function being wrapped.

Parameter

Description

application

Application instance

Optional. The application under which the data will be reported. If left without a value, the application specified in the agent configuration (config file or environment variable) will be used.

For more on generating an application object, see the application() method.

name

string or function

Optional. The name of the transaction. Could be a function that accepts a callable_name parameter. The default value is None. By default, the name will be the name of the function the decorator has been applied to but you can override this by supplying this name.

group

string or function

Optional. The group represents the naming structure for the name parameter. This is used in the UI to set the transaction type.

If not supplied, the group defaults 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, we recommend you prefix it with Python/. Could be a function that accepts the same parameters as the function being wrapped.

scheme

string or function

Optional. The scheme portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.

host

string or function

Optional. The host portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.

port

integer or function

Optional. The port portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.

request_method

string or function

Optional. The HTTP request method, such as GET or POST. Could be a function that accepts the same parameters as the function being wrapped.

request_path

string or function

Optional. The remainder of the request URL's path. Could be a function that accepts the same parameters as the function being wrapped.

query_string

string or function

Optional. The portion of the request URL that follows the question mark. Could be a function that accepts the same parameters as the function being wrapped.

headers

iterable or dict or function

Optional. The HTTP request headers An iterable of [name, value] two-item iterables or dict of {name:value}, where name is the header name, and value is the header value. Could be a function that accepts the same parameters as the function being wrapped.

Wrapper parameters:

newrelic.agent.WebTransactionWrapper(wrapped, application=None, name=None, group=None, scheme=None, host=None, port=None, request_method=None, request_path=None, query_string=None, headers=None)

WebTransactionWrapper takes the same parameters as the web_transaction decorator and this additional wrapped parameter:

Parameter	Description
`wrapped` method	Required. The method to be traced.
`name` string or function	Optional. The name of the transaction. Could be a function that accepts a callable_name parameter. The default value is `None`. By default, the name will be the name of the function the decorator has been applied to but you can override this by supplying this name.
`group` string or function	Optional. The `group` represents the naming structure for the `name` parameter. This is used in the UI to set the transaction type. If not supplied, the group defaults 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, we recommend you prefix it with `Python/`. Could be a function that accepts the same parameters as the function being wrapped.
`scheme` string or function	Optional. The scheme portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.
`host` string or function	Optional. The host portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.
`port` integer or function	Optional. The port portion of the request URL. Could be a function that accepts the same parameters as the function being wrapped.
`request_method` string or function	Optional. The HTTP request method, such as GET or POST. Could be a function that accepts the same parameters as the function being wrapped.
`request_path` string or function	Optional. The remainder of the request URL's path. Could be a function that accepts the same parameters as the function being wrapped.
`query_string` string or function	Optional. The portion of the request URL that follows the question mark. Could be a function that accepts the same parameters as the function being wrapped.
`headers` iterable or dict or function	Optional. The HTTP request headers An iterable of [name, value] two-item iterables or dict of `{name:value}`, where name is the header name, and value is the header value. Could be a function that accepts the same parameters as the function being wrapped.

Path-based parameters:

newrelic.agent.wrap_web_transaction(module, object_path, application=None, name=None, group=None, scheme=None, host=None, port=None, request_method=None, request_path=None, query_string=None, headers=None)

wrap_web_transaction takes the same parameters as the web_transaction decorator plus these additional parameters:

Parameter	Description
`module` module or string	Required. The module containing the web function/activity you are instrumenting.
`object_path` string	Required. The path to the module.

Parameter

Description

module

module or string

Required. The module containing the web function/activity you are instrumenting.

object_path

string

Required. The path to the module.

Examples

`web_transaction` decorator example

Here's an example of using the web_transaction decorator:

@newrelic.agent.web_transaction()
def get():
    ...

`WebTransactionWrapper` example

An example of using the WebTransactionWrapper:

task = newrelic.agent.WebTransactionWrapper(get_next_task())
result = task(*args, **kwargs)

Syntax.css-21sua1{background:none;border:none;width:0;padding:0;}

Requirements

Description

Parameters

Decorator parameters

Wrapper parameters:

Path-based parameters:

Examples

web_transaction decorator example

WebTransactionWrapper example

Syntax

`web_transaction` decorator example

`WebTransactionWrapper` example