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.

The agent traces the transaction performance and provides the following configurable options.

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_error_step_enabled Boolean

  Default true

  You can add a step to display error information in the profile.

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

  Example

  hook_method_patterns=a.b.C1.*
  Note

  • The methods registered through this option can be checked through the Method step in Hitmap, 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_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_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_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_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.

• trace_service_port_enabled Boolean

  Default false

  Add the port number to the transaction name.

• profile_zip_enabled Boolean

  Default false

  The compressed profile information is transmitted.

Exceptional handling

The following are options for managing and monitoring exceptions that occur in applications. You can set whether to ignore specific exceptions or treat them as errors if the HTTP status code is an error. The exception-handled items appear as normal transactions in the Hitmap or Trace analysis window.

• httpc_status_ignore String

  If the HTTP status code is an error (HTTPC_ERROR), it can be ignored. When listing multiple values, use comma (,) as the delimiter.

  whatap.conf

  httpc_status_ignore=404,500
  Tip

  Ignore HTTP status error code/Exclude error statistics

• httpc_status_ignore_set String

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

  Set it as httpc_status_ignore_set=/a/b/c:400,/a/ab/c:404. In Statistics/Error Analysis, enter the value for HTTPC_URL.

  whatap.conf

  httpc_status_ignore_set=/a/b/c:400,/a/ab/c:404
  Tip

  Ignore HTTP status error code/Exclude error statistics

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 Node.js Agent 0.4.95: 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.

  • Node.js Agent 0.4.95 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.

• 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_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.

• profile_http_header_ignore_keys String

  Default Cookie,cookie,accept,user-agent,referer

  You can specify HTTP header names to exclude from collection. The set HTTP header names are excluded from collection, and they are marked with "#."

• profile_http_parameter_keys String

  Only the parameter corresponding to the set key is recorded. To register multiple items, use comma (,) as the delimiter. If not specified, all parameters are recorded.

• 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

• status_ignore_set String

  Among HTTP status return codes, you can set the codes to ignore on a URL basis.

  whatap.conf

  # example
  status_ignore_set=/api/test/timeout/{time}:408,/error:500

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

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.

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

• trace_background_socket_enabled Boolean

  Default true

  When a socket (TCP) connection is opened, this open is traced only in transaction start status. This tracing is made when the socket is opened by a background thread rather than a transaction.

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 Int

  Default 0

  This option sets the rate of the MTID (Multi Transaction ID) issued when the first transaction occurs. It can be set from 0 to 100. By tracing the MTID, you can check calls between all registered applications. For the applications belonging to the same project, you can check transaction traces immediately through the Caller & Callee function.

• mtrace_spec String

  Default: v1

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

• 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_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: Node.js Agent v0.4.94 or later

Note

Added the Socket.io monitoring module in Node.js agent version v0.4.94. You can see the sampled data with the trace_sampling_enabled and trace_sampling_tps options. Disable tracing by adding the /socket.io path to the trace_ignore_url_prefix option.

• trace_sampling_enabled Boolean

  Default true

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

• trace_sampling_tps Number

  Default 1000

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