ManageEngine® Applications Manager

APM Insight Agent Configuration Options

<< Prev


Next >>

APM Insight Agent Configuration Options


This page should help you tune the configuration for tracking web based transactions. These settings can be configured in apminsight.conf file. Make sure that this file is present in the folder where you have deployed the APM Insight agent.

The following table explains all the configurations:




Default Value*

  • Specify the desired Application's Name to show in Applications Manager
  • If there are multiple instances of your application and you would like to group them, then specify the same application name in all installed APM Insight Agent Configuration files.




With the APMInsight Java agent, you have the option to configure the application name through JVM arguments instead of configuring it in the apminsight.conf file. Add the following parameter:

My Application*

  • Host Name where the Applications Manager is running.
  • If an invalid/ unreachable host names is entered, the agent throws a 'Connection Refused' Exception and will retry until the correct host name is entered in apminsight.conf.
  • It accepts either the host name or an Ipv4 address




  • Specify true if the data to the Applications Manager should be sent through HTTPS Protocol.
  • If false, data will be sent through HTTP Protocol



  • Specify the HTTP Port of the Applications Manager. If apm.protocol.https is true, specify the HTTPS Port.
  • If the service is not running in the specified port, the agent throws a 'Connection Refused' Exception and will retry until the correct port is entered in apminsight.conf.

Example: 9090



  • Specify weather the Agent installed Application Server is under a proxy network.
  • If set True, Proxy credential information should be given in order to send the metric data from the agent to Applications Manager.
  • If behind.proxy is set to true, specify values for the following keys:
    • Host name of the proxy server
    • proxy.server.port: Proxy server's port
    • proxy.auth.username: User name of the proxy server
    • proxy.auth.password: password for the proxy server



  • Specify the HTTP listening port of the Application Server.
  • It will be useful to distinguish Instances when more than one Application Server runs in same host.Example: 8080


  • Application Performance Index (simply called Apdex) is measurement of an Application's Performance ranging from 0 to 1.
  • Detailed information about Apdex can be found at
  • If any transaction response time scores values below the apdex.threshold value, the transaction is labeled as Satisfied.
  • If any transaction response time scores above four times the apdex.threshold, the transaction is labeled as Frustrated.
  • If it is exactly equal to apdex.threshold or in between satisfied and frustrated threshold value it is labeled as Tolerating.

0.5 (Second)


  • Enabling this option will listen to all SQL Queries which gets executed.
  • If this option is disabled, no Database Metrics will be collected.



  • Enabling this option will construct Trace for Slow Transactions.
  • You can view the traces collected in Applications Manger APM Insight Page by selecting Traces tab



  • Trace of any transaction whose response time scoring above the specified threshold value will be collected, provided if transaction.trace.enabled is set to true.
  • The trace can be used to analyze, troubleshoot the transaction working.

2 (Seconds)


  • Enabling this option will parametrize all SQL Queries in Slow Transaction Traces. (if sql.capture.enabled set to true & transaction.trace.enabled set to true)
  • Disabling this option will give you the real query (with parameters).
  • It is recommended to enable this option if there are queries getting executed using confidential parameters like credit card number, passwords, etc.



  • Enabling this option will collect the stacktrace whenever any sql query executed above this threshold time value.

3 (Second)


  • Enabling this option captures parameters of all GET & POST web requests
  • To skip capturing specific parameters use webtransaction.trace.input.params.ignore key
  • Captured parameters can be viewed by selecting the required transaction in Traces tab



  • To skip capturing specific web request parameters like password, PIN or any confidential values, specify those parameter names for this key
  • Use comma(,) to separate multiple entries. Values specified for this key are case-sensitive
  • If no value is specified, all request parameters will be recorded

password, authKey


  • To display complete URL of web transactions, use webtransaction.naming.use.requesturl=true in the apminsight.conf file. This is a hidden configuration and it's default value is false.



  • To specify encoding charset when handling application data, use webtransaction.encoding.charset=Windows-1252 in the apminsight.conf file. It's default value is UTF-8



  • Web transactions of the specified URL patterns will be skipped while tracking
  • Use comma(,) to separate multiple entries
  • For ex: transaction.skip.listening=*.jpeg, will skip listening to transactions ending with .jpeg

*.css, *.js, *.gif, *.jpg, *.jpeg, *.bmp, *.png


  • A kind of sampling. If said 20, APM Insight will only track request after every 20 requests of same kind. i.e it will track 1st, 21st, 41st.. request of its kind.
  • The request count maintained will be reset after every one minute.

1 (request)


  • By default, APM Insight groups transaction into different components like STRUTS, SERVLET, MYSQL, etc.
  • Custom components can be added by specifying the package name in below mentioned format : packagename/.*:Component_Name
  • All packages and classes under the specified package will be grouped into specified component
  • For Ex: include.components=com/test/custom/.*:CUSTOM, all packages and classes under the package com/test/custom/ will be grouped into CUSTOM component
  • Use comma(,) to separate multiple entries

Note: The package names, by default will be included for instrumentation and you need NOT give this in include.package separately



  • Directory path where the APM Insight log should be stored.
  • Use forward slash(/) as path separator
  • example: D:/apminsight/
  • Defaults to the directory where APM Insight agent jar is installed if commented or mentioned incorrectly or unable to create the configured directory.


  • The log level at which the APM Insight agent should record information.
  • Supported levels are SEVERE,WARNING, INFO and FINE.

INFO (level)


  • Enabling this option agent will automatically download and install the latest available version


APM Insight will use its default factory value, if any invalid value specified for an option. Other than options listed below, all the other options can be changed at run time.


Options marked with a * are mandatory. If any of the mandatory entries are not provided, the Agent cannot be initialized / started. However the Application Server (where the Agent is deployed) will start normally.
For more detailed information about APDEX threshold go to :


Tracking Background Transactions

Apart from web transactions, most applications run background tasks to perform various tasks like maintenance, schedulers, messaging, etc. APM Insight also captures these transactions and list them under Background tab in APM Insight dashboard.



This feature is available in .Net & Java agents only

For the agent to track background transactions, it has to be enabled in background_transaction.conf file. Configuration for background transactions is explained below.


Configuration Description Default Value

  • Enabling this option, APM Insight agent starts tracking background transactions
  • All transactions other than HTTP are considered as background transactions

  • Enabling this option, the agent collects traces for slow background transactions, provided bgtransaction.tracking.enabled is set to true



  • Traces will be collected for background transactions whose response time have crossed the specified threshold value, provided bgtransaction.trace.enabled is set to true.

5 (seconds)


  • Sampling factor for background transactions

  • If value is set to 1, agent tracks every transaction. If value is set to n, agent tracks 1 in N transactions of same kind.

1 (request) for Java & 5 for .Net agent


  • These values cannot be changed during run-time for java agent. For the changes to be effective, server restart is required.
  • Restart is not required servers using .Net agent, the values will be updated in run-time.

Custom Instrumentation

APM Insight agent instruments predefined classes of several Web Components and Frameworks to provide insight into the application. APM Insight also provides an option to custom instrument, classes of your choice. Custom instrumentation helps in providing wider insight into applications, where it will be easier to track performance of specific features or modules in the application.

Configuration Steps for Java Agent


To instrument classes of your choice, specify the class name in 'custom_instrumentation.conf' file, as per format specified below.

Fully qualified class name : Methods to be instrumented

Use comma(,) as method separator for multiple entries. If methods to be instrumented is left blank, all methods under the specified class will be instrumented. If there exists, overloading methods that needs to be instrumented, all the overloaded methods will be instrumented. Each class entry must be given in a new line.


a/b/c/CustomClass : methodA, methodB

a/b/c/CustomClass :

If all classes in a package needs to be instrumented, specify the package name as described below.

package_name/.* :

Example: a/b/c/.* :

It is not recommended to specify packages as input, as the agent will instrument all methods in all classes and all packages under it. These may cost extra overhead in CPU and memory usage. Also, there will be many methods that are of least interest and also these makes the traces lengthy. Although it can be used to study the code flow.


It requires a application server restart for the changes to be effective

Grouping Similar Transactions

Dynamic Transaction names are becoming more familiar with lots of applications, making it difficult to actually track the performance of the application. Dynamic transactions are web transactions within an application having single URL but get appended with unique alpha numeric identifiers every time they are invoked, making the web transaction name itself look different. Tracking such individual URLs is a herculean task. Here, this feature of grouping similar transactions, will help to group these dynamic transactions into the actual URL that needs to be monitored.

Configuration Steps for .Net Agent


Open Edit configuration UI, select Transactions Merge tab and add the transaction patterns you want to merge (illustrated in manual step 3.).

To do it manually do the following steps:

  1. Go to the APM Insight .NET Agent installation folder after installing the agent.

  2. Open DotNetAgent folder.

  3. Open transaction_merge_patterns.conf and add the patterns as mentioned in the below sample,

  4. Copy this transaction_merge_patterns.conf file and paste it in the following location.

  5. We can add, remove or comment the patterns at any point of time in the configuration file.


Service restart is not required to take effect of this configuration change.

The changes will be affected in the next minute onwards.


Configuration Steps for Java Agent


You have Web transaction URLs:







How to specify in transaction_merge_patterns.conf






Configuration Steps for Ruby Agent

  1. Create a new file named "transaction_merge_patterns.conf" in the directory where apminsight.conf file resides in your application.

  2. Open the file in any text editor and specify key value pairs as per syntax given below

    Regular expression of URLs=new_name_to_be_assigned

  3. Start or restart the rails server, all transactions performed from now, will use the above defined patterns to merge the transactions







<< Prev


Next >>

APM Insight .NET Agent

APM Insight Dashboard