--- title: web_transaction (Python agent API) source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/webtransaction-python-agent-api --- ## Syntax ```py 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](https://docs.newrelic.com/docs/python-agent-api-different-call-forms). ## Parameters ### Decorator parameters [#main-params] ```py 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](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-configuration) (config file or environment variable) will be used. For more on generating an application object, see the [`application()`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/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](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/transactions-page#tx_functions). 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: [#wrapper-params] ```py 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](#main-params) 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](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/transactions-page#tx_functions). 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: [#path-based-params] ```py 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](#main-params) 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. | ## Examples ### `web_transaction` decorator example [#bg_task_example] Here's an example of using the web_transaction decorator: ```py @newrelic.agent.web_transaction() def get(): ... ``` ### `WebTransactionWrapper` example [#wrapper-example] An example of using the `WebTransactionWrapper`: ```py task = newrelic.agent.WebTransactionWrapper(get_next_task()) result = task(*args, **kwargs) ```