Page History

...

About tracking service requests (URLs)

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)
called-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.

About instrumenting DLLs of an ASP.NET application

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.

About instrumenting standalone applications (Console, WinForm, Windows services)

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.
About callee vs. caller-side instrumentation (all-calls-to-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.
About tracking service requests (URLs)
Service Requests are tracked by default. The ability to track Service Requests (URLs) relies on the following blocks, which are part of the default instrumentation file:
<dll name="System.Web.dll" version="1.*">
<instrument>
<classes>
<class>
<name>System.Web.HttpRuntime</name>
<called-method>
<methods>
<method type="HTTP">
<name>ProcessRequest</name>
</method>
</methods>
</called-method>
</class>
</classes>
</instrument>
</dll>
<dll name="System.Web.dll" version="2.*">
<instrument>
<classes>
<class>
<name>System.Web.HttpRuntime</name>
<called-method>
<methods>
<method type="HTTP">
<name>ProcessRequestNoDemand</name>
</method>
</methods>
</called-method>
</class>
</classes>
</instrument>
</dll>
The instrumentation configuration partially filters the tracking of Service Requests: Service Requests are only tracked if the respective Web application’s DLLs are listed in the instrumentation file.
About tracking SQL statements
SQL statements are tracked by default. The ability to track SQL statements relies on the following blocks, which are part of the default instrumentation file:
<dlls>
<dll name="System.Data.Oracleclient.dll">
<instrument>
<classes>
<class>
<name>System.Data.OracleClient.OracleCommand</name>
<called-method>
<methods>
<method type="ADO">
<name>ExecuteOracleNonQuery</name>
</method>
<method type="ADO">
<name>ExecuteOracleScalar</name>
</method>
<method type="ADO">
<name>ExecuteReader</name>
</method>
<method type="ADO">
<name>ExecuteScalar</name>
</method>
<method type="ADO">

<name>ExecuteNonQuery</name>
</method>
<method type="ADO">
<name>Prepare</name>
</method>
</methods>
</called-method>
</class>
</classes>
</instrument>
</dll>
<dll name="System.Data.dll">
<instrument>
<classes>
<class>
<name>System.Data.SqlClient.SqlCommand</name>
<called-method>
<methods>
<method type="ADO">
<name>ExecuteReader</name>
</method>
<method type="ADO">
<name>ExecuteXmlReader</name>
</method>
<method type="ADO">
<name>InternalExecuteNonQuery</name>
</method>
</methods>
</called-method>
</class>
<class>
<name>System.Data.Common.DataAdapter</name>
<called-method>
<methods>
<method type="ADO">
<name>Fill</name>
</method>
<method>
<name>Update</name>
</method>
</methods>
</called-method>
</class>
</classes>
</instrument>
</dll>
<dll name="Oracle.DataAccess.dll">
<instrument>
<classes>
<class>
<name>Oracle.DataAccess.Client.OracleCommand</name>
<called-method>
<methods>
<method type="ADO">
<name>ExecuteReader</name>
</method>
<method type="ADO">
<name>ExecuteScalar</name>
</method>
<method type="ADO">
<name>ExecuteNonQuery</name>
</method>
<method type="ADO">
<name>ExecuteXmlReader</name>
</method>
</methods>


</called-method>
</class>
</classes>
</instrument>
</dll>
</dlls>
<!-- Instrument all the methods of classes which implement the following interfaces. -->
<instrument>
<interfaces>
<!-- Uncomment the following section to measure ADO.NET Open Connection response times -->
<!-- <interface>
<name>System.Data.IDbConnection</name>
<called-method>
<methods>
<method type="ADO">
<name>Open</name>
</method>
</methods>
</called-method>
</interface> -->
<interface>
<name>System.Data.IDbCommand</name>
<called-method>
<methods>
<method type="ADO">
<name>ExecuteReader</name>
</method>
<method type="ADO">
<name>ExecuteScalar</name>
</method>
<method type="ADO">
<name>ExecuteNonQuery</name>
</method>
<method type="ADO">
<name>Prepare</name>
</method>
</methods>
</called-method>
</interface>
</interfaces>
</instrument>
These blocks define the DLLs and methods that are used for SQL statement extractions. This configuration supports the following ADO.NET providers:
•    Microsoft provider for SQL-Server connectivity
•    Microsoft provider for Oracle connectivity
•    Microsoft ODBC connectivity
•    Microsoft OLEDB connectivity.
•    Oracle provider for Oracle connectivity
All SQL statements the above ADO.NET providers and methods use are tracked, even if the methods that call these ADO.NET methods are not explicitly selected for tracking in the Instrumentation.xml file.
The default instrumentation file for Precise for Microsoft .NET does already contain these blocks. If your application uses other database providers, consult Precise Technical Support.
About tracking COM+ (Enterprise services)
COM+ components can be developed and used in the following way:
•    The COM+ library components are executed and used as a library (DLL) in the context of an executable. The calls to the COM+ component methods look like other intra-process method calls.
The COM+ server components are hosted in an external COM+ container. A call from the COM+ component client (process) to the hosted COM+ component (external server process) is an inter-process call. In other words, activity exists in two different processes: the client-side process (caller-side) and the server-side process (callee-side).
To have the Microsoft .NET infrastructure reuse COM+ technology, perform the following tasks:
1.    Develop Microsoft .NET-based DLLs (Enterprise Services) on top of the COM+ engine.
2.    Reuse COM+ components with Microsoft .NET interoperability mechanisms (this case equals other interoperability cases and are not discussed here).
Calls to COM+ library components that were developed in Microsoft .NET equal other Microsoft .NET DLLs (for instrumentation purposes). To track the calls to the methods of these components, you only need to add the appropriate DLLs to the <dlls> list of the instance and specify the classes and methods to be tracked in the <instrumentation> block.
To track COM+ server components that are hosted in the COM+ container, perform the following tasks:
1.    To track server-side activity (the activation of the components' methods), add a new instance to the server for the COM+ container using Precise Agent Installer. The underlying process name of the COM+ host is dllhost.exe. In Precise Agent Installer, use this process name, but do not specify the path.
The <dlls> list of this new instance must include all DLLs of the Microsoft .NET-based COM+ server components to be tracked. The <instrument> block must specify the classes and methods that need to be instrumented.
2.    To track client-side activity (the calls to the COM+ components), add the DLLs of the appropriate COM+ component to the client instance (with the appropriate <instrument> block). In addition, insert the following section under the instrumentation section for the COM+ client instance:
<dll name="System.EnterpriseServices.dll">
<instrument>
<classes>
<class>
<name>System.EnterpriseServices.ServicedComponentProxyAttribute</name>
<called-method>
<methods>
<method>
<name>CreateInstance</name>
</method>
</methods>
</called-method>
</class>
<class>
<name>System.EnterpriseServices. RemoteServicedComponentProxy</name>
<called-method>
<methods>
<method>
<name>Invoke</name>
</method>
</methods>
</called-method>
</class>
</classes>
</instrument>
</dll>
About tracking Web services (calls)
The callee-side Web service infrastructure (Web service server-side) is implemented in ASP.NET. In other words, tracking Web services in the called-side is covered by tracking Service Requests.
See “About the instrumentation file” on page 151.
The Microsoft .NET framework contains comprehensive support for Web service clients (caller-side). For example, Visual Studio.NET generates a proxy class code that wraps the calls to the underlying Web service (the generated class extends an appropriate base class, such as System.Web.Services.Protocols.SoapHttpClientProtocol).
Web services are tracked by default. The ability to track Web service calls for all instances relies on the following blocks, which are part of the default instrumentation file:
<dll name="System.Web.Services.dll" >
<instrument>
<classes>
<class>
<name>System.Web.Services.Protocols. SoapHttpClientProtocol</name>
<called-method>
<methods>
<method type="WS">
<name>Invoke</name>
</method>
<method type="WS">
<name>BeginInvoke</name>
</method>
<method type="WS">
<name>EndInvoke</name>
</method>
</methods>
</called-method>
</class>
<class>
<name>System.Web.Services.Protocols. HttpSimpleClientProtocol</name>
<called-method>
<methods>
<method type="WS">
<name>Invoke</name>
</method>
<method type="WS">
<name>BeginInvoke</name>
</method>
<method type="WS">
<name>EndInvoke</name>
</method>
</methods>
</called-method>
</class>
</classes>
</instrument>
</dll>

About tracking the message queue API
To have Precise for Microsoft .NET track the usage of the Microsoft Message Queue API, you need to instrument the System.Messaging.dll file by manually adding the following blocks to the instrumentation block of the specific instance in the Instrumentation.xml file. Usually, it is sufficient to only instrument and track the methods Send and Receive to ensure that all appropriate Microsoft Message Queue call are tracked.
NOTE    The default instrumentation file for Precise for Microsoft .NET does not contain these blocks. To track Microsoft Message Queue calls, you must add these blocks manually.
To instrument Message Queue calls, insert the following section under instrumentation rules for the monitored instance in the instrumentation file:
<dll name="System.Messaging.dll">
<instrument>
<classes>
<class>
<name>System.Messaging.MessageQueue</name>
<called-method>
<methods>
<method>
<name>Send</name>
</method>
<method>
<name>Receive</name>
</method>
<method>
<name>BeginReceive</name>
</method>
<method>
<name>EndReceive</name>
</method>
</methods>
</called-method>
</class>
</classes>
</instrument>
</dll>

...