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.
NoteTo collect errors regardless of the
profile_basetime
option, set theprofile_concern_error_enabled
option totrue
. If set to the default value offalse
, 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 asprofile_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 asprofile_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.confhook_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.confhook_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.
CautionStack 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
orprofile_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.
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.BizExceptionTipError class collection/Hitmap display level: Includes the INFO (blue)/error statistics.
NoteIn 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:200TipError 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.BizExceptionTipIgnore 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,500TipIgnore 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:500TipIgnore 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).NoteFor 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,500TipIgnore 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 forHTTPC_URL
.whatap.conf# example
httpc_status_url_ignore_set=a/b/c:404,d/e/f:500TipIgnore 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 performbiz_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.
NoteIf 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.
NoteFor example, if declared as
/a/{v}/b
,a/123/b
is replaced bya/{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, theparamkey
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 withparamKey
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.
NoteIt 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
andHttpServletResponse
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.
NoteThe 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.
NoteThe 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,HEADNoteThe 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.NoteThis 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 istrue
, 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.confhook_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 theservice_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
istrue
, 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 inio.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.confignore_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 theweblogic.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.