9 Install and Configure APM .NET Agent

Topics:

• Agent Requirements and Installation Instructions

• Verify the APM .NET Agent Installation

• Configure APM .NET Agents

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)

A gateway is not a mandatory component while deploying Oracle Application Performance Monitoring. Use the gateway in the following scenarios:

• 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)

For instructions on how to deploy the gateway, see Instal a Gateway in Installing and Managing Oracle Management Cloud Agents.

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

1. From the main Oracle Management Cloud menu, navigate to Administration and Agents.

2. 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.

3. From the Agent Type dropdown list, select APM Agent.

4. Click APM .Net Agent.

5. Extract the contents of the installer ZIP file.

6. Click Done after the download is complete.

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

8. 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:

1. 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

2. Stop the IIS server.

   iisreset /stop

3. Execute the APM .Net Agent installer.

4. Ensure that the AgentConfig.info file is in the same directory as the ApmAgent.msi file.

5. Run the ApmAgent.msi executable. The APM .Net Agent installation wizard guides you through the installation process.

6. The Installation wizard performs a check of these pre-requisites before proceeding with the installation:

   1. User without administration privileges

   2. If IIS is installed

   3. If IIS is installed without ASP .Net

   4. If the user does not have the permission to access this path — "C:\Windows\System32\inetsrv\config\applicationHost.config"

   A warning is displayed if any of the pre-requisites are not met.

   • 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.

7. Specify the installation directory.

8. Optionally, select Configure Proxy and specify the proxy information. The password that you specify here is encrypted to enhance security.

9. Optionally, select Configure Gateways and specify the Gateway information.

10. 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.

11. In the Set Host Name field, review the default host name, and modify if required.

12. 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.

13. Click Install.

14. 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>

15. 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.

To manually configure applications to be monitored by APM .Net Agent:

1. Disable monitoring globally for the APM .Net Agent.

   1. In the installation directory, check the global AgentConfig.ini file. By default, the installation directory is C:\Program Files\Oracle APM .NET Agent.

   2. Disable global monitoring for all applications with this setting:

      oracle.apmaas.agent.disable=true

2. Enable monitoring for a specific application.

   1. Navigate to the Agent’s instance directory: C:\ProgramData\Oracle\ApmAgent\config\<webSite><webApplication>.

   2. Edit the AgentConfig.ini file and enable monitoring with this setting:

      oracle.apmaas.agent.disable=false

      Repeat this for every application to be monitored.

Verify the APM .NET Agent Installation

1. Use the Oracle Application Performance Monitoring Web Console
2. Examine the APM .Net Agent logs located at C:\ProgramData\Oracle\ApmAgent\logs\<site>\.
   Note that the log files are not initially created, even if the installation of APM was successful. The log files get created and populated only when the application you are monitoring is running, and shows some activity which results in data depicted on the Oracle Application Performance Monitoring Web UI.

   • If the agent logs are empty without any data, check the Windows Event Viewer for any possible problems with the agent installation. (See Custom Views and select Administrative Events.)

   • If you see the following message

     The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel

     in the agent logs, it means that the Oracle Management Cloud certificate was not provisioned since the certificate was not available. Add the root certificate emcs.cer to the trusted root certification authorities on your local machine. See https://technet.microsoft.com/en-in/library/cc754841.aspx#BKMK_addlocal.

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

• Configuration Directory

• Logs Directory

• Important Considerations

• Configuration Settings

• Proxy and Gateway Settings

• Disable Browser Agent Monitoring by APM .Net Agent

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

The APM .Net Agent logs directory contains three log files: 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 in AgentStartup.

The change the level of logging in these files, see Configuration Settings.

Important Considerations

Some important considerations before configuring the parameters:

1. Any change to the installed configuration files (AgentConfig.ini and OMC.ini), applies to all agent instances running on the machine.

2. 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 or OMC.ini), all agents on the machine restart reading the changed configuration files as they start up. If a specific AgentConfig.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).
oracle.apmaas.agent.trace.bootstrap.limitoracle.apmaas.agent.trace.bootstrap.rotation	AgentBootstrap log file settings — Rotation default is 2 Limit default is 20 Mb Limit indicated in Mbs (Example: 10 for 10 Mb)
oracle.apmaas.agent.trace.startup.limit oracle.apmaas.agent.trace.startup.rotation	AgentStartup log file settings — Rotation default is 2 Limit default is 20 Mb Limit indicated in Mbs (Example: 10 for 10 Mb)
oracle.apmaas.agent.trace.status.limit oracle.apmaas.agent.trace.status.rotation	AgentStatus log file settings — Rotation default is 2 Limit default is 20 Mb Limit indicated in Mbs (Example: 10 for 10 Mb)
oracle.apmaas.agent.trace.limit oracle.apmaas.agent.trace.rotation	Agent log file settings — Rotation default is 2 Limit default is 20 Mb Limit indicated in Mbs (Example: 10 for 10 Mb)
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>	All trace areas level: verbose, all, off
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.
oracle.apmaas.agent.trace.observations = verbose	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.
oracle.apmaas.agent.testServerUrl = file | url OR oracle.apmaas.agent.trace.observations.locationUrl = file | url	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 AgentCLI listens on), observations will be sent to the specified URL. If the agent is setup to communicate with cloud services, observations will be sent both to cloud services and to the specified URL. To disable communication with cloud services and only have the agent communicate with the specific URL, set the property oracle.apmaas.agent.test.skipCloudStartup=true Note that if you log observations within a file, you can also use the following setting: oracle.apmaas.agent.trace.observations.maxSizeMB (same as limit, defined for Java cross platform compatibility) oracle.apmaas.agent.trace.observations.limit (same semantic as limit described above) oracle.apmaas.agent.trace.observations.rotation (same semantic as rotation described above) oracle.apmaas.agent.trace.observations.prettyPrint (set it to true, to pretty print logged observations)
oracle.apmaas.agent.identity.concurrent.max	Maximum number of agents allowed to run concurrently (should be equal to max_worker_proecess defined in ApplicationPool. The default value is 1.
oracle.apmaas.agent.lock.identity.waitInMs	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.
oracle.apmaas.agent.lock.identity.waitTimesToWriteLog	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