9 Install and Configure APM .NET Agent
Agent Requirements and Installation Instructions
Prerequisites
-
Windows Server 2008 and above
-
.Net Framework 3.5 and above
Note:
If your APM is installed on .Net Framework 3.5 Classic, then, APM does not monitor the static file request page. The .Net Framework 3.5 Integrated and other higher versions of the .Net framework supports static file request monitoring by APM. -
Java Application Servers with JDK version 1.7 or above. If you are using JDK 1.6, either use a JDK 1.6 that supports TLS 1.2 security protocol, or connect to OMC through a Gateway.
-
If the JDK version you are running doesn't support TLS 1.2 security protocol, refer to My Oracle Support Doc ID 2703411.1 before proceeding with the APM agent installation.
-
For monitoring of .NET applications on Windows, only one APM product should be configured on a system at a time.
-
Other considerations:
- The machine hosting the IIS Server should be able to establish an HTTPS connection either directly or indirectly (using a proxy server or an Oracle Management Cloud gateway) to Oracle Management Cloud. For more information about Oracle Management Cloud gateway, see Install a Gateway.
-
The HTTPS connection must use TLS 1.2 security protocol.
- The users that run applications in IIS should have Read and Write permissions to the .Net agent log directories. By default, the log directory is
C:\ProgramData
. - The user should have Administrator Access to the machine where APM .Net Agent will be deployed.
- The user should have the ability to restart IIS.
Set the Registration Key
After creating or downloading a registration key, set the REG_KEY
variable to the registration key.
set REG_KEY=<Registration Key>
Deploy the Gateway (Optional)
-
If you have an application server that does not support Transport Layer Security (TLS) protocol 1.2.
-
If you have older versions of .NET IIS servers and Java Application Servers with JDK less than 1.7 (for example, Oracle WebLogic 10.3.6)
Set the Gateway Variables (Optional)
Set the values for Gateway host and port.
set GW_HOST "<Gateway Host Name>"
set GW_PORT "<Gateway Port>"
Download the APM .NET Agent Software
-
From the main Oracle Management Cloud menu, navigate to Administration and Agents.
-
On the Oracle Management Cloud Agents page, click the Action Menu on the top right corner of the page and select Download Agents.
The Agent Software Download page is displayed.
-
From the Agent Type dropdown list, select APM Agent.
-
Click APM .Net Agent.
-
Extract the contents of the installer ZIP file.
-
Click Done after the download is complete.
-
Create a registration key that will be used during the time of installing a new agent. Oracle Application Performance Monitoring Cloud Service verifies this key before accepting any data sent by APM .Net Agent deployed on your on-premises hosts. For more information about creating a registration key, see Manage Registration Keys in Installing and Managing Oracle Management Cloud Agents.
-
Enable the performance counters of the IIS application you wish to monitor. For this, the application pool user must be a member of the 'Performance Monitor Users' group. Refer to the Microsoft IIS documentation for detailed instructions.
Install the APM .NET Agent Software
To install the APM .Net Agent on your IIS server:
-
Make a backup of the following system configuration files:
-
C:\Windows\System32\inetsrv\config\applicationHost.config
-
C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\web.config
-
C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG\web.config
-
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config\web.config
-
C:\Windows\Microsoft.NET\Framework64\v2.0.50727\CONFIG\web.config
-
-
Stop the IIS server.
iisreset /stop
-
Execute the APM .Net Agent installer.
-
Ensure that the
AgentConfig.info
file is in the same directory as theApmAgent.msi
file. -
Run the
ApmAgent.msi
executable. The APM .Net Agent installation wizard guides you through the installation process. -
The Installation wizard performs a check of these pre-requisites before proceeding with the installation:
-
User without administration privileges
-
If IIS is installed
-
If IIS is installed without ASP .Net
-
If the user does not have the permission to access this path —
"C:\Windows\System32\inetsrv\config\applicationHost.config"
-
Choose No to exit the installation.
-
Choose Yes to proceed anyway.
However, if you proceed without all the pre-requisites in place, the installation of the APM .Net Agent will not be successful.
-
-
Specify the installation directory.
-
Optionally, select Configure Proxy and specify the proxy information. The password that you specify here is encrypted to enhance security.
-
Optionally, select Configure Gateways and specify the Gateway information.
-
In the Set Registration Key field, provide the Registration Key. You can get this from the Registration Keys tab in the Oracle Management Cloud Agents page.
-
In the Set Host Name field, review the default host name, and modify if required.
-
Select the applications to be monitored in the Monitored Application Configuration screen. You can choose to monitor all applications on the IIS server, or manually select specific applications from the list.
You can change this list of applications to be monitored anytime after the installation. See Enable Monitoring of Specific Applications.
-
Click Install.
-
For Silent Installation, run this command:
msiexec /i <msi file name> /quiet /log <log name to redirect the installation output> REGISTRATION_KEY=<reg key value> AGENTCONFIGEXISTS=1
Note:
For a silent mode install with proxy, run this command instead:msiexec /quiet -i <msi file name> SERVER_URL=<the server url> TENANT_ID=<the tenant ID> REGISTRATION_KEY=<reg key value> PROXY_ENABLE=1 PROXY_HOST=<the proxy url> PROXY_PORT=<the proxy port> PROXY_USER=<proxy user name> PROXY_PASSWORD=<the proxy password>
-
Start your IIS server.
iisreset /start
Note:
APM .NET Agent uses .NET Profile API like most of the IIS monitoring tools. This might lead to potential conflicts when APM .NET Agent is installed alongside another IIS monitoring tool. As a result, both APM .NET Agent and another tool may not be able to detect or correctly monitor IIS application that needs to be monitored.Enable Monitoring of Specific Applications
You can configure APM .Net Agent to monitor specific applications installed on your IIS server. You can choose the applications to be monitored during the installation. You can also choose to add a new application to be monitored, or stop monitoring some applications after the installation.
-
Disable monitoring globally for the APM .Net Agent.
-
In the installation directory, check the global
AgentConfig.ini
file. By default, the installation directory isC:\Program Files\Oracle APM .NET Agent
. -
Disable global monitoring for all applications with this setting:
oracle.apmaas.agent.disable=true
-
-
Enable monitoring for a specific application.
-
Navigate to the Agent’s instance directory:
C:\ProgramData\Oracle\ApmAgent\config\<webSite><webApplication>
. -
Edit the
AgentConfig.ini
file and enable monitoring with this setting:
Repeat this for every application to be monitored.oracle.apmaas.agent.disable=false
-
Configure APM .NET Agents
You can configure deployment parameters of your APM .Net Agent to control the monitoring of applications.
APM .Net Agent Installation Directories
The APM .Net Agent installation directory has an installation directory, configuration directory and logs directory.
The agent installation directory is specified by the environment variable ORACLE_APM_AGENT_HOME
, which gets automatically set by the installer. Each agent instance contains configuration directory and logs directory.
Examples:
Installation Directory: c:\Program Files\Oracle APM .Net Agent
Configuration directory:c:\ProgramData\Oracle\ApmAgent\config\<appName>
Logs directory: c:\ProgramData\Oracle\ApmAgent\logs\<appName>
Configuration Directory
By default, the agent configuration directory for a monitored application is c:\ProgramData\Oracle\ApmAgent\config\<appName>
.
You can customize the configuration of an APM .Net Agent instance by adding an AgentConfig.ini
file to the configuration directory. By customizing the configuration you can disable or turn log traces for a specific agent.
After you have made the configuration changes, only the agent instance using this configuration directory will detect the configuration change and restart. If several agent instances are monitoring the same replicated application, all agent instances will detect the configuration change and restart.
Logs Directory
AgentStartup.log, AgentStatus.log
and Agent.log
.
-
AgentStartup.log
contains the agent logs related to startup. You can verify if the agent started up correctly from this file. -
Agent.log
contains all agent logs, including the logs found inAgentStartup
.
Important Considerations
Some important considerations before configuring the parameters:
-
Any change to the installed configuration files (
AgentConfig.ini
andOMC.ini
), applies to all agent instances running on the machine. -
An agent automatically detects any change to any of its configuration files. When this happens an agent restarts, making any new setting immediately active. If a change is made to the installation directory configuration files (
AgentConfig.ini
orOMC.ini
), all agents on the machine restart reading the changed configuration files as they start up. If a specificAgentConfig.ini
configuration file gets changed (for example, from an agent instance configuration directory), only the specific agent restarts.
Configuration Settings
Property | Description |
---|---|
oracle.apmaas.agent.disable |
Defaults to False when not specified. If set to True , the agent is disabled (agent instance is shutdown).
|
|
AgentBootstrap log file settings —
|
|
AgentStartup log file settings —
|
|
AgentStatus log file settings —
|
|
Agent log file settings —
|
oracle.apmaas.agent.trace.<area> = <level> |
area: Instrumentation, Startup, Http, MetricsProcessor, Sampling, Handler, Transport, Config, InternalMetrics, SqlServer, Utility, Injection level: verbose, all, off |
oracle.apmaas.agent.trace = <level> |
|
oracle.apmaas.agent.trace.flow = verbose |
When the trace area flow is enabled with the level verbose , detailed traces of the flow processor are logged in a file named AgentFlowTrace.log . See section below for details.
|
oracle.apmaas.agent.trace.overhead = verbose | all |
Enable this to get a dedicated log file named AgentOverheadStatus.log created. The file contains metrics on probe, transport (verbose ) and optionally JSON, core runtime (all) internal processing overhead metrics, and some memory metrics. These metrics can be used to get the time that the agent adds (overhead) to the monitored application, in microseconds. Note that fetching these metrics also adds overhead, so the real overhead is few microseconds less than the logged overhead.
|
oracle.apmaas.agent.trace.overhead.format = csv | json |
Set this property value to csv to get a Comma Separated Values output format instead of a user readable text format (this applies to the AgentOverheadStatus.log file). Set this value to json to create separate JSON files. If the json format is specified, the file AgentOverheadStatus.log is not created.
|
|
Set this property to log all observations sent by the agent in a local file, within the agent log directory. By default, the file name is Observations.log . Use one of properties below instead of this one to specify a different file name.
|
OR
|
Set any of these properties to a file name to log observations within the specified file name in the agent log directory. If a URL is specified (typically the URL Note that if you log observations within a file, you can also use the following setting:
|
|
Maximum number of agents allowed to run concurrently (should be equal to The default value is 1. |
|
When all agent identities are being used, this property defines how long (in ms) the .Net Agent will wait before trying to retrieve agent identity again. The default value is 10 seconds. |
|
When all agent identities are being used and the .Net Agent is trying to retrieve agent identity again, this property defines after how many times of trying, the .Net Agent will write a log to inform user that it is still trying. The first trying will always be logged. The default value is 120. |
Proxy and Gateway Settings
If you are installing and provisioning the APM .Net Agent in environments that require the use of proxy servers, use these additional options. Contact your network administrator for these values.
Proxy Parameters
Option | Description |
---|---|
oracle.apmaas.agent.proxyHost |
The proxy server’s host name. This is an optional parameter. |
oracle.apmaas.agent.proxyPort |
The proxy server’s port. This is an optional parameter. |
oracle.apmaas.agent.proxyAuthUser |
This is the user name the agent will use if the proxy server requires authentication. |
oracle.apmaas.agent.proxyAuthPassword |
This is the password required if the proxy server requires authentication. |
oracle.apmaas.agent.proxyAuthDomain |
This is the name of the domain if the proxy server requires authentication. |
If you are installing and provisioning the APM .Net Agent in environments that require the use of Gateway, use these additional options. Contact your network administrator for these values.
Gateway Parameters
Option | Description |
---|---|
oracle.apmaas.agent.uploadRoot |
The APM agent’s root directory. |
oracle.apmaas.agent.collectorRoot |
The APM agent’s collector root. |
Disable Browser Agent Monitoring by APM .Net Agent
In the APM .Net Agent’s configuration file, make the following settings:
-
To disable monitoring:
oracle.apmaas.agent.enableBrowserAgent=false
-
To disable specific URLs:
oracle.apmaas.agent.jsinjection.disableRegex=<regex>
-
Add
oracle.apmaas.agent.browser.observations