Configuring User Name and Business Context
As part of detailed diagnosis, eG BTM displays two columns, namely - User Name and Business Context. By default, these two columns will not display any values. This has been done so that administrators can use these columns to display any additional information that they deem useful for troubleshooting transaction slowness. For instance, administrators can configure eG Enterprise to capture the name of the user who initiated each transaction and display the same in the User Name column for every transaction URL in the Detailed Diagnosis page. Likewise, administrators can also tweak eG Enterprise to capture and display information such as fetch type, class name, method name, method signature, session attribute name, URL pattern, etc. against Business Context. Such custom information can also be captured for specific transaction URLs or URL patterns alone.
To achieve this, follow the steps below:
- Edit the exclude.props file in the <EG_BTM_INSTALL_DIR>\lib\btm directory.
- In the file, locate the IC for APM Configuration section.
In this section, first create an entry called IC_IDS and indicate for how many URLs/URL patterns you want a User Name and/or Business Context to be displayed.
For instance, if you want to configure a User Name and/or Business Context to be displayed for 4 patterns of URLs. then your IC_IDS specification will be as follows:
Next, append an IC entry for every URL/URL pattern for which a User Name and/or a Business Context is to be displayed. Each IC specification should be configured in the following format:
IC_<<URLIndex>>=<<Entry Description>>~|~<<Field Type>>~|~<<Fetch Type>>~|~<<Fully Qualified Class Name>>~|~<<Method Name>>~|~<<Method Signature>>~|~<<Method Argument Index>>~|~<<Fetch Once>>~|~<<Pass Request Object>>~|~<<Execute at Start of the Transaction>>~|~<<Session Attribute Name>>~|~<<Matching URL Pattern>>
Let us take a look at each variable in the specification. <<URLIndex>> refers to the serial number that identifies the URL/URL pattern to which the IC specification applies. This can be any number, depending upon the total number of URLs/URL patterns for which IC specifications need to be defined. For instance, if you want to display a user name and/or business context for 3 URLs/URL patterns, then, you will have to insert three separate IC specifications here, each with the <<URLIndex>> 1, 2, and 3, respectively, as shown below.
The <<URLIndex>> has to be sequentially incremented, as and when a new IC specification is appended.
- <<Entry Description>> can be a text string or a keyword that uniquely identifies the URL/URL pattern to which the IC specification applies. For instance, if you are configuring an IC specification for the URL pattern, */sports*, then you can configure sports as the <<Entry Description>>.
- <<Field Type>> should indicate whether you want to fetch a User Name for the URL/URL pattern or a Business Context. The <<Field Type>> should be either 1 or 2, where 1 denotes User Name and 2 denotes Business Context.
<<Fetch Type>> refers to the approach using which you want to capture the User Name or Business Context for a transaction URL. eG Enterprise prescribes three approaches to capturing the same:
- Method Argument - If you have written a Java method that takes input arguments for capturing the user name or business context, then use the Method Argument approach.
- Static Method - A Static method belongs to the class and not to the object(instance). A static method can access only static data. It cannot access non-static data (instance variables). A static method can call only other static methods and can not call a non-static method from it. If you have written a static Java method for retrieving the user name or business context, then use this approach.
- Session Attribute - If the User Name or Business Context is available as a session attribute, then you can configure the eG agent to access that session attribute and retrieve the required information.
- <<Fully Qualified Class Name>> is applicable only if the <<Fetch Type>> is either 1 or 2. If so, then specify the name of the class that contains the method definitions for fetching the User Name or Business Context. If a packaged class is to be used, then specify the fully qualified class name - eg., com/samples/MyProgram. If its not a packaged class, then simply specify the class name - eg., MyProgram.
- <<Method Name>> refers to the method that should be invoked for capturing the User Name or Business Context. Specify the name of that method here.
<<Method Signature>> is applicable only if the <<Fetch Type>> is 1. If the <<Method Name>> configured takes one/more input arguments, then specify a comma-separated list of such arguments in the place of <<Method Signature>>. Typically, if these input arguments are of primitive type, then you can specify them as is . However, if they are objects or wrapper classes, then they should be specified using the fully qualified object name or wrapper class name - eg., /java/lang/String.
On the other hand, if the <<Method Name>> configured does not take any input parameters, then enter null here.
- <<Method Argument Index>> is applicable only if <<Fetch Type>> is 1. If the <<Fetch Type>> is 2 or 3, then replace <<MethodArgumentIndex>> with none. For <<Fetch Type>> 1, in the place of <<Method Argument Index>>, you need to define at what position of the method invocation call, the information you need - i.e., whether User Name or Business Context - resides. For instance, if the method invocation call is Method1(int userID, string userName), then to fetch the User Name, the <<Method Argument Index>> will be 2. This is because, the second argument, string userName, is the one that fetches the User Name information.
- <<Fetch Once>> takes the value true or false. This is presently not handled. Nevertheless, you need to set it to either true or false. The value you set will not in any way impact the functionality or the output of the method.
- <<Pass Request Object>> is applicable only if <<FetchType>> is 2 - i.e., the static method approach. The static method that you use to fetch the User Name or Business Context should either take only one request object or no request objects. If the static method you use uses a single request object, enter true in the place of <<Pass Request Object>>. If the method you have written does not use any request objects, then specify false. If the <<Fetch Type>> is 1 or 3, then enter none.
- <<Execute at Start of Trans>> is applicable only if <<Fetch Type>> is 2 or 3. If <<Fetch Type>> is 1, then set this flag to none. On the other hand, if << Fetch Type>> is 2 or 3, then set the value of this flag to true or false. For example, say, you want to fetch the value of User Name from a session attribute and have hence set <<Fetch Type>> to 3. Let's say that the session attribute captures the user name only when the transaction is in progress; not when it begins. In this case, you have to set the <<Execute at Start of Trans>> to false, so that the user name is obtained from the session attribute towards the end of the transaction. On the other hand, if the session attribute captures the user name at the beginning of the transaction, set this flag to true. In this case, the user name is obtained from the session attribute at the start of the transaction itself.
- <<Session Attribute Name>> is applicable only if <<Fetch Type>> is 3. If so, then specify the name of the session attribute from which the User Name or Business Context has to be fetched.
- <<URL Pattern>> is applicable to all <<Fetch Types>>. Here, specify a comma-separated list of URLs or URL patterns for which the User Name or Business Context has to be captured and displayed as part of detailed diagnosis. The URL patterns can include wild card patterns - eg., */WebPoc*,*Web*
A sample IC specification is as follows:
- Then, restart the application.
The rest of the specification will change based on the approach you choose. In the specification, type 1 to choose the Method Argument approach, 2 to choose the Static Method approach, and 3 to pick the Session Attribute approach.
Some of the limitations of each of the approaches are as follows:
Method Argument Approach
- Not possible to get the argument values of predefined methods.
- Not possible to capture all the argument values of a method.
Static Method Approach
- Not possible to get the return value of private static methods.
- Not possible to get the output of static methods that have more than one parameter.
Session Attribute Approach
Not possible to get the session value if the response is committed at the end of the transaction.