Configuration

How to set configuration

All configuration options can be set in the agent.config file.

Note

You must restart your application in order for any changes to take effect. For IIS websites, you can run iisreset to restart.

Certain configurations can also be overridden via a system environment variable. If the same configuration is set in both places (for example, service key in both system environment variable APPOPTICS_SERVICE_KEY and agent.config ServiceKey), then the setting is applied with this precedence:

System Environment Variable > Configuration in agent.config File

.NET Framework Agent

The agent.config file is located under the .NET agent directory C:\Program Files\AppOptics\APM\dotnet.

.NET Core SDK

The agent.config file is included in the AppOptics.Instrumentation nuget package. It is configured within the nuget package to be deployed along with the application that includes the AppOptics.Instrumentation nuget package. The location of the agent.config file can also be set using the system environment variable APPOPTICS_CONFIG.

Change the logging configuration

The default logging level is ‘Info’. This the minimum severity required to report Info, Warning, Error and Fatal messages to the logs. By default one log file per app is created in \TEMP\AppOptics (where TEMP is the system environment variable: TEMP) with a timestamp as part of its naming convention. The file ages out periodically at which point a new file is created. Segmenting the log history this way makes logs a little easier to search and handle. To protect hosts against disk space issues, logs may be written only if there is sufficient disk space; older files are purged; and they are subject to a maximum size. Once the max file size is reached, no logs are written until a new file is created. This occurs either when the current file ages out, or if the current file is renamed, a new file will be created immediately.

Disable tracing for static files

You can disable tracing for static files using the URL sample rate config. Basically you add an instrumentation block to the bottom of agent.config. That block should contain a regular expression describing the file extensions you want to exclude, plus a trace mode setting. An example is included in agent.config itself. You must restart your application in order for any changes to take effect.

...
</appSettings>
  <instrumentation>
    <urlSampleRates>
      <!-- Setting a URL Specific Tracing Mode or Sample Rate -->
      <!--   Element: urlSampleRate -->
      <!--   Attributes: -->
      <!--     urlMatch (regular expression to match against the url with the protocol removed) -->
      <!--     tracingMode (Never) -->
      <!--       -If the tracingMode is Never the sampleRate must not be set.-->
      <!--     sampleRate (Valid values are any integer between 0 and 1000000 (100%))-->
      <!--   Example: -->
      <!--     <urlSampleRate urlMatch=".*\.(png|jpg|jpeg|gif)" tracingMode="Never" /> -->
      <!--     <urlSampleRate urlMatch=".*\admin\.*" sampleRate="300000" /> -->
    </urlSampleRates>
  </instrumentation>
</configuration>

Configure the service key for an application pool

Note

The application pool configuration is only applicable to the .NET Framework Agent.

There are two options for setting an application pool specific service key. With both options after updating the configuration an iisreset is required for the updated settings to take effect.

Option 1 - Environment Variable

Note

This option is only applicable to servers using IIS 10.

Starting at IIS 10 support was added for setting application pool specific environment variables.

The appcmd.exe command line tool located at: %windir%\System32\inetsrv can be used to add and remove application pool specific environment variables.

Command to add an environment variable: appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='app_pool_name'].environmentVariables.[name='APPOPTICS_SERVICE_KEY',value='service_key']" /commit:apphost

Command to remove an environment variable: appcmd.exe set config -section:system.applicationHost/applicationPools /-"[name='app_pool_name'].environmentVariables.[name='APPOPTICS_SERVICE_KEY',value='service_key']" /commit:apphost

For more information see: IIS 10 Documentation:

Option 2 - Configuration File

You can also configure an application pool specific key by using the ApplicationPools config section in the agent.config file. Basically you add an instrumentation block to the bottom of agent.config. That block should contain a list of application pools identified by name and the service key that should be used for that application pool. If the main service key should be used for an application pool then that application pool does not need to be added to the agent.config. An example is included in agent.config itself. You must run iisreset in order for any changes to take effect.

...
</appSettings>
  <instrumentation>
    <applicationPools>
      <!-- Optional Configuration: This section can be used for application pool specific configuration. -->
      <!--   Element: applicationPool -->
      <!--   Attributes:  -->
      <!--     name: The name of the application pool. -->
      <!--     serviceKey: If the application pool should be identified as a different service than a specific Service Key can be specified. -->
      <!--                 The Service Key can be created and found in the AppOptics web interface. -->
      <!--     appOptics: Optional attribute. Valid Options: Disabled, Enabled -->
      <!--                The default option is Enabled. To disable AppOptics for an application pool set the appOptics attribute to Disabled. -->
      <!--  Example:  -->
      <!--    <applicationPool name="application_pool_name" serviceKey="[API-TOKEN]:[SERVICE-NAME]"/> -->
    </applicationPools>
  </instrumentation>
</configuration>

Configure the service key for an IIS site

Note

The IIS site configuration is only applicable to the .NET Framework Agent.

After updating the configuration an iisreset is required for the updated settings to take effect.

Configuration File

You can configure a specific key for an IIS site by using the iisSites config section in the agent.config file. Basically you add an instrumentation block to the bottom of agent.config. That block should contain a list of IIS sites identified by name and the service key that should be used for that IIS site. An service key does not need to be configured for each IIS site. If the application pool that the IIS site uses has a service key configured then the application pool service key will be used. Otherwise, if neither the IIS site nor the corresponding application pool has a service key configured then the main service key will be used. An example of the iisSites configuration is included in agent.config itself. You must run iisreset in order for any changes to take effect.

...
</appSettings>
  <instrumentation>
    <iisSites>
    <!-- Optional Configuration: This section can be used for IIS Site specific configuration. -->
    <!--   Element: iisSite -->
    <!--   Attributes:  -->
    <!--     name: The name of the IIS Site. -->
    <!--     hostName: Optional attribute. The host name can be specified, if a service also needs to be separated by host names. -->
    <!--     serviceKey: If the IIS Site should be identified as a different service from other sites in an application pool than a specific Service Key can be specified. -->
    <!--                 If a virtual directory needs to be identified as a different service than the format for the name must -->
    <!--                 combine the IIS Site name and Virtual Directory name in this format: "iis_site_name/virtual_directory_name" -->
    <!--                 The Service Key can be created and found in the AppOptics web interface. -->
    <!--  Example:  -->
    <!--    <iisSite name="iis_site_name" serviceKey="[API-TOKEN]:[SERVICE-NAME]"/> -->
    <!--    <iisSite name="iis_site_name/virtual_directory_name" serviceKey="[API-TOKEN]:[SERVICE-NAME]"/> -->
    <!--    <iisSite name="iis_site_name" hostName="host.domain.com" serviceKey="[API-TOKEN]:[SERVICE-NAME]"/> -->
    </iisSites>
  </instrumentation>
</configuration>

Complete config options

The following is the complete list of instrumentation configuration options.

ServiceKey

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
ServiceKey
system environment variable
APPOPTICS_SERVICE_KEY
description

The Service Key is required during the installation of the .NET agent and is set in the agent.config file by the installer. If the .NET agent is manually installed, the installer prompts for the Service Key. If the .NET agent is installed using the command line, the Service Key must be specified in the ‘conf.inf’ file.

Note

the ServiceKey in agent.config is required. Use APPOPTICS_SERVICE_KEY only to override the value set in agent.config.

history
Introduced in original version of .NET instrumentation
example
<add key="ServiceKey" value="398fc234fedcb23063826cba723ba67bc82840234dacb3bdb42bab35482bab35:service_name" />

AppOptics

supported .NET agent versions
.NET Framework Agent
config option
AppOptics
description
Configuration option to disable AppOptics. The ApplicationPools element below can be used to enable or disable specific application pools.
valid values
Disabled, Enabled. Default: Enabled.
history
Added in 3.4.0 release
example
<add key="AppOptics" value="Disabled" />

HostnameAlias

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
HostnameAlias
description
An optional logical/readable hostname that can be used to easily identify the host. If configured, the hostname alias will be displayed and will be able to be used as a filter in the AppOptics dashboard.
history
Added in 3.0.1 release
example
<add key="HostnameAlias" value="prod_host_a1" />

SQLSanitizationMode

supported .NET agent versions
.NET Framework Agent
config option
SQLSanitizationMode
description
The .NET instrumentation has the ability to sanitize query literals from sql statements. By default this is disabled. Set to one of the other options to avoid collecting and reporting query literals to AppOptics.
valid values
Disabled
Disable sanitization of query literals.
Auto
Remove literals, auto-detecting literal quotes.
DropDoubleQuotes
Remove literals and double-quoted values.
KeepDoubleQuotes
Remove literals but keep double-quoted values.
history
Introduced in original version of .NET instrumentation
example
<add key="SQLSanitizationMode" value="Disabled" />

urlSampleRate

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
urlSampleRate
description
Disable tracing for URLs matching a user-configurable regular expression.
parameters
urlMatch
A regular expression. Matching URLs will honor the trace mode that follows. There are no defaults, which means that tracing is not disabled for any static files or URLs by default.
tracingMode
Set to ‘Never’ to disable tracing for matching URLs, otherwise do not set this attribute.
sampleRate
This attribute can be used if an increase in traces for a particular endpoint is required.
history
Introduced in original version of .NET instrumentation
example
See disable tracing for static files.

Inlining

supported .NET agent versions
.NET Framework Agent
config option
Inlining
description
If a method is inlined by CLR, it cannot be instrumented. You can disable inlining for all applications through this config option. See the troubleshooting section Are custom instrumentation spans or other spans missing from traces? for more information.
valid values
Disabled, Enabled. Default: Enabled.
history
Introduced in original version of .NET instrumentation
example
<add key="Inlining" value="Disabled" />

SecurityTransparencyInstrumentation

supported .NET agent versions
.NET Framework Agent
config option
SecurityTransparencyInstrumentation
description
If an assembly has the SecurityTransparent attribute then any methods instrumented in it might cause a System.Security.VerificationException to occur, and a web request that invokes those instrumented methods might fail. By default instrumentation of SecurityTransparent assemblies is disabled but it can be enabled with this config option.
valid values
0
(Default) Disable instrumentation for security transparent assemblies. When this value is set, instrumentation will be disabled for MVC3 and MVC4.
1
Enable instrumentation for security transparent assemblies. When this value is set, MVC3 will be instrumented but MVC4 will not.
2
Set the <a href=”https://msdn.microsoft.com/en-us/library/ms231874(v=vs.110).aspx” target=”_blank”>compiler flag</a> that disables transparency checks. When this value is set, System.Security.VerificationException won’t occur even if both the SecurityTransparent attribute and AppOptics instrumentation are present.
history
Introduced in original version of .NET instrumentation
example
<add key="SecurityTransparencyInstrumentation" value="1" />

LogCreationSchedule

supported .NET agent versions
.NET Framework Agent
config option
LogCreationSchedule
description
Specify when the current log file ages out and a a new log file should be generated.
valid values
Daily or Weekly. The default is Daily.
history
Introduced in original version of .NET instrumentation
example
<add key="LogCreationSchedule" value="Daily" />

LogFileMaxSize

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
LogFileMaxSize
description
The maximum size, in bytes, that a log file may be. After the maximum is reached, no additional messages will be written to it. Log messages will be written again once a new log file is generated. The default is 10000000 (10 MB).
history
Introduced in original version of .NET instrumentation
example
<add key="LogFileMaxSize" value="10000000" />

LogLevel

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
LogLevel
description
Change the logging severity level. The default is ‘info’, which is the minimum level required to capture trace events, e.g., entry, exit, etc.
valid values

In order of descending: Fatal, Error, Warning, Info, Debug, Trace, none.

Fatal
An error caused .NET instrumentation to stop.
Error
Any error caused an instrumented trace to fail.
Warning
An issue such as an unexpected configuration value, but the .NET instrumentation can still generate traces.
Info
Logging items such as configuration settings that were loaded on start up.
Debug
Diagnostic information used by customer care to resolve technical issues.
Trace
Highest level of logging. Logs functions called, exception stack traces, etc.
none
No logging.
history
Introduced in original version of .NET instrumentation
example
<add key="LogLevel" value="Info" />
Note
Levels Info and higher do not log messages per request when the .NET agent is running as expected.

LogRetentionDays

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
LogRetentionDays
description
Retain old log files for the specified number of days, after which they will be deleted. The default is 45 days.
history
Introduced in original version of .NET instrumentation
example
<add key="LogRetentionDays" value="45" />

ReserveDiskSpace

supported .NET agent versions
.NET Framework Agent
config option
ReserveDiskSpace
description
The amount of disk space, in bytes, that must be available before messages can be written to a log file. Log messages will not be written if there is insufficient disk space. The default is 200000000 (200 MB).
history
Introduced in original version of .NET instrumentation
example
<add key="ReserveDiskSpace" value="200000000" />

IncludeQueryString

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
IncludeQueryString
description
By default the query string parameters are included in the URL’s reported in IIS spans. Set the IncludeQueryString configuration to Disabled if query string parameters should be excluded from URL’s reported in IIS spans.
valid values
Disabled, Enabled. Default: Enabled.
history
Introduced in 3.1.1 .NET instrumentation
example
<add key="IncludeQueryString" value="Disabled" />

PrependDomain

supported .NET agent versions
.NET Framework Agent and .NET Core SDK
config option
PrependDomain
description
Optional configuration: Used to indicate if the domain should be prepended to the transaction name.
valid values
Disabled, Enabled. Default: Disabled.
history
Introduced in 3.2.0 .NET Framework Agent. Introduced in 3.3.2 for .NET Core SDK.
example
<add key="PrependDomain" value="Enabled" />

applicationPool

supported .NET agent versions
.NET Framework Agent
config option
applicationPool
description
Optional configuration, is used for application pool specific configuration.
parameters
name
The name of the application pool.
serviceKey
If the application pool should be identified as a different service than a specific Service Key can be specified.
appOptics
Optional attribute. Valid Options: Disabled, Enabled. The default option is Enabled. To disable AppOptics for an application pool set the appOptics attribute to Disabled.
history
The applicationPool element was introduced in 3.0.3 .NET instrumentation. The appOptics attribute was introduced in 3.4.0 .NET instrumentation.
example
See Configure the service key for an application pool - Option 2 Configuration File.

iisSite

supported .NET agent versions
.NET Framework Agent
config option
iisSite
description
Optional configuration, is used for IIS site specific configuration.
parameters
name
The name of the IIS site.
serviceKey
If the IIS site should be identified as a different service from other sites in an application pool than a specific Service Key can be specified. If a virtual directory needs to be identified as a different service than the format for the name must combine the IIS site name and virtual directory name in this format: “iis_site_name/virtual_directory_name”
hostName
Optional attribute. The host name can be specified, if a service also needs to be separated by host names.
history
Introduced in 3.1.1 .NET instrumentation
example
See Configure the service key for an IIS site.

application

supported .NET agent versions
.NET Framework Agent
config option
application
description
Optional configuration, is used for configuring non-IIS applications.
parameters
name
The name of the application to instrument.
serviceKey
Optional attribute. If the application is a different service than a specific Service Key for this application can be specified.
inlining
Optional attribute. Valid Options: Disabled, Enabled. If the inlining attribute is not set in the application element, the appSettings Inlining value is used.
appOptics
Optional attribute. Valid Options: Disabled, Enabled. The default option is Enabled. To disable AppOptics for an application set the appOptics attribute to Disabled.
history
The application element was introduced in original version of .NET instrumentation. The appOptics attribute was added in 3.4.0 .NET instrumentation.
example
<application name="ApplicationToInstrument1.exe" serviceKey="[API-TOKEN]:[SERVICE-NAME]" />