Skip to main content

Transactions

Note

For more information about transaction, see the following. For example, see the following on the transaction analysis guide in case of using the hitmap.

Transaction Tracing​

While the transaction performance means the summary metrics or attributes between the start and end of transaction, the transaction profile traces the steps during transactions. If any transaction is slow or erroneous, the execution records must be traced step by step to find the cause. This is called transaction tracing.

The types of steps that WhaTap collects include SQL steps, HTTP call steps, message steps, socket open steps, DB connection steps, and method steps.

Note

WhaTap's step is used with the same meaning as Span.

  • DB connection step START-END

    It includes the performance for connection to RDB. Step information includes the name, response time, and error.

  • SQL Step START-END

    It includes the performance for JDBC SQL. Step information includes connection data, SQL statements, and errors.

  • HTTP Call step START-END

    It includes the performance for the outbound HTTP service calls. Step information includes URL, host, port, response time, and errors.

  • Message step ADD

    While collecting traces, the message steps are used to collect the records of all irregular sections.

  • SOCKET Step ADD

    Step to represent the socket open.

  • METHOD Step START-END

    The method response time is traced.

  • ACTIVE STACK Step START-END

    It includes the active stack information. It is created and collected by a separate thread and it is added to the transaction trace.

  • profile_step_normal_count Int

    Default 1000

    Set the default step count for tracing transactions.

  • profile_step_heavy_count Int

    Default 1020

    If the trace's default step count is exceeded, it limits the maximum heavy step count. In profile_step_normal_count, it counts the steps that are over profile_step_heavy_time. The steps with no response time are not collected.

  • 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 within profile_step_heavy_count.

  • profile_basetime MiliSecond

    Default 500

    Transaction 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.

  • query_string_enabled Boolean

    Default false

    It enables the function to collect query strings for transaction URLs.

  • query_string_urls String

    It registers the URLs to collect query strings for transactions. To register multiple items, comma (,) is used as the delimiter.

  • hook_method_patterns String

    Use this when measuring the response time of a specific method. Use the values in the [MODULE_NAME]:[CLASS_NAME].[FUNCTION_NAME] or [MODULE_NAME]:[FUNCTION_NAME] format. Multiple method patterns can be set using comma (,) as the delimiter. All classes for a module or all modules for a class can be traced using asterisk (*).

    Note

    • The methods registered through this option can be checked through the Method step in Hitmap, Trace analysis, or Transaction information window.

    • Because tracing all modules may incur overhead, it is recommended to use accurate module and method names if possible.

  • trace_error_callstack_depth Int

    Default 50

    Set the maximum number of call stack lines when collecting error call stacks for transactions. This data can be viewed from the error statistical data.

  • trace_active_callstack_depth Int

    Default 50

    Set the maximum number of call stack lines when collecting active stacks for transactions.

  • trace_active_transaction_slow_time MiliSecond

    Default 3000

    Set the response criteria in the slow section of the active transaction's arc equalizer.

  • trace_active_transaction_very_slow_time MiliSecond

    Default 8000

    Set the response criteria in the very slow section of the active transaction's arc equalizer.

  • trace_active_transaction_lost_time MiliSecond

    Default 300000

    Timeout waiting for a transaction to end. If a transaction does not end within 5 minutes, no further transaction data is collected.

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.

  • profile_http_header_enabled Boolean

    Default false

    The HTTP header's content is output in the transaction trace. This setting is used to expose headers to the transaction trace regardless of whether headers are collected or not.

  • profile_http_parameter_enabled Boolean​

    Default false

    Set it to true to record HTTP parameters in the trace history. However, the parameters can be retrieved only by entering a separate security key. Set the security key to 6 digits in paramkey.txt of the agent installation path. If paramkey.txt does not exist, it is automatically generated and a random key is set.

  • 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

    The transaction URLs are parsed and normalized. It deletes the path parameters by 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. Using /a/*/b, you can collect after deleting the path parameter with a specific format.

  • web_static_content_extensions(*) String

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

    Specify the extension to determine the static content. Transactions with extensions set here are excluded from transaction tracing and counting.

  • 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

    Set the URL prefix for excluding transactions during collection. Any URLs whose prefix matches the set value do not collect the transaction performance.

    Note

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

  • trace_useragent_enabled Boolean

    Default false

    If the value is true, the user agent data for transactions is collected.

Non-HTTP transaction tracing​

  • Transaction end point

    The end point is the start method of the transaction. In case of the HTTP transaction, HttpServlet.service() or Filter.doFilter() is the start point of transaction, and this point is called "transaction end point."

  • Non-HTTP tracing

    The performance from the start to the end of the method specified as the transaction end point, is called "transaction performance." To trace non HTTP transactions, be sure to specify the end point.

    Note

    Finding the end point

    1. Set the transaction trace for all methods where transactions are supposed to be called.
    2. After restarting, trigger a transaction for monitoring.
    3. Turn on the back stack option to pinpoint the entry method.

Selecting the target​

  1. Method Trace Setting

    Set the method trace. Be sure to specify a class that is called in transactions. The JDBC driver is useful for the programs that use the database.

    whatap.conf
    hook_method_patterns=jdbc.*.*
    hook_method_access_public_enabled=true
    hook_method_access_protected_enabled=true
    hook_method_access_none_enabled=true

  2. Transaction start option setting

    Start a transaction when the method is called. Turn on the transaction start option and the option to dump the stack at the start of a transaction.

    whatap.conf
    trace_auto_transaction_enabled=true
    trace_auto_transaction_backstack_enabled=true

  3. Trace analysis after restart

    Restart it. After calling the service, you can see the transaction being traced.

    If you view the transaction, you can see that the methods of all classes starting with jdbc.* appear in this transaction. If you view the transaction trace, you can see the message step called TRANSACTION BACKSTACK.

    TRANSACTION BACKSTACK
    jdbc.FakePreparedStatement.executeQuery(FakePreparedStatement.java),
    com.virtual.dao.SelectDAO.execute2(SelectDAO.java:29),
    com.virtual.web.SimulaNonHttp.execute(SimulaNonHttp.java:147),
    com.virtual.web.SimulaNonHttp.process(SimulaNonHttp.java:76),
    com.virtual.web.SimulaNonHttp.run(SimulaNonHttp.java:100)

  4. Check Stack Content

    By checking the stack content, you can infer which method the transaction is departing from.

    Example
    com.virtual.web.SimulaNonHttp.execute(SimulaNonHttp.java:147),
    com.virtual.web.SimulaNonHttp.process(SimulaNonHttp.java:76),
    com.virtual.web.SimulaNonHttp.run(SimulaNonHttp.java:100)

    One of the above three methods can be determined as the start point of a transaction. In this situation, perform reverse compilation to determine the appropriate transaction end point.

    Looking at the logic, while() runs within SimulaNonHttp.run, SimulaNonHttp.process() is called, and then SimulaNonHttp.execute() is run. We can guess that process() is appropriate. This part must be determined by looking at the source.

    Tip

    The most important criterion for end point is that it must be ended. Under normal circumstances, it must terminate immediately without any delay so that the performance evaluation can be made.

Setting the end point of transaction​

  1. Set the transaction start point as follows:

    whatap.conf
    hook_service_patterns=com.virtual.web.SimulaNonHttp.process

  2. Restart the application.

The process() method becomes the end point of a new transaction.

Note

For the hook_service_patterns option, wildcard characters cannot be used. To set multiple values, use comma (,) as the delimiter.

Defining the transaction name​

Generally, transactions are identified by the method name.

whatap.conf
service_name_mode=[full,class,method,string,arg]
service_name_index=0

  • service_name_mode

    You can specify any of 5 options: full, class, method, string, and arg.

    • full: The full class name is used as the service name.

    • class: The class name is used as the service name.

    • method: The method name is used as the service name.

    • string: The first parameter in the text string is used as the service name.

    • arg: Among parameters, the parameter of the index specified in the service_name_index option is used as the service name.

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_rate Percentage

    Default 0

    This option sets the rate of the MTID (Multi Transaction ID) issued when the first transaction occurs. By tracing MTIDs, the calls between all registered applications can be checked. Through the Caller & Callee function, the transaction trace can be viewed for the applications that belong to the same project.

  • mtrace_spec String

    Default: v1

    Set the application version of the current instance. You can arbitrarily set a string. This data is used for call statistics.

  • mtrace_send_url_length Integer

    Default 80

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