Infrastructure Agent Properties Reference

You can configure the following properties:
apmdevops106
HID_IAPropertiesReference
You can configure the Infrastructure Agent using the properties in the IntroscopeAgent.profile file. The Infrastructure Agent uses these properties for its standard connection and naming. During installation, the Infrastructure Agent profile is installed in the
<Agent_Home>
/core/config directory unless you specify a different location.
You can configure the following properties:
2
Agent Name
introscope.agent.agentName
Uncomment this property to provide a default Infrastructure Agent name if the other naming methods fail.
Example:
introscope.agent.agentName=Agent
Note:
Restart the managed application for changes to this property to take effect.
Agent Extensions Directory
introscope.agent.extensions.directory
This property specifies the location of all extensions that the Infrastructure Agent loads. Non-absolute names are resolved relative to the location of this properties file.
Example:
introscope.agent.extensions.directory=../../core/ext
Note:
Restart the managed application for changes to this property to take effect.
Agent Metric Clamp
introscope.agent.metricClamp
This property configures the Infrastructure Agent to clamp approximately the number of metrics sent to the Enterprise Manager. When the property is not set, by default, the Infrastructure Agent clamps at 50000 metrics. New metrics are not reported, however existing metrics still report values.
Default:
50000
Example:
introscope.agent.metricClamp=50000
Note:
Restart the managed application for changes to this property to take effect.
Agent Remote Probe
Remote Probe Port
introscope.remoteagent.collector.tcp.port
This property specifies the port where Introscope listens to connections to collect events from remote probes. These probes include Infrastructure, Ruby, and .NET.
Values:
1 to 65535
Default:
5005
Example:
introscope.remoteagent.collector.tcp.port=5005
Note:
Restart the managed application for changes to this property to take effect.
Remote Probe Filter
introscope.remoteagent.collector.probeid.filtering.enabled
This property optimizes the remote agent probe to filter out unnecessary events before sending them to the Enterprise Manager. This property is only beneficial when an agent probe supports filtering. When filtering is not supported, setting this property can result in extra overhead. This property only takes effect for new agent probe connections.
Values:
True or false
Default:
True
Example:
introscope.remoteagent.collector.probeid.filtering.enabled=true
AutoProbe Properties
Enable AutoProbe
introscope.autoprobe.enable
This property enables and disables AutoProbe.
Values:
True or false
Default:
True
Example:
introscope.autoprobe.enable=true
Note:
Restart the managed application for changes to this property to take effect.
AutoProbe Custom Log File Location
introscope.autoprobe.logfile
This property specifies a custom log file location. AutoProbe always attempts to log the changes it makes.  Set this property to move the location of the log file from the default. Non-absolute names are resolved relative to the location of this properties file.
Values:
Custom location
Default:
../../logs/AutoProbe.log
Example:
introscope.autoprobe.logfile=../../logs/AutoProbe.log
Note:
Restart the managed application for changes to this property to take effect.
Directive Files
introscope.autoprobe.directivesFile
This property specifies all the directives files that determine how AutoProbe performs instrumentation. Specify a single entry or a comma-delimited list of entries. The list can include any combination of:
  • Directives (.pbd) files
  • Directives list (.pbl) files
  • Directories that are scanned about once per minute for pbd files
    Directive files that are placed in a listed directory load automatically without the need to edit the IntroscopeCollectorAgent.profile file. When dynamic instrumentation is enabled, the directives take effect immediately with no managed application restart needed.
Non-absolute names are resolved relative to the location of this properties file.
This parameter is required and
must
be set to a valid value.
  • When the property is not specified or the values are invalid
    The Infrastructure agent does not run.
  • When the property is set to include a directory and invalid directives files are placed in the directory
    AutoProbe metrics are no longer reported.
  • When the property is set to include a directory and loaded directives files are removed from the directory
    AutoProbe metrics are no longer reported
Example:
introscope.autoprobe.directivesFile=php-typical.pbl,hotdeploy
Note:
Restart the managed application for changes to this property to take effect. However, when the property includes one or more directories
and
dynamic instrumentation is enabled, no managed application restart is needed. The Infrastructure Agent loads directives files from the specified directories.
Default Process Name
introscope.agent.defaultProcessName
This property specifies the default process name in a specific situation: When no custom process name is provided and the Infrastructure Agent cannot determine the main application class name. The configured default process name displays in the Enterprise Manager and Workstation.
Example:
introscope.agent.defaultProcessName=Collector
Note:
Restart the managed application for changes to this property to take effect.
Dynamic Instrumentation Settings
Enable Dynamic Instrumentation
introscope.autoprobe.dynamicinstrument.enabled
This property specifies the changes to PBDs to take effect without restarting the application server or the Infrastructure Agent process. This operation is very CPU intensive. We highly recommend that you use configuration to minimize the classes that are being redefined. PBD editing is all that is required to trigger this process.
This property enables the dynamic instrumentation functionality. Dynamic instrumentation allows updates pbd files, while collector and Infrastructure applications are running.
Example:
introscope.autoprobe.dynamicinstrument.enabled=true
Note:
Restart the managed application for changes to this property to take effect.
Polling Interval to Poll for PBD Changes
introscope.autoprobe.dynamicinstrument.pollIntervalMinutes
This property specifies the polling interval in minutes to poll for PBD changes.
Example:
introscope.autoprobe.dynamicinstrument.pollIntervalMinutes=1
Note:
Restart the managed application for changes to this property to take effect.
Enterprise Manager Connection Order
introscope.agent.enterprisemanager.connectionorder
This property specifies the Enterprise Manager connection order list the Infrastructure Agent uses when disconnected from its Enterprise Manager.
Default:
Default
Example:
introscope.agent.enterprisemanager.connectionorder=DEFAULT
Note:
Restart the managed application for changes to this property to take effect.
Enterprise Manager Locations and Names
Host and Port Combinations
The names that are defined in this section are only used in the
introscope.agent.enterprisemanager.connectionorder
property.
These properties specify the settings that the Infrastructure agent uses to find the Enterprise Manager. They also specific the names that are given to host and port combinations.
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=orionphpcoda03
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.DefaultSocketFactory
Note:
Restart the managed application for changes to these properties to take effect.
Enable HTTP Tunneling
The following connection properties enable the Infrastructure agent to tunnel communication to the Enterprise Manager over HTTP.
HTTP tunneling impacts the Infrastructure agent and Enterprise Manager performance. Only use HTTP tunneling when a direct socket connection to the Enterprise Manager is not feasible. For example, when the Infrastructure agent is isolated from the Enterprise Manager with a firewall blocking all but HTTP traffic.
When enabling the HTTP tunneling for the Infrastructure Agent, uncomment the following host, port, and socket factory properties. Set the host name and port for the Enterprise Manager web server. Comment out any other connection properties that are assigned to the DEFAULT channel. Confirm that the DEFAULT channel is assigned as a value for the
introscope.agent.enterprisemanager.connectionorder
property.
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=8081
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.HttpTunnelingSocketFactory
Note:
Restart the managed application for changes to these properties to take effect.
Connect to the Enterprise Manager Using a Proxy Server
Sometimes the Infrastructure agent tunnels over HTTP and must connect to the Enterprise Manager through a proxy server. Use the following properties only in this situation. Here are two examples:
When the Infrastructure agent cannot reach the proxy server at the specified host and port
The Infrastructure agent tries a direct HTTP tunneled connection to the Enterprise Manager before failing the connection attempt.
When the Infrastructure agent can reach the proxy server at the configured host and port but the authentication fails
The Infrastructure agent keeps trying to make a connection to the Enterprise Manager through the proxy server.
Uncomment and set the appropriate proxy host and port values.
introscope.agent.enterprisemanager.transport.http.proxy.host
introscope.agent.enterprisemanager.transport.http.proxy.port
Note:
Restart the managed application for changes to these properties to take effect.
Proxy Server Authentication
The following properties are used only when the proxy server requires authentication. Uncomment and set the user name and password properties.
For NT LAN Manager (NTLM) credentials, separate domain name from the user name using an escaped backslash. For example: mydomain.com\\jack01
introscope.agent.enterprisemanager.transport.http.proxy.username
introscope.agent.enterprisemanager.transport.http.proxy.password
Note:
Restart the managed application for changes to this property to take effect.
Connect to the Enterprise Manager Using HTTPS
To connect to the Enterprise Manager using HTTPS, uncomment these properties. Set the host and port to the Enterprise Manager secure https listener host and port.
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=8444
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.HttpsTunnelingSocketFactory
Connect to the Enterprise Manager Using SSL
To connect to the Enterprise Manager using SSL, uncomment these properties. Set the host and port to the Enterprise Manager SSL server socket host and port.
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5443
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.SSLSocketFactory
More Properties for Connecting to the Enterprise Manager Using SSL
Location of a Truststore Containing Trusted Enterprise Manager Certificates
introscope.agent.enterprisemanager.transport.tcp.truststore.DEFAULT
If no truststore is specified, the Infrastructure agent trusts all certificates. Provide either an absolute path or a path relative to the Infrastructure agent working directory. On Windows, escape the backslashes. For example: C:\\keystore.
Truststore Password
introscope.agent.enterprisemanager.transport.tcp.trustpassword.DEFAULT
Keystore Location That Contains the Infrastructure Agent Certificate
introscope.agent.enterprisemanager.transport.tcp.keystore.DEFAULT
A keystore is needed when the Enterprise Manager requires client authentication. Provide either an absolute path or a path relative to the Infrastructure agent working directory. On Windows, escape the backslashes. For example: C:\\keystore.
Keystore Password
introscope.agent.enterprisemanager.transport.tcp.keypassword.DEFAULT
Set the Enabled Cipher Suites
introscope.agent.enterprisemanager.transport.tcp.ciphersuites.DEFAULT
A comma-separated list of cipher suites.whennot specified, use the default enabled cipher suites.
ErrorDetector Configuration
Enable Error Snapshots
introscope.agent.errorsnapshots.enable
This property enables error snapshots to capture transaction details about serious errors and enables recording of the error count metrics.
Values:
True = enabled, false = disabled
Default:
True
Examples:
introscope.agent.errorsnapshots.enable=true
Note:
No managed application restart needed
Maximum Number of Error Snapshots
introscope.agent.errorsnapshots.throttle
This property specifies the maximum number of error snapshots that the Infrastructure agent can send in a 15-second period.
Example:
introscope.agent.errorsnapshots.throttle=10
Note:
No managed application restart needed
Ignore Specific Error Messages
introscope.agent.errorsnapshots.ignore.0
This property specifies which error messages to ignore. Error snapshots are not generated or sent for errors with messages matching these filters.  You can specify any number using 0, 1, 2 and wildcards (*).
Examples:
introscope.agent.errorsnapshots.ignore.0=*com.company.HarmlessException*
introscope.agent.errorsnapshots.ignore.1=*HTTP Error Code: 404*
Note:
No managed application restart needed
Treat PHP Script Aborting Through die() or exit() as an Error
introscope.agent.php.error.on.abort
Treat PHP script aborting through
die()
or
exit()
as error.
Values:
True = enabled, false = disabled
Default:
True
Example:
introscope.agent.php.error.on.abort=true
Note:
No managed application restart needed
Stall Events
Minimum Threshold for Stall Event Duration
introscope.agent.stalls.thresholdseconds
This property specifies the minimum threshold for stall event duration.
Example:
introscope.agent.stalls.thresholdseconds=30
Note:
No managed application restart needed
Frequency That the Infrastructure Agent Checks for Stall Events
introscope.agent.stalls.resolutionseconds
This property specifies the frequency that the Infrastructure agent checks for stall events.
Example:
introscope.agent.stalls.resolutionseconds=10
Note:
No managed application restart needed
Logging Configuration
log4j.logger.IntroscopeAgent
Controls both the logging level and the output location.
Values:
INFO, console, logfile
Examples:
  • To increase the logging level, set the property to:
log4j.logger.IntroscopeAgent=VERBOSE#com.wily.util.feedback.Log4JSeverityLevel, console, logfile
  • To send output to the console only, set the property to:
    log4j.logger.IntroscopeAgent=INFO, console
  • To send output to the logfile only, set the property to:
    log4j.logger.IntroscopeAgent=INFO, logfile
Note:
No managed application restart needed
Log File Location
Do not modify the following properties for normal use.
  • log4j.additivity.IntroscopeAgent=false
  • log4j.appender.console=com.wily.org.apache.log4j.ConsoleAppender
  • log4j.appender.console.layout=com.wily.org.apache.log4j.PatternLayout
  • log4j.appender.console.layout.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n
  • log4j.appender.console.target=System.err
  • log4j.appender.logfile=com.wily.introscope.agent.AutoNamingRollingFileAppender
  • log4j.appender.logfile.layout=com.wily.org.apache.log4j.PatternLayout
  • log4j.appender.logfile.layout.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n
  • log4j.appender.logfile.MaxBackupIndex=4
  • log4j.appender.logfile.MaxFileSize=2MB
log4j.appender.logfile.File
If logfile is specified in
log4j.logger.IntroscopeAgent
, the location of the log file is configured using the
log4j.appender.logfile.File
property. System properties, such as the Java command line
-D
options, are expanded as part of the file name.
Examples:
  • log4j.appender.logfile.File=../../logs/IntroscopeAgent.log
  • When Java is started using
    -Dmy.property=Server1
    , then
    log4j.appender.logfile.File=../../logs/Introscope-${my.property}.log
    is expanded as shown:
log4j.appender.logfile.File=../../logs/Introscope-Server1.log
Note:
Restart the managed application for changes to this property to take effect.
Transaction Trace Configuration
Maximum Components Allowed in a Transaction Trace
introscope.agent.transactiontrace.componentCountClamp
Uncomment this property to specify the maximum number of components allowed in a Transaction Trace.  By default, the clamp is set at 5000. Any transaction trace exceeding the clamp value is discarded at the Infrastructure agent. A warning message is logged in the Infrastructure agent log file.
When you increase this clamp size, the memory requirement is higher. Therefore, the maximum JVM heap size might need to be adjusted, otherwise the managed application might run out of memory.
Default:
5000
Example:
introscope.agent.transactiontrace.componentCountClamp=5000
Note:
No managed application restart needed
Depth of Components Allowed in Head Filtering
introscope.agent.transactiontrace.headFilterClamp
Head filtering is the process of examining the start of a transaction for potentially collecting the entire transaction. Head filtering checks until the first blamed component exits, which can be a problem on deep call stacks without clamps. This clamp value forces the Infrastructure agent to look to a fixed depth, limiting the memory and CPU utilization impact.
Uncomment this property to specify the maximum depth of components that are allowed in head filtering.
Any transaction trace depth that exceeds the clamp value is no longer examined for possible collection aside from one exception. When another mechanism, such as sampling or user-initiated transaction tracing, is active to select the transaction for collection.
When this clamp size is increased, the memory requirement is higher and, garbage collection behavior might be affected. This situation has an application-wide performance impact.
Example:
introscope.agent.transactiontrace.headFilterClamp=30
Note:
No managed application restart needed
Transaction Trace Sampling
Disable Transaction Tracer Sampling
introscope.agent.transactiontracer.sampling.enabled
Uncomment this property to disable Transaction Tracer Sampling.
Values:
False = enabled, true = disabled
Default:
False
Example:
introscope.agent.transactiontracer.sampling.enabled=false
Note:
No managed application restart needed
Limit the Number of Transactions Reported by Infrastructure Agent Per Reporting Cycle
introscope.agent.ttClamp
Limits the number of transactions reported by the Infrastructure agent per reporting cycle.
Default:
200
Example:
introscope.agent.ttClamp=50
Note:
Restart the managed application for changes to this property to take effect.
Configure Transaction Trace Sampling
These properties are typically configured in the Enterprise Manager. Configuring sampling in the Infrastructure agent disables configuring in the Enterprise Manager.
introscope.agent.transactiontracer.sampling.perinterval.count=1
introscope.agent.transactiontracer.sampling.interval.seconds=120
Note:
Restart the managed application for changes to these properties to take effect.
Deep Instrumentation
introscope.agent.deep.instrumentation.enabled
This property enables deep instrumentation. When false, deep instrumentation is  turned off.
Values:
True = enabled, false = disabled
Default:
True
Example:
introscope.agent.deep.instrumentation.enabled=true
Note:
Restart the managed application for changes to this property to take effect.
Deep Instrumentation Components
introscope.agent.deep.trace.enabled
This property enables the PHP agent to collect deep instrumentation components and send them to the Enterprise Manager. When false, then PHP agent does not collect any deep instrumentation data.
Values:
True, false
Default:
True
Example:
introscope.agent.deep.trace.enabled=true
Note:
No managed application restart needed
Deep Component Visibility into Error Snapshots
introscope.agent.deep.errorsnapshot.enable
This property enables and disables deep component visibility into error snapshots.
Values:
True = enable, false = disable
Default:
True
Example:
introscope.agent.deep.errorsnapshot.enable=true
Note:
No managed application restart needed
Deep Trace of Component Limits
introscope.agent.deep.trace.max.components
Limits the maximum number of deep trace components in a transaction trace.
Example:
introscope.agent.deep.trace.max.components=5000
Note:
No managed application restart needed
Deep Trace of Consecutive Component Limits
introscope.agent.deep.trace.max.consecutive.components
Limits the maximum number of consecutive deep trace components in a transaction trace.
Default:
15
Example:
introscope.agent.deep.trace.max.consecutive.components=15
Note:
No managed application restart needed
Sustainability Metrics
Sustainability metrics are generated to provide information about the Infrastructure agent health and internal status. Substantial overhead is associated with these metrics.
introscope.agent.environment.java.metrics.enabled
This property enables or disables the Java version, Virtual Machine, and GC Heap:* metrics in the Infrastructure Agent.
Values:
True= enabled, false = disabled
Default:
True
Example:
introscope.agent.environment.java.metrics.enabled=true
URL Group Properties
These properties are for configuring URL groups for frontend metrics
introscope.agent.urlgroup.keys
Specifies configuration settings for frontend naming.
Default:
default
Example:
introscope.agent.urlgroup.keys=default
introscope.agent.urlgroup.group.default.format
This property specifies configuration settings for frontend naming.
When
introscope.agent.urlgroup.group.default.format={path_delimited:/:0:5}
,
introscope.agent.urlgroup.keys=default
, and
introscope.agent.urlgroup.group.default.pathprefix=*
, the default URL grouping provides Java URL groups with two segments after the port in the URL path.
Default
: Two segments after the port in the URL path.
Example:
introscope.agent.urlgroup.group.default.format={path_delimited:/:0:5}
Note:
No managed application restart needed
introscope.agent.urlgroup.group.default.pathprefix
This property specifies configuration settings for frontend naming.
Default:
*
Example:
introscope.agent.urlgroup.group.default.pathprefix=*
introscope.agent.urlgroup.frontend.url.clamp
This property limits the number of unique frontend URL group metrics that the Java agent creates. When the number of new URL groups reaches the set value, metrics for new URL groups display under the Metric Browse
Frontends|Apps|URLs|Default
node. This property helps to prevent metric explosions.
Default
:
5
Example:
introscope.agent.urlgroup.frontend.url.clamp=5
introscope.agent.urlgroup.frontend.url.resources.list
Frontends URL groups can contain specific file extensions, for example, png in  <
filename
>.png, We name these extensions as
resources
. This property specifies the file extension types.
When frontends URLs contain the resources that are listed in
introscope.agent.urlgroup.frontend.url.resources.list
, the resources display under the
Frontends|Apps|URLs|Resources
node.
The Resources URL group prevents invalid URLs from creating unique, one-time metrics and using large amounts of Enterprise Manager memory. Common invalid URLs are those that generate 404 errors,
Default
: tif,tiff,jpg,jpeg,gif,png,bmp,bmpf,ico,cur,xbm,svg,img,css,woff,nil
Example:
introscope.agent.urlgroup.frontend.url.resources.list=tif,tiff,jpg,jpeg,gif,png,bmp,bmpf,ico,cur,xbm,svg,img,css,woff,nil