Install .NET Framework Agent¶
Getting the agent¶
There is a .NET agent installer which installs the required dlls and
configuration files under
Program Files\AppOptics\APM\dotnet
.
- Download the installer from https://files.appoptics.com/dotnet/DotNetAgent_Setup.exe
- Stop IIS by running
iisreset /STOP
via the command line. - Run the installer and provide your service key when requested. The installer also supports command line install
- Start IIS by running
iisreset /START
via the command line. - Now requests to an instrumented application pool under IIS will be traced, and you’ll see data in the AppOptics dashboard shortly.
Troubleshooting¶
After installing the agent if traces and metric data do not appear in the AppOptics dashboard, please review the Troubleshooting page for tips on how to resolve.
Diagnostics¶
A connectivity diagnostic tool is available with the .NET Framework Agent. To run it, open a command prompt and run the executable dotnet_diagnostic_tool.exe
located in the agent install directory:
C:\Program Files\AppOptics\APM\dotnet> dotnet_diagnostic_tool.exe
The optional parameters are:
- /ServiceKey : Service key to be used for the diagnostic tool. By default it uses the current service key configured configured globally for the host, it does not pick up any service keys defined at the
<iisSites>
,<applicationPools>
or<applications>
levels. - /Verbose : Enable printing to console of verbose level log messages from the diagnostic run.
For example, to verify connection using a specific service key:
C:\Program Files\AppOptics\APM\dotnet> dotnet_diagnostic_tool.exe /ServiceKey 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service
Look for the message Has connection succeeded? YES
which indicates that the connection has succeeded.
If there are any errors, see the log file C:\Program Files\AppOptics\APM\dotnet\dotnet_diagnostic_tool.log
.
The diagnostic tool provides exit code as below:
Exit Status Code | Name | Description |
---|---|---|
0 | OK | Diagnostics successful |
101 | UNKNOWN_ERROR | Unexpected error. See error message for details |
102 | INVALID_FORMAT_ARGUMENT | Argument passed to the diagnostic tool is not in valid format. For example the service key is too short. See error message for details |
103 | INVALID_ARGUMENTS | Argument passed to the diagnostic tool is incorrect. For example using argument name not recognized by the diagnostic. See error message for details |
104 | INVALID_SERVICE_KEY | Service key is rejected by AppOptics server |
105 | CONNECTION_FAILURE | Failed to connect to the AppOptics server within the timeout limit of 5 seconds. |
106 | TRY_LATER | AppOptics server rejected the diagnostic request with status TRY_LATER |
107 | LIMIT_EXCEEDED | AppOptics server rejected the diagnostic request with status LIMIT_EXCEEDED |
Command Line Install¶
To automate the installation of the AppOptics .NET Agent, the agent can be installed via the command line.
Create a file called
conf.inf
with the following contents, and place it in the same directory as your installer.[Setup] service_key=*service-key*
Run following command:
# to install the .net agent via the command line # square brackets indicate an optional parameters # the pipe character separates multiple choices within an option # for /COMPONENTS specify "IISOnly,NonIISApplications" to instrument non-IIS applications as well. DotNetAgent_Setup.exe [/SILENT | /VERYSILENT] /LOADINF="conf.inf" /COMPONENTS="IISOnly[,NonIISApplications]" [/CLOSEAPPLICATIONS | /NOCLOSEAPPLICATIONS]
To start tracing, restart the application pools in which your apps are running via the
iisreset
command-line tool.
Command Line Options¶
Below is the list of supported command line options for the installer:
/CLOSEAPPLICATIONS
– this flag instructs the installer to close applications using files that need to be updated, if possible./COMPONENTS="IISOnly"
– this option allows specifying a comma separated list of components selected. Valid components areIISOnly
(default) andNonIISApplications
./LOADINF="conf.inf"
– this option instructs the installer to load settings from the specified file./LOG="filename"
– the installer currently creates a “Setup Log .txt” file but the uninstall process doesn’t create a log file. The “/LOG=filename” option can be used to create a log file for the uninstall./NOCLOSEAPPLICATIONS
– this flag prevents the installer from closing applications using files that need to be updated./NOCONNECTIVITYCHECK
– this flag prevents the installer from running the connectivity diagnostic checks. The diagnostics can take 2 to 3 seconds so this flag can be used when install/uninstall speed is important./NORESTART
– this flag prevents the installer from running a system restart following an install or uninstall./RESTARTEXITCODE=exitcode
– this option allows specifying a custom exit code that the installer returns if the system needs to be restarted following a successful installation or uninstall./SILENT
– this flag instructs the installer to be silent, the installation progress window is displayed./VERYSILENT
– this flag instructs the installer to be very silent, the install progress window is not displayed.
Instrumenting Non-IIS Applications¶
To instrument non-IIS applications, add the following snippet to the agent config file, which is in Program Files\AppOptics\APM\dotnet
:
<applications>
<!-- add one line for each non-IIS application that should be instrumented -->
<application name="non-iis_application_file_name.exe" />
</applications>
Note
Standalone WCF services will be instrumented automatically. Other types of non-IIS applications must be instrumented using the custom instrumentation SDK.
The application will need to be restarted after updating the agent config file to start tracing.
Log File Locations¶
AppOptics installers and agents log detailed information about problems they run into, which can provide helpful information during troubleshooting.
- Records of the instrumentation install process are in:
C:\Program Files\AppOptics\APM\dotnet\instrumentation_setup.log
for agent versions up to 3.5.0C:\Program Files\AppOptics\APM\dotnet\AppOptics.NETAgent.Install.<dd-mm-yyyy>.log
for agents starting from version 3.5.1
- Records of running instrumentation are in
C:\Windows\TEMP\AppOptics\DotNetAgentLog*
.
Uninstalling the Agent¶
Note
The uninstall executable is named unins<nnn>.exe
, where nnn is a number
that starts at 000 and increments on each agent re-install. The examples
below will use unins000.exe
.
Stop IIS by running
iisreset /STOP
via the command line.Run the .NET agent uninstaller
C:\Program Files\AppOptics\APM\dotnet\unins000.exe
, or follow the instructions below to uninstall the agent via the command line.# square brackets indicate an optional parameters # the pipe character separates multiple choices within an option C:\Program Files\AppOptics\APM\dotnet\unins000.exe [/SILENT | /VERYSILENT] [/CLOSEAPPLICATIONS | /NOCLOSEAPPLICATIONS]
Start IIS by running
iisreset /START
via the command line.