Transactions

Transaction means the logical unit of work (LUW) on the server side for processing a user browser request. The process for an individual web service (URL) request is a transaction. A transaction in a web application is the process from receiving an HTTP request for a web service (URL) to returning a response.

The performance of the application can be summarized as the performance of these transactions. Transaction performance includes information such as transaction start-to-end time, response time, resource usage, or attributes of the transaction caller.

Basically, the transaction performance can be analyzed through the response distribution and statistics.

Transaction Tracing

The following agent options allow you to trace the execution paths of each transaction within applications in detail. You can adjust various aspects, from the minimum response time to the number of execution steps for transactions.

profile_basetime MiliSecond

Default 500

Set the minimum response time to collect trace details. The trace data is not collected, if a transaction is terminated within the set value. The first URL called in every 5 minutes and the erroneous profile data are collected.

Note
To collect errors regardless of the profile_basetime option, set the profile_concern_error_enabled option to true. If set to the default value of false, errors are sampled.

profile_step_normal_count Int

Default 1000

Set the maximum step count for tracing transactions.
profile_step_heavy_count Int

Default 1020

In case of heavy steps, even if they exceed the default step count in the trace, the set value is recorded.
profile_step_max_count Int

Default 1024

Set the maximum number of trace steps. If the number of collected trace steps exceeds this value, all steps collected later are ignored. If profile_step_heavy_count is set up to 1000, active stacks are collected as many as profile_step_max_count.
profile_step_heavy_time MiliSecond

Default 100

Set the criterion of heavy steps. If the execution time is greater than the set value and profile_step_normal_count is exceeded, recording is made as many as profile_step_heavy_count.
active_stack_count Int

Default 100

Set the maximum number of active stacks to collect in transactions.
profile_method_resource_enabled Boolean

Default false

When collecting method steps from the transaction trace, the CPU and memory usages in the step is traced.
profile_position_method String

It records the stack traces that run the set methods.
profile_position_depth Int

Default 50

Set the maximum number of lines when recording stack traces for position tracing.
trace_error_callstack_depth Int

Default 50

Set the maximum number of stack trace lines collected when errors occur.
trace_active_callstack_depth Int

Default 50

Set the maximum number of stack trace lines collected by active stacks.

trace_active_transaction_yellow_time MiliSecond

Default 3000

Set the criteria to display in yellow on the active transaction arc equalizer.
trace_active_transaction_red_time MiliSecond

Default 8000

Set the criteria to display in red on the active transaction arc equalizer.

hook_method_patterns String

It sets the method to measure the response time. Class full names and methods are separated by the period (.) as the delimiter, and asterisk (*) can be used as the wildcard. In case of multiple items, comma (,) is used as the delimiter.
whatap.conf
```
hook_method_patterns=a.b.C1.*
```
Note
- The methods registered through this option can be checked through the Method step in Trace analysis or Transaction information window.
- It is recommended to apply it locally as much as possible. If applied extensively, it may cause performance degradation in applications.
hook_method_supers String

Set the super class when measuring the response time of the method inherited from a specific class. It sets the full name of the class. Multiple items are separated with comma (,).
whatap.conf
```
hook_method_supers=a.b.C1
```
hook_method_interfaces String

When measuring the response time of the method that implements a specific interface, it sets the interface. It sets the full name of the interface. Multiple items are separated with comma (,).
hook_method_ignore_classes String

When setting a method trace, it sets the classes to exclude from the trace.
hook_method_access_public_enabled Boolean

Default true

When setting a method trace, it sets whether or not to treat only the public methods as separate targets.
hook_method_access_private_enabled Boolean

Default false

When setting a method trace, it sets whether or not to treat only the private methods as separate targets.
hook_method_access_protected_enabled Boolean

Default true

When setting a method trace, it sets whether or not to treat only the protected methods as separate targets.
hook_method_access_none_enabled Boolean

Default true

When setting a method trace, it sets whether or not to treat only the no access indicated methods as separate targets.
stacklog_socket_port TCP_PortNumber

Default 0

If the destination TCP port has been set, the stack trace is recorded as an agent log at the time of Socket.connect(). It can be used when tracing DB connections, HTTPC connections, and such that are not checked by default settings.

Caution
Stack traces are recorded whenever the set destination is connected. It may cause performance degradation. It must be used temporarily only in the agents selected for debugging purposes.
Example of DB connection tracing: stacklog_socket_port=1521
trace_concern_error_enabled Boolean

Default true

It sets whether or not to collect detailed traces with errors, regardless of the trace_basetime or profile_basetime option.

Exceptional handling

The following options are used to manage and monitor exceptions that occur in applications. You can check the stability of applications by registering business exceptions and collecting related statistics. You can also set whether to ignore specific exceptions or treat them as errors if the HTTP status code is an error. Exception-handled items appear as normal transactions in the Hitmap or Trace analysis window.

Note

For more information about the Java agent's exception handling criteria, see the following.

biz_exceptions String

It registers the business exception.
whatap.conf
```
# example
biz_exceptions=com.home.test.exception.BizException
```
Tip
Error class collection/Hitmap display level: Includes the INFO (blue)/error statistics.

Note
In the Java agent v2.2.20 or higher, the registered business exceptions are collected as error statistics. In the versions below v2.2.20, the registered business exceptions are excluded from error statistics. However, they appear in the trace details.
biz_exceptions_status String Java Agent v2.2.20 or later

Set the business exception and status to restrict event notifications when any exception occurs. For Business Exception:Status set by this option, the event level is changed to INFO. Business exceptions and status are separated by colon (:). If multiple statuses are used for a business exception, they are separated by ampersand (&). You can set multiple values using comma(,) as the delimiter.
whatap.conf
```
# example
biz_exceptions_status=java.util.concurrent.TimeoutException:400&404&408,java.lang.Exception:200
```
Tip
Error class collection/Hitmap display level: Includes the INFO (blue)/error statistics.
ignore_exceptions String

The errors of the registered exceptions are ignored.
whatap.conf
```
# example
ignore_exceptions=com.home.test.exception.BizException
```
Tip
Ignore error class/Hitmap display level: Excludes the INFO (blue)/error statistics.
transaction_status_error_enable Boolean

Default true

If an HTTP status code that is not a normal response such as HTTP 401 or 403, is returned, set whether or not to handle it as an error.
status_ignore String

You can set the HTTP status codes to ignore. For multiple values, use comma (,) as the delimiter.
whatap.conf
```
# example
status_ignore=408,500
```
Tip
Ignore status error/Hitmap display level: Excludes the INFO (blue)/error statistics.
status_ignore_set String

whatap.error.STATUS_ERROR is ignored. For multiple values, use comma (,) as the delimiter.
whatap.conf
```
# example
status_ignore_set=/api/test/timeout/{time}:408,/error:500
```
Tip
Ignore status error set/Hitmap display level: Excludes the INFO (blue)/error statistics.
httpc_status_error_enable Boolean

Default true

Set whether or not to collect when the HTTP status code is an error. It includes client error responses (400 or higher) and server error responses (500 or higher).

Note
For more information about the HTTP status codes, see the following.
httpc_status_ignore String

If the HTTP status code is an error (HTTPC_ERROR), it can be ignored. For multiple values, use comma (,) as the delimiter.
whatap.conf
```
# example
httpc_status_ignore=404,500
```
Tip
Ignore HTTP status error code/Exclude error statistics
httpc_status_url_ignore_set String

whatap.error.HTTPC_ERROR is ignored. For multiple values, use comma (,) as the delimiter.

Set it as httpc_status_url_ignore_set =/a/b/c:400,/a/ab/c:404. In Statistics/Error Analysis, enter the value for HTTPC_URL.
whatap.conf
```
# example
httpc_status_url_ignore_set=/a/b/c:404,/d/e/f:500
```
Tip
Ignore HTTP status error code/Exclude error statistics
trace_sql_exception_enabled Boolean

Default true

It sets whether to trace SqlException when occurred in the JDBC driver. By setting the option value to false, you can perform biz_exceptions as custom exception handling.
trace_exception_handler_overwrite_enabled Boolean

Default true

If an exception that passes through the spring-boot ExceptionHandler occurs, it can replace the previous exception. In the Trace analysis tab of the Record summary window, you can mark the exception as an exception registered in the ExceptionHandler of the spring-boot.

HTTP transaction tracing

The following agent options trace and record various data related to HTTP requests and responses. This allows you to closely monitor and analyze the HTTP transactions for applications. You can add parameter values to the transaction names or exclude specific URLs or HTTP methods. You can also record transactions in detail, including HTTP headers and parameters.

trace_normalize_enabled Boolean

Default true

It enables the function to parse and normalize transaction URLs.

Note
If the value is changed to false, it disables the path parameter parsing. In this case, it is recommended to temporarily use the setting only for debugging purposes because the statistical data is less meaningful.
trace_auto_normalize_enabled Boolean

Default true

It enables automatic parsing of pattern values by extracting them from annotations when normalizing transaction URLs.
trace_normalize_urls String

Set transaction URL patterns to normalize. It deletes the path parameter after parsing the call URL patterns.

Note
For example, if declared as /a/{v}/b, a/123/b is replaced by a/{v}/b. For multiple values, use comma (,) as the delimiter. A complement is required after arranging substitution patterns.
web_static_content_extensions String

Default js, htm, html, gif, png, jpg, css, swf, ico

Set the extension to determine the static content. Transactions with the set extensions are excluded from the transaction tracing and counting.
trace_transaction_name_header_key String

The value extracted from the set HTTP header key is added at the end of the transaction name.

profile_http_header_enabled Boolean

Default false

To record HTTP headers in the trace details, set it to true.
profile_http_parameter_enabled Boolean

Default false

To record HTTP parameters in the trace details, set this to true. Parameters can be viewed by entering a separate security key.
Note
- Earlier than Java Agent 2.2.2: The security key is written in the WAS server ${WHATAP_AGENT_HOME}/paramkey.txt file with a 6-letter value. If the paramkey.txt file does not exist, it is automatically created with a random value.
- Java Agent 2.2.2 or later: For the security key, check the paramkey key value in the WAS server ${WHATAP_AGENT_HOME}/security.conf file. If the security.conf file does not exist, the paramkey key value is automatically created as WHATAP.
- For more information about the security key configuration file, see the following.
profile_http_header_url_prefix String

It is used to define the prefix of URL to record HTTP headers in the trace history.
profile_http_parameter_url_prefix String

It is used to define the prefix of URL to record HTTP parameters in the trace details.

trace_transaction_name_key String

If you set the HTTP request parameter value in the option, the parameter value is extracted and added to the end of the transaction name.

For example, when calling the /api/test URL with paramKey as an HTTP parameter, if you set it as in the following example, the transaction name in the trace history appears as /api/test$paramKey={value}. However, multiple parameters cannot be registered.
whatap.conf
```
# example
trace_transaction_name_key=paramKey
```
recursive_max Int

Default 1000000

This option is used to detect whether any transaction has been recursively called. Set the criteria for issuing event notifications by counting the number of recursive calls that are caused by a single transaction.

Note
It targets the HTTP URL recursive calls. It counts the recursive calls delivered through jsp:forward.
hook_httpservlet_classes String

It additionally sets END POINT for HTTP transactions. For the first 2 parameters of the method, only HttpServletRequest and HttpServletResponse can be set.
hook_jsp_patterns String

Default org.apache.jasper.servlet.JspServlet.serviceJspFile

Set the method to load the JSP files. It displays the JSP information returned as a result of the transaction call in a trace. Default values are automatically added to the settings added through this option.
trace_ignore_url_set String

It sets URLs to exclude from transaction tracing. For multiple values, use comma (,) as the delimiter.

Note
The URLs registered through this option are excluded from the Hitmap, Trace analysis, or Transaction information window for collection.
trace_ignore_url_prefix String

It sets URL prefixes to exclude from transaction tracing. For multiple values, use comma (,) as the delimiter.

Note
The URLs registered through this option are excluded from the Hitmap, Trace analysis, or Transaction information window for collection.
ignore_http_method String

Default PATCH,OPTIONS,HEAD,TRACE

Transactions requested by the specified HTTP method are not collected. To set multiple items, use comma (,) as the delimiter.
whatap.conf
```
# e.g. tracing the transactions whose http_method is OPTIONS or HEAD
ignore_http_method=PATCH,TRACE

# e.g. ignoring the transactions whose http_method is OPTIONS or HEAD
ignore_http_method=OPTIONS,HEAD
```
Note
The HTTP methods registered through this option are excluded from the Hitmap, Trace analysis, or Transaction information window for collection.
trace_tx_name_with_method_enabled Boolean

Default false

Statistical data can be collected using URL+method where the URL has been changed. You can check with URL+method in Statistics or Transaction Search.

e.g. /api/user+GET, /api/user+POST

Non-HTTP transaction tracing

The following options are used to trace and monitor non-HTTP transactions: These options allow you to closely trace background tasks or transactions for other protocols.

trace_auto_transaction_enabled Boolean

Default false

Collection is not allowed when the trace target method is not performed within the transaction start point (Javax.http.httpservlet, hook_service_*). In this case, set to make the trace target method become the transaction start point.

Note
This is used when finding the end point of the background transaction mainly in the development environment.
trace_auto_transaction_backstack_enabled Boolean

Default true

If the value of the trace_auto_transaction_enabled option is true, the stack trace is recorded upon start of transaction. As the above, the start point of transaction can be found.
trace_background_socket_enabled Boolean

Default true

Tracing is recorded even when the socket is opened by the background, not by the transaction.
async_stack_enabled Boolean

Default false

Set whether or not to use the active stack function for the background threads.
async_thread_match String

Set the background thread name for dumping the active stacks. To set multiple items, use comma (,) as the delimiter. When setting the name, you can use a comparison pattern using an asterisk (*), such as "Thread-*."
async_thread_parking_class String

Default sun.misc.Unsafe

If the top method of the stack is a class or method registered in async_thread_parking, the system considers that the thread is parked and does not generate any dump.
hook_service_patterns String

It sets the starting point pattern for tracing NON-Http transactions. Wildcard characters cannot be used. To set multiple values, use comma (,) as the delimiter.
hook_serivce_ignore_methods String

Among the settings in hook_service_patterns, unnecessary methods as the start point can be added.
hook_service_supers String

If the common denominator of the starting points for NON-HTTP transaction tracing inherits the method of a specific class, set the method of the common denominator. Enter the full path to the method. You can use wildcards ("*") and register multiple methods by using comma (,) as the delimiter.
whatap.conf
```
hook_service_supers=a.b.C.method,a.b.C.*
```
hook_service_interfaces String

Set this if the common denominator of the start points for non-HTTP transaction tracing has implemented a specific interface.
hook_service_access_public_enabled Boolean

Default true

When setting the transactions for the non-HTTP daemon process, it sets the access permission criteria to on or off only for public methods.
hook_service_access_private_enabled Boolean

Default true

When setting the transactions of the non-HTTP daemon process, it sets the access permission criterion to on or off only for private methods.
hook_service_access_protected_enabled Boolean

Default true

When setting the transactions of the non-HTTP daemon process, it sets the access permission criterion to on or off only for protected method.
service_name_mode String

Default full

You can use the following options with the transaction name.
- full: Full class name is used.
- class: The service name is used with the service name.
- method: The service name is used with the method name.
- string: The service name is used with the first parameter in the string.
- arg: Among parameters, the service name is used with the parameter of the index set in the service_name_index option.

Multiple transaction trace

The following options are used to trace and monitor cross-application calls. The options can help you understand the interactions between multiple applications. Various options provided allow you to fine-tune the behaviors for tracing multiple transactions.

mtrace_enabled Boolean

Default true

It sets whether or not to use the multi-transaction tracing (MTID). By tracing the MTID, you can check the calls between all the registered applications.
mtrace_rate Percentage

Default 10

With this option, you can set the rate of MTIDs issued when the first transaction occurs.
mtrace_caller_key String

Default x-wtap-mst

Set the caller key name to be used for MTID tracing.
mtrace_callee_key String

Default x-wtap-tx

Set the callee key name to be used for MTID tracing.
mtrace_send_url_length Int

Default 80

The HTTP caller passes its URL to the callee. At this time, the URL length is restricted. This sets the length value.
mtrace_callee_id_send_enabled Boolean

Default false

When tracing the MTIDs, the callee ID issued upon the HTTPC call is included in the trace.
mtrace_callee_id_recv_enabled Boolean

Default false

Upon MTID tracing, the received callee ID is represented in the trace.
mtrace_alltx_enabled Boolean

Default false

MTIDs of all transactions can be traced to link with the logging system like log4j.
mtrace_basetime Miliseconds

Default 100

If the value of mtrace_alltx_enabled is true, it may leave too many logs. In this case, it needs to reduce the amount of trace logging.
stat_mtrace_enabled Boolean

Default false

It collects correlation statistics between callers and callees. When applied to a caller, the caller details are sent. When applied to a callee, the caller-callee call statistics are sent to the collection server in URL units.

Trace data sampling

The following options are used to control sampling of trace data and set whether to transmit data. The options allow you to manage the performance and data transfer volume for applications.

Agent support scope: Java Agent v2.2.4 or later

trace_sampling_enabled Boolean

Default false

You can set whether or not to collect trace data samples.
trace_sampling_tps Int

Default 10000

You can set the trace data sampling count. The data exceeding the set count is not transmitted and is initialized every 5 seconds.
trace_send_enabled Boolean

Default true

You can set whether or not to transmit the trace data.
debug_trace_samling Boolean

Default false

You can turn on or off the trace data sampling debug option.

Modifying the trace URL name

hook_tx_name_patterns / hook_tx_name_mode string Java Agent v2.2.4 or later

You can modify the name of the trace URL when calling a specific URL or method. For example, if the test100000() method is called while calling a URL registered in io.home.test.TestController.test1, you can see it as /api/100000+test1+test100000 on the service screen.

The hook_tx_name_mode option allows you to select one of class, method, string, and return.
whatap.conf
```
# The full path of the call method and wildcard (*) can be used.
hook_tx_name_patterns=ab.cd.ef.GH.ij

# Select one of class, method, string, and return.
hook_tx_name_mode=method
```

Ignoring a specific exception

ignore_exception_tx_pattern String Java Agent v2.2.4 or later

You can configure a service to ignore specific exceptions. When registering multiple items, use a comma (,) as the delimiter.
whatap.conf
```
ignore_exception_tx_pattern=exception:service_url
# e.g. java.util.concurrent.TimeoutException:/api/test/timeout,org.springframework.web.util.NestedServletException:/api/posts/test/cexception
```

Tracing HttpURLConnection

The following options are used to trace HTTP calls by using the HttpURLConnection class.

HttpURLConnection Boolean

Default true

The option is used to trace methods in the HttpURLConnection class.
hook_HttpURLConnection_startup_enabled Boolean Java Agent v2.2.4 or later

Default false

You can set to trace methods in the HttpURLConnection class even when called for the first time.
HttpURLConnection_weblogic Boolean Java Agent v2.2.4 or later

Default true

In case of calling HTTP from Weblogic with HttpURLConnection, the option traces methods in the weblogic.net.http.HttpURLConnection class.
hook_HttpURLConnection_weblogic_startup_enabled Boolean Java Agent v2.2.4 or later

Default false

You can set to trace methods in the weblogic.net.http.HttpURLConnection class even when called for the first time.

Transaction Tracing​

Exceptional handling​

HTTP transaction tracing​

Non-HTTP transaction tracing​

Multiple transaction trace​

Trace data sampling​

Modifying the trace URL name​

Ignoring a specific exception​

Tracing HttpURLConnection​