Page History
...
The following table describes the tags in the Instrumentation.xml file.
Table 13-1 Instrumentation 1 Instrumentation file tags
| Tag |
|---|
...
| name | Description | Comment |
|---|---|---|
| instrumentation- |
...
| config | The top level XML tag. |
...
instances |
...
| The list of instances to be instrumented. |
...
|
...
| The logical name of the instance. |
...
instance tracker |
...
| (attribute) |
...
| The tracker DLL's reference to use. |
...
| Optional tag. | |
| dlls |
...
| The list of DLLs to be instrumented when loaded by this instance. |
...
| Without a list of DLLs, all loaded DLLs should be instrumented. | |
dll name (attribute) |
...
| The name of the DLL. |
...
Pattern match (for example Company.GUI.*) If the main module of the process must also be instrumented, the process name should be added explicitly to this DLL list. | |
dll path (attribute) |
...
| The path of the DLL. |
...
Pattern match. Optional tag. Without this tag, all |
...
DLLs with the indicated name are instrumented. |
dll version (attribute) |
...
| The version of the DLL. |
...
Pattern match. Optional tag. Without this tag, all |
...
DLLs with the indicated name are instrumented. | |
| instrument | The include list for instrumentation. |
...
| interfaces | List of interfaces to be instrumented. |
...
| All classes that implement these interfaces must be instrumented. | |
| interface |
...
| A specific interface (item in the interfaces list). |
...
...
| classes | The list of classes to be instrumented. Also classes that inherit from these classes must be instrumented. |
...
| The same syntax as the interfaces section. | |
| class |
...
A specific class (item in the classes list). |
...
name (in interface/class section) |
...
| The specific name of the interface/class. |
...
| Pattern match. (for example, using * as the name indicates all names in this context) |
...
| caller-method | The list of methods to be instrumented on the callee side. |
...
...
| methods | The beginning of the list. |
...
...
| method | The description of a specific method (within the classes/interfaces context). |
...
...
| type | The type of method invocation. |
...
Optional tag (the default is Custom). Specified in the default-inst-config.xml file. | |
name (of method) |
...
| The specific name of the method. |
...
| Pattern match (for example, using * as the method name indicates all methods in this context). |
...
| params | The list of parameter types. |
...
| param |
...
A specific parameter type. |
...
| all-calls-to- |
...
| method | The list of methods to be instrumented on the caller side. |
...
| The same syntax as the caller-method section. |
...
| ignore | The exclude list for instrumentation. |
...
| The syntax of this section and its subcomponents is identical to the instrument section. |
About instrumenting DLLs from the GAC
The Global Assembly Cache (GAC) is a logical directory that stores all assemblies that can be shared among applications. An assembly is placed in the GAC at deployment time, using either an installer that knows about the assembly cache or the Global Assembly Cache Utility (gacutil.exe), found in the MS .NET Framework SDK.
To instrument a DLL from the GAC, do not specify the path attribute in the DLL list. Instead, use only the DLL name. To instrument a DLL with a specific version, use the version attribute.
...
The ASP.NET DLLs are typically loaded from a special temporary directory, such as:
C:\WINNT\Microsoft.NET\Framework\v1.1.4322\Temporary ASP.NET Files\mspetshop\c73f3fa0\1ae4c2f3\assembly\dl2\bee75c45\aa2e9da0_9807c501)
As in the case of the GAC, to instrument such DLLS, do not specify the ASP.NET DLL path and only use the DLL name.
...
A standalone application that starts with a main method usually does not finish before the application terminates. This main method typically invokes other methods that actually perform most of the activities in the application. These other methods are started and stopped quite frequently, but their top-level caller (the main method) remains running.
The Microsoft .NET AppTier Collector agent is designed to report only when a complete sequence of method invocations has finished. To deal with this kind of scenario, the ignore tag is used in the default instrumentation file to exclude the instrumentation and the tracking of the main method.
...
Callee-side instrumentation means instrumenting the methods (their prologues and epilogues) to track the method invocations. Caller-side instrumentation means instrumenting the calls to the methods to track the called method invocations. These techniques are two different ways to gather the same data.
Precise for Microsoft .NET generally uses the callee-side instrumentation technique. If callee-side instrumentation is not possible, caller-side instrumentation can be applied instead. To do so, replace the default called-methods tag with the all-calls-to-method tag. This alternative is best used when the tracked method is part of the Microsoft .NET framework system DLLs that cannot be instrumented directly, such as the System.dll.
...
The instrumentation process is the execution of a Collector agent, which reads the code (the DLLs) of your application and stores an instrumented version in the <i3_root>\products\dotnet\cache\instr cache directory:
The contents of the cache can then be used for future invocations of your Microsoft .NET application, avoiding the time to re-instrument. The instrumentation process can last anywhere between a few minutes and an hour, depending on the size of the DLLs.
The instrumentation process consumes memory. The required memory for instrumenting a DLL is approximately 20 times the size of that DLL file. As a result, the startup of your Microsoft .NET application can be considerably slow.
The instrumentation is triggered when the Microsoft .NET application starts and one of the following criteria is applicable:
• The .NET instance is installed for the first time.
• A change is made to the instrumentation.xml file (the instrumentation configuration file).
• A new code version is deployed on the monitored server.
To minimize the time it takes the Microsoft .NET application to start up, you can invoke a Precise for Microsoft .NET utility called Instrumentation Driver. The Instrumentation Driver populates the cache before it restarts the Microsoft .NET application.
NOTE If the instance uses DLLs from several directories or several single DLLs, invoke the Instrumentation Driver utility several times using the appropriate directory or DLL names.
It is recommended to stop your Microsoft .NET application before you invoke the Instrumentation Driver utility. If you invoke the utility while the application is running, the instrumentation results are placed in the cache and used only during the next startup of the Microsoft .NET application.
If your application changes, for example because a new version is deployed, or if you modify the instrumentation.xml file, you can activate the Instrumentation Driver utility to recalculate the cache contents.
NOTE The Instrumentation Driver utility may not calculate the cache contents for all DLLs that the application uses. These DLLs are only instrumented during the next startup of the Microsoft .NET application.
To invoke the Instrumentation Driver utility
1. After the Microsoft .NET instance is installed, configure the DLLs, classes, and methods to be instrumented in the instrumentation.xml file.
2. Open a command prompt window and run the following command:
cd <i3_root>
products\dotnet\bin\psdn_instr_validate.exe [-k instance-name]
-f directory-name | -dll name [-gac]
Where:
instance-name is the Microsoft .NET instance name, such as AspNetIIS5. If this parameter is omitted, the Instrumentation Driver works for all the Microsoft .NET instances that are installed on the monitored server. directory-name is the name of the DLL directory of the Microsoft .NET instance to be instrumented. This is the location where you deployed your Microsoft .NET code. For example, a DLL for an ASP.NET application may be stored in:
C:\Inetpub\wwwroot\MyWebApp\bin
name is the name of a single DLL (without the path). If this DLL is located in the GAC, add -gac when running the command.
Precise. Performance intelligence from click to storage. Learn more > >
...