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:

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: myonlineshopping.com

Note: 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

Example: mymachine.mydomain.com



  • 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:
    • proxy.server.host: 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 www.apdex.org
  • 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 specified package names, by default will be included for instrumentation and you need not repeat this in custom_instrumentation.conf



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

  • application.name
  • apm.host
  • apm.port
  • agent.server.port
  • apminsight.log.dir
  • apminsight.log.level (only in java agent. Whereas, in .NET agent, this property 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: http://apdex.org/overview.html

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.

Note: 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.

Java Agent provides two ways to custom instrument your application:

1. Using Configuration File

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

Fully/qualified/ClassName : 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/.* :


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

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

2. Using JAVA Annotations

Using Java annotations, APM Insight provides an easier way to custom instrument your application classes and methods. Usage of Java annotation enables you to define custom names for the transaction and also assign a custom component.

Note: This feature is available from agent version 2.2


  • Download the apminsight-javaagent.zip file which includes agent jar with its associated files along with the apminsight-javaagent-api.jar
  • Include the apminsight-javaagent-api.jar file to the project build path. Make sure the jar file is exported along with the application's libraries.

There are two annotations that can be used to custom instrument:

ApmTracker - Can be used upon any classes and methods, which will be instrumented and included in the traces.

ApmRootTracker - Can be used upon the methods which are likely to be starting point of transaction execution.


This annotation can be used on Classes and Methods. When used upon a class, the attributes are applied for all the methods in that class. It will override the method-wise annotations.


component- Default Value: POJO (Plain Java Object)

Defines a component name for the annotated element. Its an optional attribute.


Case 1: Usage on Class

public class Category {
Case 2:

public class PaymentProcessor {

Case 3: Usage on Methods

public class Product {
public int getPrice(String product, String brand) {

private List fetchAllBrandsList(String product) {


This annotation can be used only on methods. If annotated method is the first method invoked on the server for processing the transaction, then the transaction is re-named using the value of the txnName attribute. Else, it is considered to be a normal method call and included in the traces.


txnName - Mandatory attribute.

Value of this attribute is used to name the transaction that invoked the ApmRootTracker annotated method.

component - Default Value: POJO

Defines a component name for the annotated element. Its an optional attribute.


public class AppService {
public void init() {

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,
    • aspsite/account/~=account - The above pattern will match with all transactions which start with aspsite/account/ and it will be renamed as account.
    • aspsite/~/basicdetails=basicdetails - The above pattern will match with all transactions which start with aspsite/ and end with /basicdetails. They will be renamed as basicdetails.
    • ~/educationdetails=educationdetails - The above pattern will match with all transactions which end with /educationdetails and it will be renamed as educationdetails.
  4. Copy this transaction_merge_patterns.conf file and paste it in the following location.
    • %WINDIR%ProgramDataDotnetAgent (for 64-bit agent) - For Windows server 2003, the corresponding path will be in %WINDIR%Documents and SettingsAll UsersApplication DataDotNetAgent
    • %WINDIR%ProgramDataDotnetAgent (for 32-bit agent) - For Windows server 2003, the corresponding path will be in %WINDIR%Documents and SettingsAll UsersApplication DataDotNetAgent
    • In case of multi-monitors, all sub folders for every application in the above locations.
  5. We can add, remove or comment the patterns at any point of time in the configuration file.
Note: 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

  • Shutdown the Application Server to which the agent is plugged in.
  • Create a new file named "transaction_merge_patterns.conf" in the directory where the apminsight.conf exists.
  • Open the file in a text editor and specify key value pairs as per below syntax.
  • Regular expression of URLs/web transaction=new name to be assigned.
  • Start the Application Server, all transactions performed from now, will use the above defined patterns to merge the transactions


You have Web transaction URLs:

ebay/shop/user/4534634 ebay/shop/user/1380284

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