Configure .NET Agent Properties

Most agent operations are configured using properties in the IntroscopeAgent.profile file. This section describes the most common agent properties to set.
apmdevops106
Most agent operations are configured using properties in the
IntroscopeAgent.profile
file (agent profile). This section describes the most common agent properties to set. More properties might be appropriate for your environment. For information about extra properties, see Properties Reference .NET Agent. Different versions of the agent might have different properties available or different default values.
Configure Backup Enterprise Managers and Failover Properties
When you install the agent, you specify the Enterprise Manager host name and port number that the agent connect to by default. Optionally, you can also specify one or more backup Enterprise Managers. If the agent loses the connection to its primary Enterprise Manager, it can then attempt to connect to a backup Enterprise Manager.
To enable an agent to connect to a backup Enterprise Manager, you specify the communication properties for the Enterprise Managers in the agent profile. If the primary Enterprise Manager is not available, the agent tries to connect to the next Enterprise Manager on its list of allowed connections. If the agent does not connect with its first backup Enterprise Manager, it tries the next Enterprise Manager in the list. The process continues trying to connect to each Enterprise Managers in the list, in order, until it succeeds in connecting. If the agent is unable to connect to any of its Enterprise Managers, it waits 10 seconds before retrying.
Follow these steps:
  1. Open the
    Introscope.Agent.profile
    file in a text editor.
  2. Specify one or more alternative Enterprise Manager communication channels.
    Add the following properties to the agent profile for each backup Enterprise Manager:
    introscope.agent.enterprisemanager.transport.tcp.host.
    NAME
    introscope.agent.enterprisemanager.transport.tcp.port.
    NAME
    Introscope.agent.enterprisemanager.transport.tcp.socketfactory.
    NAME
    Replace
    NAME
    with an identifier for the new Enterprise Manager channel. Do not use
    DEFAULT
    or the name of an existing channel when creating a channel. For example, to create two backup Enterprise Managers:
    introscope.agent.enterprisemanager.transport.tcp.host.BackupEM1=paris
    introscope.agent.enterprisemanager.transport.tcp.port.BackupEM1=5001
    Introscope.agent.enterprisemanager.transport.tcp.socketfactory.BackupEM1=com.custom.postofficehub.link.net.DefaultSocketFactory
    introscope.agent.enterprisemanager.transport.tcp.host.BackupEM2=voyager
    introscope.agent.enterprisemanager.transport.tcp.port.BackupEM2=5002
    introscope.agent.enterprisemanager.transport.tcp.socketfactory.BackupEM2=com.wily.isengard.postofficehub.link.net.DefaultSocketFactory
  3. Locate the
    introscope.agent.enterprisemanager.connectionorder
    property. Set it to a comma-separated list of identifiers for the primary and backup Enterprise Managers. The order in which you list the identifiers defines the order in which they are contacted. For example:
    introscope.agent.enterprisemanager.connectionorder=DEFAULT,BackupEM1,BackupEM2
  4. Save the changes and close the
    IntroscopeAgent.profile
    file.
  5. Restart the application.
Specify an Agent Profile for an Application
By default, .NET agents that monitor web applications are automatically assigned a name that is based on the application virtual directory or context path. Agents that monitor non-web-based applications are assigned a name-based on the application domain name. We recommend that you use automatic agent naming whenever possible. However if needed, you can explicitly assign a name to an agent. For example, if you have multiple instances of the .NET agent, you can manage the instances separately and you can manually assign the names.
To assign agent names manually, perform these tasks:
  • create a separate agent profile for each agent instance and application.
  • define the process and agent name properties in each profile.
  • set the agent profile location for a specific application and agent instance.
Note:
CA APM edits the information that is used to construct the agent name according to the following rules:
  • Characters, such as pipes, colons, or percentage signs, are replaced with underscores.
  • Names beginning with any character other than a letter are prepended with the letter "
    A
    ".
  • Empty names are replaced with
    UnnamedAgent
    to distinguish them from the
    UnknownAgent
    condition.
For example:
Original Name
Display Name
"leading or trailing spaces"
"no spaces"
"44 Agent Name"
"A44 Agent Name"
"""
"UnmanagedAgent"
"agent name-123"
"agent name-123"
Create separate profiles for each application
You might want to explicitly assign a name to an agent instance monitoring a specific .NET application. In this case, you must create a separate
IntroscopeAgent.profile
for each application. Using a separate profile for each agent instance and application allows you to control the process and agent name and customize other properties, as needed.
Follow these steps:
  1. Copy the existing
    IntroscopeAgent.profile
    file in the
    <Agent_Home>
    directory.
  2. Paste the copied profile into a new directory.
  3. (Optional) Rename the profile to identify it as an agent instance profile. For example,
    IntroscopeAgentCalc1.profile
    .
Define an agent name
Using a custom process and agent name helps you identify agent instances that monitor specific applications. You can also modify other properties for the instance, as needed.
Follow these steps:
  1. Open the
    IntroscopeAgent.profile
    you created for the agent instance and application in a text editor. For example, if you created a custom profile that is named
    IntroscopeAgentCalc1.profile
    in the
    C:\NetApps\wily
    directory, open that file in a text editor.
  2. Locate the
    Custom Process Name
    section.
  3. Specify a custom process name to be displayed using the
    introscope.agent.customProcessName
    property. For example:
    introscope.agent.customProcessName=ArcadeCaclcProcess
  4. Disable automatic agent naming using the
    introscope.agent.AutoNamingEnabled
    property. For example:
    introscope.agent.agentAutoNamingEnabled=false
  5. Specify a custom agent name to be displayed using the
    introscope.agent.agentName
    property. For example:
    introscope.agent.agentName=ArcadeCalcAgent
  6. Save and close the updated custom profile.
Specify the Agent Name System Property Key
You can name the agent from the value of an existing system property that is specified in the
IntroscopeAgent.profile
.
Follow these steps:
  1. Open the
    IntroscopeAgent.profile
    .
  2. Under the
    Agent Name
    section, specify the system property that provides the agent name in this property:
    introscope.agent.agentNameSystemPropertyKey
    If the .NET system property specified here does not exist, this property is ignored.
  3. Close the file.
  4. Restart the application server.
Set the agent profile location for a specific application and agent instance
By default, the
IntroscopeAgent.profile
file is installed in the
<Agent_Home>
directory. For example, the default location is
C:\Program Files\CA APM\Introscope<version>\wily
. When you create separate profiles for agent instances that monitor specific applications, you must create a configuration file that specifies the location of the profile for that application and agent instance.
Follow these steps:
  1. Open the
    <Agent_Home>\Sample.exe.config
    file in a text editor.
  2. Copy all the sample
    <configSections>
    and
    <com.wily.introscope.agent>
    sections from the
    Sample.exe.config
    file.
  3. Open the
    web.config
    file for the .NET application or the standalone configuration file for non-IIS application executables.
    For more information about creating a configuration file for application executables, see Application-Specific Configuration.
  4. In the
    <env.parameters>
    section, modify the agent profile location. For example:
    <env.parameters>
    <add key="com.wily.introscope.agentProfile" value="C:\\NETApps\\wily\\IntroscopeAgentCalc1.profile" />
    </env.parameters>
  5. Save the
    web.config
    or standalone configuration file.
  6. Restart the managed application.
Collect and Customize Performance Monitor Data
By default, the .NET agent deploys a separate Windows service, the Performance Monitor Collection Agent. This agent collects metrics from all Windows Performance Monitor objects, counters, and instances. The Windows service reports this information for all agent instances and processes running on the IIS server. During installation, you specify whether this service starts automatically or must be started manually. After installation, you can use the Services Control Panel to manage the service. For example, you can use the Service Control Panel to change the startup type or pause and resume the collection of Performance Monitor counters.
You can customize the data that are collected by the Performance Monitor Collection Agent by modifying properties in the agent profile. For example, you can:
  • Use regular expressions to filter the specific metrics collected.
  • Control the total number of Performance Monitor metrics returned.
  • Control how frequently Performance Monitor counters are checked.
  • Control how frequently the Performance Monitor Collection Agent checks for new Performance Monitor objects.
  • Prevent the Performance Monitor Collection Agent from checking for new Performance Monitor objects.
Accounts that run the Performance Monitor Collection Agent must have permission to access Performance Monitor counters for the data to be available in the Investigator. By default, the Performance Monitor Collection Agent service runs using the Local System account, which has access to Performance Monitor counters. However, you can use the Services Control Panel to identify a different user account and password that the service runs under. For information about setting the appropriate permissions, see Set the user permissions for the IIS worker process.
Use regular expressions to filter metric collection
The .NET agent
perfmon.metric.filterPattern
property specifies the Performance Monitor counters the agent reads. Here is the default setting:
introscope.agent.perfmon.metric.filterPattern=|Processor|*|*,|.NET Data Provider*|*|*,|.NET CLR*|{osprocessname}|*,|.NET CLR Data|*|*,|Process|{osprocessname}|*,|ASP.NET|*
The filter follows the format |Object|Instance|Counter or |Object|Counter (if there is no instance) where:
  • Object
    identifies a performance monitor category, such as Memory, Processor, or Process.
  • Instance
    identifies a specific instance of the specified object. Some objects, such as Memory, do not have instances.
  • Counter
    identifies the specific type of metric for the Object|Instance to be collected. For example, the .NET CLR Memory Performance Monitor object has counters such as # Bytes in all heaps, Gen 0 heap size, # GC handles, and % time in GC.
The default filter also includes the
{osprocessname}
placeholder. In the Investigator, the
{osprocessname}
placeholder is replaced to identify the instances of the standalone applications that are monitored or the application pool name for the IIS worker process, for example,
w3wp(BusinessServiceAppPool)
.
Using the filter |*|* is equal to asking Performance Monitor to enumerate all counters as instance-less, which can break certain counters.
You can tailor the Performance Monitor data the .NET agent collects by modifying the value of the
introscope.agent.perfmon.metric.filterPattern
property. For example, you can expand or decrease the data that the agent reports by modifying the default filter. You can also include custom Performance Monitor counters if you have defined them for your applications.
Some Performance Monitor metrics have been reserved for future implementation by Microsoft. These metrics are tagged
NotDisplayed
when seen in Performance Monitor. When these metrics are viewed in the Introscope Investigator, the placeholder tag is displayed.
Set a limit on the total number of metrics
By default, the Performance Monitor Collection Agent collects Performance Monitor data for all Performance Monitor objects, instances, and counters available. You can limit the overall scope of data from setting an upper limit on the total number of Performance Monitor metrics reported
.
Setting a maximum number of Performance Monitor metrics helps to reduce the overhead of the Performance Monitor Collection Agent on the monitored server.
Follow these steps:
  1. Open the
    IntroscopeAgent.profile
    file in a text editor.
  2. Locate the
    perfmon.metric.limit
    property and set it to the maximum number of Performance Monitor metrics you want to allow in each interval. For example:
    introscope.agent.perfmon.metric.limit=100
  3. Save and close the
    IntroscopeAgent.profile
    file.
Control how frequently Performance Monitor data is collected
By default, the Performance Monitor Collection Agent checks for metric values from all Performance Monitor objects, instances, and counters every 15 seconds. This polling interval ensures that current data is reported for the Performance Monitor objects previously discovered
.
The Performance Monitor Collection Agent also periodically checks for new Performance Monitor objects from which it collects data. By default, this browsing interval is every 10 minutes to ensure that available objects are discovered and obsolete objects are removed without incurring overhead. You can modify either or both of these intervals in the agent profile.
Follow these steps:
  1. Open the
    IntroscopeAgent.profile
    file in a text editor.
  2. Locate the
    introscope.agent.perfmon.metric.pollIntervalInSeconds
    property and configure the polling interval of the Performance Monitor Collection Agent. The value that is set controls how frequently the Performance Monitor Collection Agent checks for metric values. For example:
    introscope.agent.perfmon.metric.pollingIntervalInSeconds=20
  3. Locate the
    introscope.agent.perfmon.category.browseIntervalInSeconds
    property and configure the browsing interval of the Performance Monitor Collection Agent. The value that is set controls how frequently the Performance Monitor Collection Agent checks for new or obsolete Performance Monitor objects. For example:
    introscope.agent.perfmon.category.browseIntervalInSeconds=900
  4. Save and close the
    IntroscopeAgent.profile
    file.
Prevent browsing of Performance Monitor objects
The Performance Monitor Collection Agent queries Performance Monitor objects periodically to ensure that all available services are accounted for. This action allows the agent to discover new counters, or eliminate obsolete counters, if needed. This functionality is enabled by default, with the default interval between queries are set to 600 seconds (10 minutes).
To reduce overhead on your system, you can prevent the Performance Monitor Collection Agent from checking for new and obsolete counters.
Follow these steps:
  1. Open the
    IntroscopeAgent.profile
    file in a text editor.
  2. Locate the
    introscope.agent.perfmon.category.browseEnabled
    property and set it to
    false
    . For example:
    introscope.agent.perfmon.category.browseEnabled=false
  3. Save and close the
    IntroscopeAgent.profile
    file.
Start the Collection of Performance Monitor Data
The .NET agent deploys an external service, CA APM PerfMon Collector Service, to collect and report Performance Monitor metrics. This service lets you collect metrics at the computer level, instead of collecting metrics for each .NET agent. Only this instance of the .NET agent uses PerfMon system resources.
Run this service after the .NET agent is deployed on the application server.
Follow these steps:
  1. Log in as the administrator to the Windows Management Console.
  2. Navigate to the
    CA APM PerfMon Collector Service
    .
  3. Right-click the service, and then click
    Start
    .
Stop the Collection of Performance Monitor Data
You can stop the collection of all Performance Monitor counters from collecting Performance Monitor data that is not required for managing .NET applications.
Follow these steps:
  1. Open the Services Control Panel.
  2. Locate the
    Performance Monitor Collector Service
    in the list of service names.
  3. Select the
    Performance Monitor Collector Service
    , right-click, then select
    Properties
    .
  4. Click
    Stop
    .
  5. Select
    Manual
    or
    Disabled
    as the Startup type.
  6. Click
    OK
    .
Control Startup Time
Many organizations that use IIS periodically restart the IIS services to recycle .NET application pools for each application domain. Anytime IIS restarts, the .NET agent is also invoked to instrument the applications in each application pool. The initial startup time can vary depending on these conditions:
  • Number of applications and classes that you monitor.
  • Agent profile configuration
  • Whether custom PBDs exist.
The default settings for an agent instrumented using NativeProfiler allow the agent and application server to start within a reasonable amount of time. To improve startup performance, you can perform some options steps.
If you want to improve the startup time of the .NET agent, perform these tasks:
  • Change the value of the
    introscope.nativeprofiler.directivematching.cache.max.size
    property in the agent profile.
    By default, the agent creates an in-memory cache of the directive groups it has previously found, which contain monitored classes. When you start IIS, the agent creates a cache of the classes previously discovered. The cache increases over time as the application code monitors new classes. By default, the in-memory cache stores up to 5000 class names. If the cache size reaches this limit, the agent records an entry in the NativeProfiler log file indicating that the cache is saturated.
    You can use the
    introscope.nativeprofiler.directivematching.cache.max.size
    property in the
    IntroscopeAgent.profile
    file to increase or decrease the size of the cache. Increasing the value can improve the startup time when the cache stores more than 5000 class names. However, increasing the value increases the memory overhead of the agent. Decreasing the property value reduces agent memory overhead. Decreasing the value is appropriate when you monitor fewer than 5000 classes or when you stop monitoring large directive groups.
  • Check how you have identified classes and directives in custom PBD files.
    If you use
    IdentifyInheritedAs
    directives for classes in the same group, you can enable the agent to use the inheritance hierarchy most effectively.
Configure Agent Load Balancing
In clusters where the workload is primarily metrics that are reported by agents, you can optimize the overall cluster capacity by configuring MOM agent load balancing.
Configure Detection of Synthetic Transactions
Configuration settings for synthetic transaction monitoring are done using the
introscope.agent.synthetic.header.names
parameter.
The
introscope.agent.synthetic.header.names
parameter value lists the HTTP header parameters that are used to determine whether a monitored HTTP request is part of a synthetic transaction. Commas separate the Individual parameter names. If this parameter is undefined or the value is empty, synthetic transactions are not detected. If multiple HTTP header parameter names are defined, they are examined in the specified order. The first HTTP parameter with a value is used to define the synthetic transaction.
The node under which the agent reports synthetic transactions depends on the specific HTTP header parameter that is used to detect each transaction as follows:
  • When the parameter value is anything other than
    x-wtg-info
    , the HTTP parameter value itself is used as the node name. Appropriate modification is done to ensure that a valid node name is used.
  • When the parameter value is
    x-wtg-info
    , the HTTP header parameter value is assumed to contain a sequence of name and value pairs. The ampersand symbol separates the pairs from each other. An equal sign separates the attribute name and value within each pair. The values of
    group
    ,
    name
    ,
    ipaddress
    ,
    and
    request_id
    with a | node separator form the synthetic transaction node names.
For example, given the parameter:
introscope.agent.synthetic.header.names=Synthetic_Transaction,x-wtg-info
The following
x-wtg-info
header results in metrics being reported under the
SampleGroup|sample|172.24.36.107|start
node as shown in this example:
clear synthetic=true&instance=ewing&name=sample&group=SampleGroup&version=4.1.0&ipaddress=172.24.36.107&sequencenumber=1&request_id=start&executiontime=1226455047
Any attributes that are not defined in the
x-wtg-info
HTTP header parameter value have default values that are supplied as follows:
  • group
    =unknownGroup
  • name
    =unknownScript
  • ipaddress
    =0.0.0.0
  • request_id
    =Action
If
introscope.agent.synthetic.header.names
is undefined, the following configuration parameters are ignored.
introscope.agent.synthetic.node.name=Synthetic Users
The node under which transactions recognized as synthetic are reported. This node is located under
Frontends|Apps|<WebAppName>
where
<WebAppName>
is the web application name. This value defaults to Synthetic Users.
introscope.agent.non.synthetic.node.name=Real Users
The node under which transactions not recognized as synthetic are reported. This node is located under
Frontends|Apps|<WebAppName>
where
<WebAppName>
is the web application name. If undefined, no additional node under
<WebAppName>
is created.
introscope.agent.synthetic.user.name=Synthetic_Trace_By_Vuser
The name of the HTTP header parameter whose value is used as the synthetic user name. The synthetic user name is used to separate different synthetic transactions. A node for each synthetic user name is created below the
Synthetic User
node. If this configuration parameter is defined and an HTTP header parameter of this name exists, synthetic transaction metrics are reported. The node under which the transactions are reported is
<Synthetic Users>|<Synthetic User>
where:
  • The
    introscope.agent.synthetic.node.name
    property determines the
    <Synthetic User>
    node name.
  • The HTTP header parameter value determines the
    <Synthetic User>
    node name.
Changes to these properties take effect immediately and do not require you to restart the managed application.
Using the TagScript Utility
You can use the CA TagScript utility with HP Vugen to specify extraction of synthetic user information.
To use the TagScript utility
  1. Open the TagScript utility.
    For Windows:
    <Agent_Home>\tools\TagScript.bat
    For UNIX:
    <Agent_Home>/tools/TagScript.sh
    You are asked which environment you want to modify scripts for.
  2. Click one of the following options:
    • Performance Testing
      - for HP LoadRunner scripts
    • Production
      - for HP Business Process Monitor or Sitescope scripts
    • Un-tag
      - to reverse the tagging process
  3. Navigate to the directory where your HP Vugen scripts are located. Double-click each .c script to open them.
    The HP Vugen script.c files are all backed up and replaced by modified versions.
  4. If HP Vugen is open and the utility is executed, you are prompted to reload the modified scripts. When prompted click
    Yes to All
    .
  5. You can either close the TagScript utility or click the
    Cancel
    button in the file selection dialog. You are not required to close the TagScript utility and many users do not close the utility while in HP Vugen. If a script is modified or any new scripts are created, not closing the utility simplifies the process.
  6. Verify that your scripts have been tagged in the following locations:
    • The new paragraphs of HP Vugen code are inserted at the beginning of each script.
    • Tags appear before all
      lr_start_transaction
      ,
      lr_end_transaction
      , and at the end of the script.
  7. (Optional) You can track each virtual user in an HP LoadRunner performance test with an individual set of blame stacks. To track each user, uncomment the following line at the beginning of the script in the declaration paragraph:
    web_add_auto_header(“Synthetic_Trace_By_Vuser”,vuserOverview)
    When this option is uncommented for a Production-tagged script, the .NET agent creates an individual set of blame stacks for each point of presence or synthetic generator.
Disable or Adjust Differential Analysis
Differential Analysis is active by default for WebAPI and MVC Controllers. However, as an administrator you can:
  • Disable Differential Analysis
  • Limit the number of transactions per interval.
Follow these steps:
  1. Open the
    IntroscopeAgent.profile
    file in a text editor.
  2. Locate the following properties:
    # Enabled the DA trigger feature. #introscope.agent.da.trace.enabled=true # Limit the number of transactions that are analyzed per 15-second interval #introscope.agent.da.trace.maxTransactionsAnalyzedPerInterval=4
  3. Uncomment the property that you want to configure and specify a value.
    • Disable Differential Analysis:
      introscope.agent.da.trace.enabled=false
      Values: true/false
      Default: true
    • Limit the number of transactions per interval:
      introscope.agent.da.trace.maxTransactionsAnalyzedPerInterval=3
      Values: A non-negative integer
      Default: 4
  4. Save and close the file.