ManageEngine® Applications Manager

APM Insight Agent Configuration Options

<< Prev


Next >>

APM Insight Agent Configuration Options


APM Insight Agent works based on the values 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:


Configuration Description 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.
  • Example:

  • Host Name where the Applications Manager is running.

  • If an invalid/ unreachable host names is entered, the agent throws a 'Connection Refused' Exceptionand 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
Default value: false
  • 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

Default value: false

* agent.server.port
  • 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.
Default value: 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.
Default value: true
  • 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.

Default value: true
  • 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.

Default value: 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.
Default value: true
  • Enabling this option will collect the stacktrace whenever any sql query executed above this threshold time value.
Default value: 3 (Second)
  • APM Insight does not instrument all the classes loaded. APM Insight itself has a predefined list and only those classes will be instrumented.

  • If you need to instrument any of the other classes, you can achieve this by specifying the package name of the class.

  • Use Comma to separate multiple entries
  • For eg., include.packages=com/test/customimpl/.* will include all the packages & classes that start with com.test.customimpl

  • A kind of sampling. If said 20, apminsight 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.
Default value: 1 (request)
  • Directory path where the APM Insight log should be stored.

  • Use forward slash(/) as path separator
  • example: D:/Tomcat6.0/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.
Default value: INFO (level)

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.

The following configurations are not supported for .NET agent:



Options marked with a * are mandatory. If any of the mandatory files 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 → Add 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