Schedule demo

Java Agent Configuration Options


The APM Insight Java agent provides configuration options to control transaction tracking, trace collection, data capture, and other monitoring settings. You can modify these settings either through the Web Client or directly in the apminsight.conf file. This page describes the available settings, their configuration keys, and their default values.

Configuring settings through the Web Client

You can modify the Java agent configuration settings from the APM Insight agent configuration profile in the Web Client. Use the edit option to view and update the available settings.

Applications Manager Java Agent Configuration Options: Editing Java agent configuration settings

The configuration settings are grouped into the following sections:

Note: A red asterisk (*) indicates that the corresponding default value applies to Applications Manager versions later than 16470.

Basic configuration settings

NameKeyDescriptionDefault value
Capture database SQL Queriessql.capture.enabled
  • When enabled, the agent captures SQL queries executed by the application. If disabled, database metrics are not collected.
True
Obfuscate SQL Parameterstransaction.trace.sql.parametrize
  • When enabled, the agent parameterizes SQL queries in slow transaction traces. This setting applies when both sql.capture.enabled and transaction.trace.enabled are set to true.
  • When disabled, the original queries, including their parameter values, are captured. Enable this option to help prevent confidential values, such as credit card numbers and passwords, from appearing in transaction traces.
True
Stack trace threshold for SQL queries in transaction tracestransaction.trace.sql.stacktrace.threshold
  • When a SQL query takes longer than the configured threshold, the agent captures its stack trace.
3 seconds
Display instance port numbershow.instance.port.number
  • When enabled, the port number of each application instance is displayed.
True
Logging levelapminsight.log.level
  • The log level at which the APM Insight agent should record information. Supported levels are SEVERE, WARNING, INFO and FINE.
INFO
List of URL extensions to be skipped from trackingtransaction.skip.listening
  • Specifies URL patterns for web transactions that the agent should exclude from tracking. Separate multiple entries with commas. For example, transaction.skip.listening=*.jpeg excludes transactions with URLs ending in .jpeg.
*.css, *.js, *.gif, *.jpg, *.jpeg, *.bmp, *.png, *.ico
List of exceptions to be skipped from trackingexceptions.ignore
  • Specifies the exceptions that the agent should exclude from tracking.
None
Skip Transactionstransaction.skip.patterns
  • Specifies regular expression patterns or transaction names to exclude from tracking. Separate multiple entries with commas.
None
Show Method Description in Traces 
  • When enabled, the class name is captured and displayed in the trace details.
True
Enable Loop detectiontransaction.trace.track.loopWhen enabled, the agent captures loops running in the application.false
Enable Smart Samplingsmart.sampler.enabledWhen enabled, the agent automatically adjusts the sampling factor based on the Java process's CPU and memory consumption.true
Include Async in Total Response Timert.include.async.timeWhen enabled, the response times of asynchronous calls are included in the transaction's total response time.true
Capture JVM Metricscapture.jvm.metricsWhen enabled, the agent collects Java Virtual Machine (JVM) performance metrics.true
Exclude Grouping in Transaction Namestransaction.keyword.skip.grouping
  • Specifies keywords that should be preserved when transaction names are grouped.
    • Example keywords: v1, v2, index1, and index2.
    • For example, api/v2/web3/index2.html and api/v1/web3/index1.html are grouped as api/v2/*/index2.html and api/v1/*/index1.html, respectively.
    • The specified keywords are preserved, while other dynamic URL segments are replaced with a wildcard (*).
None
JVM polling frequencyjvm.polling.intervalFrequency (in minutes) at which JVM metrics are collected by the agent.5 minutes

Web transaction settings

NameKeyDescriptionDefault value
Transaction performance and sampling
Apdex Thresholdapdex.threshold
  • Application Performance Index (Apdex) measures application performance on a scale from 0 to 1.
  • For more information about Apdex, visit www.apdex.org.
  • Transactions with response times below the Apdex threshold are classified as Satisfied.
  • Transactions with response times above four times the Apdex threshold are classified as Frustrated.
  • Transactions with response times equal to the Apdex threshold or between the Satisfied and Frustrated ranges are classified as Tolerating.
0.5 seconds
Sampling factortransaction.tracking.request.interval
  • Specifies the proportion of requests of the same kind that APM Insight tracks. For example, if set to 5, the agent tracks 1 in every 5 requests.
1 request or 10 requests*
Transaction tracing
Enable transaction tracingtransaction.trace.enabled
  • When enabled, the agent collects traces for slow transactions. You can view the collected traces in the Traces tab of the APM Insight monitor.
True
Transaction tracing thresholdtransaction.trace.threshold
  • The agent collects traces for transactions whose response times exceed the configured threshold, provided transaction.trace.enabled is set to true. Use these traces to analyze and troubleshoot transaction performance.
2 seconds or 5 seconds*
Capture trace if external calls exceedswebtransaction.trace.external.components.count.threshold
  • The agent captures a trace snapshot for an HTTP request when the number of calls to external components, such as MySQL and Memcached, meets or exceeds the configured threshold.
50 calls
Capture traces for unique executionstransaction.trace.unique.execution
  • When enabled, the agent captures traces for unique executions.
FALSE
Capture CPU time per transactionwebtransaction.record.cputime.enabled
  • When enabled, the agent records CPU time for each HTTP request.
True
Capture memory allocation per transactionwebtransaction.record.memory.allocation.enabled
  • When enabled, the agent captures memory allocations for web transactions.
2 (seconds)
HTTP request data
Capture HTTP parameterswebtransaction.trace.input.params.record
  • When enabled, the agent captures parameters from GET and POST requests.
  • To exclude specific parameters, configure webtransaction.trace.input.params.ignore.
  • To view captured parameters, select the relevant transaction in the Traces tab.
False
List of HTTP parameters to ignorewebtransaction.trace.input.params.ignore
  • To exclude specific web request parameters, such as passwords, PINs, or other confidential values, specify their names for this key.
  • Separate multiple entries with commas. Parameter names are case-sensitive.
  • If no value is specified, all request parameters are recorded when parameter capture is enabled.
password, pswd, pass, authKey, parentId, parentID, resourceId, resourceID, id, ID
List of HTTP error codes to be ignored from trackinghttp.errors.ignore
  • Specifies HTTP error codes, such as 400, 401, and 500, that the agent should exclude from tracking.
None
List of HTTP error codes to be trackedhttp.errors.track
  • Specifies HTTP error codes, such as 400, 401, and 500, that the agent should track.
None
Capture HTTP bytescapture.http.network.bytes
  • When enabled, the agent captures the number of bytes sent and received in network requests.
True
Transaction grouping and filtering
Web Transaction Tracker Drop Thresholdwebtransaction.tracker.drop.threshold
  • Specifies the response-time threshold below which trackers are dropped.
10 milliseconds
Group similar transactions by positiontransaction.grouping.by.position
  • Groups similar transactions under a single transaction based on their position, making them easier to monitor.
  • Input format: Transaction [*a-zA-Z0-9_/.,-:] : Position [0-9] : Group Name [a-zA-Z0-9_]
None
HTTP headers and external call data
Capture HTTP request headerswebtransaction.trace.request.headers.record
  • When enabled, the agent captures HTTP request headers for the trace.
False
Capture HTTP response headerswebtransaction.trace.response.headers.record
  • When enabled, the agent captures HTTP response headers, which you can view in the Trace Details tab.
FALSE
List of HTTP Response Headers to be ignoredwebtransaction.trace.response.headers.ignore
  • To exclude specific HTTP response headers from capture, specify their names for this key.
  • Separate multiple entries with commas. Header names are case-sensitive.
  • If no value is specified, all HTTP response headers are captured.
password, pswd, pass, authKey, parentId, parentID, resourceId, resourceID, id, ID
Capture external call request headerswebtransaction.trace.ext.request.headers.record
  • When enabled, the agent captures external request headers, which you can view in the Trace Details tab.
FALSE
List of External Request Headers to be ignoredwebtransaction.trace.ext.request.headers.ignore
  • To exclude specific external request headers from capture, specify their names for this key.
  • Separate multiple entries with commas. Header names are case-sensitive.
  • If no value is specified, all external request headers are recorded.
password, pswd, pass, authKey, parentId, parentID, resourceId, resourceID, id, ID
Capture external call response headerswebtransaction.trace.ext.response.headers.record
  • When enabled, the agent captures external response headers, which you can view in the Trace Details tab.
FALSE
List of External Response Headers to be ignoredwebtransaction.trace.ext.response.headers.ignore
  • To exclude specific external response headers, such as those containing passwords, PINs, or other confidential values, specify their names for this key.
  • Separate multiple entries with commas. Header names are case-sensitive.
  • If no value is specified, all external response headers are recorded.
password, pswd, pass, authKey, parentId, parentID, resourceId, resourceID, id, ID

Background transaction settings

NameKeyDescriptionDefault value
Track background transactionsbgtransaction.tracking.enabled
  • Enabling this option, the APM Insight agent starts tracking background transactions
  • All transactions other than HTTP transactions are considered background transactions.
True
Capture background transaction tracesbgtransaction.trace.enabled
  • When enabled, the agent collects traces for slow background transactions, provided bgtransaction.tracking.enabled is set to true.
True
Transaction trace thresholdbgtransaction.trace.threshold
  • The agent collects traces for background transactions whose response times exceed the configured threshold, provided bgtransaction.trace.enabled is set to true.
5 seconds
Capture trace if external calls exceedsbgtransaction.trace.external.components.count.threshold
  • The agent captures a trace snapshot for a background transaction when the number of calls to external components, such as MySQL and Memcached, meets or exceeds the configured threshold.
50 calls
Capture CPU time per transactionbgtransaction.record.cputime.enabled
  • When enabled, the agent records CPU time for each background transaction.
False
Capture memory allocation per transactionbgtransaction.record.memory.allocation.enabled
  • When enabled, the agent captures memory allocations for background transactions.
True
Sampling factorbgtransaction.tracking.request.interval
  • Specifies the sampling factor for background transactions.
  • If set to 1, the agent tracks every transaction. If set to n, it tracks 1 in every n transactions of the same kind.
1 request

Settings available only in apminsight.conf

The following settings are available only in the apminsight.conf file and cannot be modified through the Web Client.

NameKeyDescriptionDefault value
Application Nameapplication.name
  • Specifies the application name displayed in Applications Manager.
  • To group multiple instances of an application, specify the same application name in the apminsight.conf files of all the corresponding APM Insight agents. For example: myonlineshopping.com.
True
Capture traceslicense.key
  • Specifies the API key associated with the user.
  • You can find this key on the APM Insight home page after logging in.
  • Copy the key and paste it as the value for this parameter.
  • This key is user-specific. Do not share it with others.
none
Configure Proxybehind.proxy
  • Specify whether the application server where the agent is installed is behind a proxy.
  • If set to true, provide the proxy credentials required for the agent to send metric data to Applications Manager.
  • If behind.proxy is set to true, configure the following keys:
  • proxy.server.host: Host name of the proxy server.
  • proxy.server.port: Port number of the proxy server.
  • proxy.auth.username: User name for proxy authentication.
  • proxy.auth.password: Password for proxy authentication.
False
Host detailsapm.host
  • Specify the Applications Manager host name and port in URL format. For example: https://apm-server:9090.
  • The agent uses this URL to send data to the corresponding Applications Manager instance.

For a failover setup, specify both the primary and secondary host details in the apm.host field. For example: apm.host=https://primary-server:8443,https://secondary-server:8443.

None
Agent Server Portagent.server.port
  • Specify the port number on which the application is running.
  • Each port number is treated as an individual instance and is grouped under the same application name.
80
APM Directory pathapminsight.log.dir
  • Specifies the directory where APM Insight agent logs are stored.
  • Use forward slashes (/) as path separators.
  • Example: D:/apminsight/.
  • If this parameter is commented out, contains an invalid path, or the configured directory cannot be created, the agent uses the directory where its JAR file is installed.
  • This parameter is available in apminsight.conf and is commented out by default.
  • Use the following formats to configure this parameter on Windows and Linux:
    Windows: D:/Tomcat/APMInsight/logs 
    Linux: /home/apps/APM/APMInsight/logs
 

Loved by customers all over the world

"Standout Tool With Extensive Monitoring Capabilities"

★★★★★

It allows us to track crucial metrics such as response times, resource utilization, error rates, and transaction performance. The real-time monitoring alerts promptly notify us of any issues or anomalies, enabling us to take immediate action.

Reviewer Role: Research and Development

carlos-rivero
"I like Applications Manager because it helps us to detect issues present in our servers and SQL databases."
Carlos Rivero

Tech Support Manager, Lexmark

Trusted by thousands of leading businesses globally