Contents
Agent Legacy Mode Limitations
The following capabilities are not available when running the agent in legacy mode:- Agent CPU usage and response time optimizations in version 9.1
- Dynamic Instrumentation for the .NET agent
- SQL Agent properties
introscope.agent.sqlagent.sql.artonly introscope.agent.sqlagent.sql.turnoffmetrics
- Smart instrumentation
- SAP Passport propagation
IconImportant! Running legacy tracers with the CA APM agent in new mode is known as “mixed mode” configuration. Never run the agent in mixed mode as it often consumes extra memory heap resulting in application outages.
Configuring the Agent to Use Legacy Mode Transaction Tracing
Converting to the legacy mode Transaction Tracing only applies to versions of CA APM that have the new mode. CA APM versions before version 9.1 do not have new mode.Follow these steps:- Stop the monitored application.
- Archive and delete existing log files in the <Agent_Home>/logs directory to prepare for new logs.
- Back up the existing .pbl and .pbd files in the <Agent_Home>/core/config directory.
- Back up the existing <Agent_Home>/core/config/IntroscopeAgent.profile.
- Copy the legacy .pbl and .pbd files from the <Agent_Home>/examples/legacy directory to the <Agent Home>/core/config directory.
- Open <Agent_Home>/core/config/IntroscopeAgent.profile and make the following changes:
- Add property introscope.agent.configuration.old=true
- Update the agent property introscope.autoprobe.directivesFile to point to the appropriate legacy .pbl and .pbd files that have been copied over. For example, replace spm.pbl with spm-legacy.pbl
- Restart the monitored application.
Controlling Transaction Trace Sampling
By default, Introscope agents trace each normalized unique URL in an application once per hour, to provide a sampling of transaction behavior. This sampling enables historical analysis of potentially problematic transaction types without explicitly running transaction traces.Transaction trace sampling is enabled by default. You can disable the behavior by uncommenting the following property in the agent profile, IntroscopeAgent.profile:
introscope.agent.transactiontracer.sampling.enabled
Uncomment and set to false to disable transaction trace sampling.
You can configure how many transactions are sampled per interval and how long that interval is by uncommenting the following properties in the agent profile.
Icon
Important! These configurations are typically performed in the Enterprise Manager. Configuring the following properties in the agent profile overrides any configuration made in the Enterprise Manager.
introscope.agent.transactiontracer.sampling.perinterval.count
Uncomment and set how many transactions are sampled per interval. The default is 1.
introscope.agent.transactiontracer.sampling.interval.seconds
Uncomment and set how long the sample interval is in seconds. The default is 120 seconds.
Transaction Trace component clamp
Introscope sets a clamp (set by default to 5,000 components) to limit the size of traces. When this limit is reached, warnings appear in the log, and the trace stops.
This allows you to clamp a component heavy transaction the grows beyond expected component counts. For example, when a component executes hundreds of object interactions and backend SQL calls. Without the clamp, Transaction Tracer views this as one transaction, continuing infinitely. Without a clamp in place in certain extreme situations, the CLR can run out of memory before the trace completes.
The property for clamping transactions is located in the IntroscopeAgent.profile file:
introscope.agent.transactiontrace.componentCountClamp=5000
For traces producing clamped components -- those exceeding the CountClamp -- traces are marked with an asterisk and have a tool tip associated with them.
If the clamp is set too low, you may encounter Performance Monitoring (PerfMon) or LeakHunter exceptions when your applications start. If you encounter this, your managed .NET applications must to be restarted
Transaction Tracer options
You can configure the Introscope Transaction Tracer to trace only the transactions that meet criteria you specify. You can filter by user ID data or by HTTP request and session properties.
Icon
Important! You can filter by user ID
or by HTTP attributes, but not both. Do not configure both types of filters -- bad metrics can result from this configuration.
To control which transactions are traced:
- Enable the .NET agent to report filter parameters.
- Configure filtering either by user ID or HTTP request data:
Enable collection of filter parameters
By default, the .NET agent reports only the URL for transactions it traces. Reporting of individual HTTP properties is restricted to minimize the impact of transaction tracing on system overhead. To enable filtering you must first enable collection of HTTP properties, by adding the following line to the agent profile:
introscope.agent.asp.disableHttpProperties=false
This enables collection of:
- Application Name
- Session ID
- Context Path
- Server Name
- URL
- Context Path
- Normalized URL
- HTTP headers
- HTTP parameters
- HTTP attributes
You can enable collection of additional properties by adding this line to the agent profile:
introscope.agent.asp.optionalProperties=true
This enables collection of:
Filter Transaction Traces By User ID
To configure the .NET agent to filter transaction traces by user IDs in frontend components, determine how your application specifies user IDs. The application architect who developed the application can provide this information.The Introscope Transaction Tracer can identify user IDs that are accessed through one of these methods:- HTTP Context identity
- HTTP request header
- URL user information
- An attribute of the HTTP session
Icon
Important! Perform only the configuration process that applies to the method of specifying user IDs in your application.
Filter by context identity
If the user ID is accessed through the HTTP Context identity, uncomment this property in the agent profile:
introscope.agent.transactiontracer.userid.method=HttpContext.User.Identity.Name
Filter by URL user
If the user ID is accessed through the URL user information, uncomment the property in the agent profile:
introscope.agent.transactiontracer.userid.method=HttpContext.Request.Uri.UserInfo
Filter by request header
If the user ID is determined from the HTTP request header, uncomment the following pair of properties in the agent profile, and define a key string for the second property:
introscope.agent.transactiontracer.userid.method=HttpRequest.Headers.Get introscope.agent.transactiontracer.userid.key=<application defined key string>
Filter by session attribute
If the user ID is an attribute in the HTTP Session, uncomment the following pair of properties in the agent profile, and define a key string for the second property:
introscope.agent.transactiontracer.userid.method=HttpContext.Session.Contents introscope.agent.transactiontracer.userid.key=<application defined key string>
Filter Transaction Traces By HTTP Request Data
You can filter for transaction traces by HTTP request properties, including:
- Request headers
- Request parameters
- Session attributes
You can filter using multiple properties, for instance by request parameter and by session attribute.IconImportant! Do not configure filtering by HTTP property if you have configured filtering by user ID.
Follow these steps:- Open the IntroscopeAgent.profile file.
- Locate the Transaction Tracer properties under the Transaction Tracer Configuration heading.
- To collect specific HTTP request headers, uncomment the following property and specify the HTTP request headers to track, in a comma-separated list:
introscope.agent.transactiontracer.parameter.httprequest.headers=User-Agent
- To collect HTTP request parameters data, uncomment this property and specify the HTTP request parameters to track, in a comma-separated list:
introscope.agent.transactiontracer.parameter.httprequest.parameters=parameter1,parameter2
- To collect HTTP session attributes data, uncomment this property and specify the HTTP session attributes to track, in a comma-separated list, for example:
introscope.agent.transactiontracer.parameter.httpsession.attributes=attribute1,attribute2
- Save your changes to the IntroscopeAgent.profile file.
- Restart the application.
Configuring Component Stall Reporting
An application performance management stall is when there is no response from probed components for a defined length of time. By default, the Introscope agents detect this condition and report Stall metrics.Each time the agent checks for stalls, all the topmost instrumented components on the method stack are checked. When a component is stalled, a stalled metric and a stall snapshot are created. A stall metric is also created for each component that subscribes to downstream monitoring.The stall metrics are created first for the topmost instrumented components on the method stack. These metrics are created for the components that take longer than the introscope.agent.stalls.thresholdseconds value.Downstream Subscriber Component Stalls
A component that subscribes to downstream monitoring is stalled when it calls a stalled downstream component.By default, the following components subscribe to downstream stall monitoring:- FrontendTracer probed Components
- BackendTracer probed Components
- WebServiceBlamepointTracer@Servicelevel probed components
- WebServiceBlamepointTracer@Opertationlevel probed components
ExampleA frontend component calls a Webservice which calls a backend component that is stalled.Frontend--> WebService-->BackendThe stall metrics are created for the backend, the Webservice, and the Frontend components because all of them subscribe to downstream monitoring by default.Upstream Inherited Component Stalls
The stall checker first examines the top member of the component stack to see if it is stalled. If the top component is not stalled, the stall checker looks for stalled parent components. When a parent is stalled, a stall metric is created for that component and each upstream parent in the stack.If a component M1() calls multiple components M2() that each take only a few seconds, a stall metric could be reported for M1().Example:The stall threshold is set at 15 seconds. Method M1() calls method M2() in a loop 100 times. M2() never stalls because it takes only 2 seconds to respond each time. However, M1() is eventually stalled.Disable the Capture of Stalls as Events
By default, Introscope captures transaction stalls as events in the Transaction Event database, and generates stall metrics from the detected events. Stall metrics are generated for the first and last method in the transaction. Users can view stall events and associated metrics in the Workstation Historical Event Viewer.IconNote: Generated stall metrics are always available, but stall events are only visible if Introscope Error Detector is installed. Stalls are stored as ordinary errors, and are visible in the Errors Tab View and in the Live Error Viewer. Stalls are also visible in the historical query viewer by querying for “type:errorsnapshot.” Stalled transactions are reported as Errors in the Live Error Viewer and under the Errors tab. Stalled transactions are not reported as Errors in the transaction Trace window when traced using "Errors matching *" criteria because this behavior is the designed behavior.
To disable the capture of stalls as events, change the stall threshold, or change the frequency with which the .NET agent checks for stalls, use the following properties:- introscope.agent.stalls.enable -- Controls whether the agent checks for stalls and creates events for detected stalls.
- introscope.agent.stalls.thresholdseconds -- Specifies the minimum threshold response time at which time a transaction is considered stalled.
- introscope.agent.stalls.resolutionseconds -- Specifies the frequency that the agent checks for stalls.
Icon
Important! Support for stall tracers in PBDs is deprecated when you disable the capture of stalls as events.
NonIdentifying Transaction Tracing
By default, traces for nonidentifying transactions are not generated even if the feature is enabled in the CEM UI.
To enable traces for nonidentifying transactions, set the following property value to FALSE in introscopeAgent.profile.
introscope.agent.bizdef.turnOff.nonIdentifying.txn=FALSE