Documentation forSolarWinds Observability SaaS

Configure the .NET Library

See the following sections for information about the configuration options available for the .NET Library and how to set them.

How to set configuration options

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

Some configuration options can also be set through an environment variable. If an environment variable can be used, it is listed in the description of the configuration option.

If the same configuration option is set in both a config file and an environment variable, the setting is applied with the following precedence:

  1. Environment variable
  2. Application-level solarwinds_apm.config file
  3. Global solarwinds_apm.config file

After you change any configuration options, you must restart your application for the changes to take effect. For IIS websites, you can run iisreset to restart.

Config file location

You can find the config file in one of the following locations.

.NET Library for Windows

The solarwinds_apm.config file is located under the .NET Library directory %PROGRAMFILES%\SolarWinds\APM\dotnet.

.NET Library for Linux

The solarwinds_apm.config file is located under the .NET Library installation directory, which should also be set in the environment variable SW_APM_HOME_DOTNET. For example, if you installed the library to ${HOME}/SolarWinds, the config file is located at ${HOME}/SolarWinds/solarwinds_apm.config.

If the solarwinds_apm.config config file is moved to a non-default location, set the location of the file in the environment variable SW_APM_CONFIG by specifying the path of the directory that contains the config file. For example, if it is located at /opt/custom/directory/solarwinds_apm.config, set SW_APM_CONFIG to /opt/custom/directory.

SolarWindsAPM.Agent NuGet package

The solarwinds_apm.config file is included in the SolarWindsAPM.Agent NuGet package. It is configured within the NuGet package to be deployed along with the application that includes the SolarWindsAPM.Agent NuGet package.

The global solarwinds_apm.config included with the .NET Library will take precedence over a solarwinds_apm.config deployed with the application, unless the environment variables have been configured for the application process.

If the .NET Library is installed with NON-IIS selected (.NET Framework and/or .NET 6+), the environment variables are set at a system level and the global solarwinds_apm.config file is used by default. If the environment variables had been set for the application process, the application-specific solarwinds_apm.config is used.

If the solarwinds_apm.config config file is moved to a non-default location, set the location of the file in the environment variable SW_APM_CONFIG by specifying the path of the directory that contains the config file. For example, if it is located at C:\custom\directory\solarwinds_apm.config, set SW_APM_CONFIG to C:\custom\directory.

Logging configuration options

The following configuration options affect the information written to the logs.

The LogLevel option specifies the severity level of the events that are logged. The default value, Info, logs events with severity levels of Info and higher (Warning, Error, and Fatal).

By default, one log file per app is created in %TEMP%\SolarWinds (where %TEMP% is the environment variable: TEMP) on Windows platforms or /var/tmp/solarwinds on Linux platforms, with a timestamp as part of its naming convention. The file ages out periodically (daily, by default), and a new file is created. Segmenting the log history this way makes logs easier to search and handle. Use the LogCreationSchedule option to change how often the file ages out.

Logs are written only if there is enough disk space. To avoid disk space issues:

  • Older files are automatically deleted. Use the LogRetentionDays option to specify how many days to retain log files.

  • Log files have a maximum size, which can be specified with the LogFileMaxSize option. After the maximum file size is reached, nothing else is written to the log until a new file is created. A new file is created when the current file ages out or if the current file is renamed.

Disable tracing on transactions

You can exclude transactions from being traced by adding an <instrumentation><transactionSettings> block to the bottom of solarwinds_apm.config to disable tracing for particular requests, such as static files or health-check endpoints. This block should contain a list of transactionSetting entries that specify either a list of file extensions or a regular expression describing the URLs you want to exclude, plus a tracing setting. An example is included in solarwinds_apm.config itself. You must restart your application for any changes to take effect.

...
</appSettings>
  <instrumentation>
    <transactionSettings>
      <!-- Settings for specific transactions -->
      <!--  Element: transactionSetting -->
      <!--  Attributes: -->
      <!--   applicationPool: Optional attribute. If set the transaction configuration will only be applied to the application pool specified. -->
      <!--   application: Optional attribute. If set the transaction configuration will only be applied to the application specified. -->
      <!--   type: Required attribute. (Valid option: Url) -->
      <!--   One of extensionList or regexMatch is required. -->
      <!--   extensionList: Optional attribute. Comma separated list of file extensions. -->
      <!--   regexMatch: Optional attribute. Regular expression to match against. -->
      <!--   tracing: Required attribute. (valid options: Enabled, Disabled) -->
      <!--  Examples: -->
      <!--   <transactionSetting type="Url" extensionList=".js,.css,.png,.ico" tracing="Disabled" /> -->
      <!--   <transactionSetting applicationPool="app-pool-1" type="Url" regexMatch=".*long-transaction.*" tracing="Disabled" /> -->
    </transactionSettings>
  </instrumentation>
</configuration>

Enable or disable code profiling

Code profiling is currently only supported by the .NET Library for Windows.

To enabled code profiling use the Profiling setting in the solarwinds_apm.config file.

For more information, see Code Profiling.

Configure the Service key for an application pool

The application pool configuration is applicable only to the .NET Library for Windows.

You can set an application-pool-specific Service key with an environment variable or by editing the config file. With either options, after you update the configuration an iisreset is required for the updated settings to take effect.

The same API token should be used for every service key defined in your process.

Configure the Service key with an environment variable

The IIS site configuration is only applicable to the .NET Library for Windows.

IIS 10 and later supports setting application-pool-specific environment variables.

You can use the appcmd.exe command line tool to add and remove application-pool-specific environment variables. This tools is located in the %windir%\System32\inetsrv folder.

Use the following command to add an environment variable: 

appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='app_pool_name'].environmentVariables.[name='SW_APM_SERVICE_KEY',value='YourServiceKey']" /commit:apphost

Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Use the following command to remove an environment variable: 

appcmd.exe set config -section:system.applicationHost/applicationPools /-"[name='app_pool_name'].environmentVariables.[name='SW_APM_SERVICE_KEY',value='YourServiceKey']" /commit:apphost

Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

For more information see the IIS 10 Documentation.

Configure the Service name in the config file

You can also configure an application pool-specific Service name by editing the ApplicationPools config section in the solarwinds_apm.config file. To do so, add an instrumentation block to the bottom of solarwinds_apm.config. That block should contain a list of application pools identified by name and the Service name 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 solarwinds_apm.config. An example is included in solarwinds_apm.config itself. You must run iisreset 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. -->
      <!--   serviceName: Optional attribute. If the application pool should be identified as a different service than a specific service name can be specified. -->
      <!--         The service name only allows numbers, lowercase letters and special characters " - " " . " " _ ". -->
      <!--         The ServiceKey configuration setting above must be set as the Api Token contained in it will be -->
      <!--         used when sending telemetry data for the configured application pool. -->
      <!--   apmAgent: Optional attribute. Valid Options: Disabled, Enabled -->
      <!--        The default option is Enabled. To disable the library for an application pool set the apmAgent attribute to Disabled. -->
      <!--   iisInstrumentation: Optional attribute. Valid Options: DisabledIISFramework, DisabledIISCore, Enabled  -->
      <!--        The default option is Enabled. -->
      <!--        To disable .NET Framework instrumentation set the iisInstrumentation attribute to DisabledIISFramework. -->
      <!--        To disable .NET Core or .NET 5.0 instrumentation set the iisInstrumentation attribute to DisabledIISCore. -->	
      <!-- Example: -->
      <!--  <applicationPool name="application_pool_name" serviceName="your-service-name"/> -->
    </applicationPools>
  </instrumentation>
</configuration>

Replace your-service-name with your chosen name for this service.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service name.

Configure the service name for an IIS site

The IIS site configuration is applicable only to the .NET Library for Windows.

You can configure a specific Service name for an IIS site by editing the iisSites config section in the solarwinds_apm.config file. To do so, you add an instrumentation block to the bottom of solarwinds_apm.config. That block should contain a list of IIS sites identified by name and the Service name that should be used for that IIS site. A Service name does not need to be configured for each IIS site. If the application pool that the IIS site uses has a Service name configured, then the application pool Service name is used. Otherwise, if neither the IIS site nor the corresponding application pool has a Service name configured, the main Service key is used. An example of the iisSites configuration is included in solarwinds_apm.config itself. You must run iisreset 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. -->
      <!--   serviceName: If the IIS Site should be identified as a different service from other sites in an application pool than a specific Service name can be specified. -->
      <!--         The service name only allows numbers, lowercase letters and special characters " - " " . " " _ ". -->
      <!--         The ServiceKey configuration setting above must be set as the Api Token contained in it will be used when sending -->
      <!--         telemetry data for the IIS sites configured. -->
      <!--         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" -->
      <!-- Example: -->
      <!--  <iisSite name="iis_site_name" serviceName="your-service-name"/> -->
      <!--  <iisSite name="iis_site_name/virtual_directory_name" serviceName="your-service-name"/> -->
      <!--  <iisSite name="iis_site_name" hostName="host.domain.com" serviceName="your-service-name"/> -->
    </iisSites>
  </instrumentation>
</configuration>

Replace your-service-name with your chosen name for this service.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service name.

Configure the Service key for a Windows service

You can configure a Service key for a Windows service by setting an environment variable, or you can configure a Service name by modifying the config file. It is required that you restart the Windows service after you set the environment variable or modify the config file.

Stand-alone WCF Windows services are instrumented automatically. Other types of Windows services must be instrumented using the custom instrumentation SDK.

Configure the Service name in the config file

You can configure the Service name for a Windows service by modifying the applications config section in the solarwinds_apm.config file. For each application the Windows service should run, add a new child application node to the applications node and set the value of the new node's name attribute as the name of the EXE file the Windows service runs and the value of the serviceName attribute as the service name.

An example application node for the WindowsServiceA application is:

<applications>
  <!-- add one line for each exe run by the Windows Service that should be instrumented -->  
  <application name="WindowsServiceA.exe" serviceName="windowsservicea"/>
</applications>

Configure the Service key with an environment variable

You can set the Service key for a process is by configuring an SW_APM_SERVICE_KEY environment variable. Complete the following steps to set an environment variable in the registry for a Windows service.

  1. Open the Registry Editor (regedit.exe).
  2. Expand the following:
    KEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
  3. Click the service name that corresponds to the process you want to add a Service key to.
  4. Click the Edit menu and select New > Multi-String Value.
  5. Type Environment in the string name, and press Enter.

  6. Double-click the newly created Multi-String Value (type REG_MULTI_SZ) to edit the multi-string value, and enter SW_APM_SERVICE_KEY=YourServiceKey in the Value data field.

    Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

    The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

    The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

  7. Click OK.
  8. Repeat steps 2 through 7 for each Windows process that needs to be configured.

Trace context in logs

Trace context as a string identifier can be added to logs to correlate log entries for a single transaction. See .NET trace context in logs for information about how this feature is supported in the .NET Library.

Application logs for your service entity are not included in the data sent by APM libraries. Configure your server or application to send application logs to SolarWinds Observability SaaS. See Add logs from services.

Use the following options to add the trace context for supported logging frameworks. With either option, the LoggedTraceId configuration variable can be used to specify whether the Trace Context is available for all transactions or only for sampled transactions.

Automatic insertion

Automatically insert the Trace Context into log messages. When Log4net is used, this feature is supported for unstructured layouts (PatternLayout or SimpleLayout). This feature is controlled by the InsertLogTraceIdIntoLogs configuration variable. See Automatic insertion.

Automatically created attribute

Automatically create Trace Context attribute values. The attributes can be referenced in the layout configurations. Structured layouts like XmlLayout use all available attributes to render the output. This feature is controlled by the AddAttributeLogTraceId configuration variable. See Automatic attribute.

All .NET Library configuration options

This section describes all available .NET Library instrumentation configuration options.

ServiceKey

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

ServiceKey

Environment variable

SW_APM_SERVICE_KEY

Description

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

The same API token should be used for every service key defined in your process.

The Service key is required during installation of the .NET Library on Windows, and it is set in the solarwinds_apm.config file by the installer. If the library is manually installed, the installer prompts for the Service key. If the library is installed using the command line, the Service key must be specified in the conf.inf file.

For the .NET Core SDK, the Service key is required during application runtime and can be set in either the solarwinds_apm.config file for Core SDK, or as an environment variable.

The ServiceKey option is required. SolarWinds recommends setting it in the solarwinds_apm.config file.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="ServiceKey" value="398fc234fedcb23063826cba723ba67bc82840234dacb3bdb42bab35482bab35:service_name" />

Collector

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

ApmCollector

Environment variable

SW_APM_COLLECTOR

Description

Set the collector value to define an ingestion endpoint and override the default SolarWinds APM collector endpoint. The value defined using the environment variable will take precedence over the ApmCollector setting in the solarwinds_apm.config file.

To find the endpoint URI for your organization's SolarWinds APM collector, see Data centers and endpoint URIs.

History

Introduced with version 5.1.0 of the .NET Instrumentation Library.

Example

<add key="ApmCollector" value="apm.collector.na-02.cloud.solarwinds.com" />

ApmAgent

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

ApmAgent

Description

Use this configuration option to disable the .NET Library. The ApplicationPools element below can be used to enable or disable specific application pools.

Valid values

Disabled  
Enabled (Default)

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="ApmAgent" value="Disabled" />

Trusted certificate path

The library uses the trusted CA certificates configured for the .NET library to verify the TLS connection to the collector. To override the default, define the trusted certificate path configuration option with an absolute path to a specific trusted certificate file in PEM format.

System environment variable

SW_APM_TRUSTEDPATH

Required

No

History

Introduced with version 5.0.0 of the .Net Instrumentation Library.

Examples

  • System environment variable (Linux)

    export SW_APM_TRUSTEDPATH=/path/to/cacert.pem

  • System environment variable (Windows PowerShell)

    $env:SW_APM_TRUSTEDPATH="C:\path\to\cacert.pem"

Tracing

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

Tracing

Description

Set Tracing to Disabled if requests should never be sampled and transaction metrics should not be reported.

Valid values

Disabled  
Enabled (Default)

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="Tracing" value="Disabled" />

HostnameAlias

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

HostnameAlias

Description

Use this to specify an optional descriptive host name that can be used to easily identify the host. If configured, the host name alias is displayed and can be used as a filter in the Traces Explorer.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="HostnameAlias" value="prod_host_a1" />

InsertSqlTag

Supported .NET Library versions

.NET Library

Config option

InsertSqlTag

Description

Optional configuration. This option enables or disables injecting trace context as a comment into the beginning of a SQL statement for sampled requests. Injecting trace context in queries is supported only for MySQL databases (MySql.Data.MySqlClient and MySqlConnector database providers) and Microsoft SQL Server databases under ADO.NET. See .NET trace context in queries.

Valid values

Disabled (Default) Injecting trace query context is disabled.
Enabled Injecting trace query context is enabled.

History

Introduced with version 5.1.1 of the .NET Instrumentation Library.

Example

<add key="InsertSqlTag" value="Enabled" />

InsertSqlTagDatabases

Supported .NET Library versions

.NET Library

Config option

InsertSqlTagDatabases

Description

This option enables or disables injecting trace context in queries for MySQL and Microsoft SQL Server databases. See .NET trace context in queries.

Valid values

MySql,MicrosoftSqlServer (Default) Enables trace query context in queries for MySQL and Microsoft SQL Server databases.
MySql Enables trace query context in queries for MySQL databases.
MicrosoftSqlServer Enables trace query context in queries for Microsoft SQL Server databases.

History

Introduced with version 5.3.5 of the .NET Instrumentation Library.

Example

<add key="InsertSqlTagDatabases" value="MySql" />

Ec2MetadataTimeout

Supported .NET Library versions

.NET Library

Config option

Ec2MetadataTimeout

Environment variable

SW_APM_EC2_METADATA_TIMEOUT

Description

Optional configuration. On library startup, the .NET Library checks to determine if the server is an AWS EC2 instance. The Ec2MetadataTimeout configuration can be used to adjust the timeout length of this check. If the library is not running on an AWS EC2 instance, it is safe to set this value to 0. A valid value is an integer between 0 and 3000. The EC2 metadata timeout is in milliseconds.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="Ec2MetadataTimeout" value="0" />

SQLSanitizationMode

Supported .NET Library versions

.NET Library

Config option

SQLSanitizationMode

Description

The .NET instrumentation has the ability to sanitize query literals from SQL statements. By default, literals are removed from SQL statements. The SQLSanitizationMode configuration option can be used to disable the sanitizing or change the type of sanitization used.

Valid values

Auto (Default) Removes literals, auto-detecting literal quotes.
DropDoubleQuotes Removes literals and double-quoted values.
KeepDoubleQuotes Removes literals but keeps double-quoted values.
Disabled Disables sanitization of query literals.
 

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="SQLSanitizationMode" value="Disabled" />

transactionSetting

Supported .NET Library versions

.NET Library and .NET Core SDK (SolarWinds Observability middleware)

Config option

transactionSetting

Description

Use this option to disable tracing for a transaction where the request URL matches a user-configurable regular expression or list of extensions. If more than one transactionSetting is defined, the first one matching the request URL is used. For the .NET Core SDK, the SolarWinds Observability middleware supports the transactionSetting configuration.

Parameters

applicationPool Optional attribute (supported only by .NET Library on Windows). Applies the transaction configuration only to the application pool specified.
application Optional attribute (supported only by .NET Library on Windows). Applies the transaction configuration only to the application specified.
type Required attribute. (Valid option is Url.)
extensionList A comma-separated list of file extensions. Either extensionList or regexMatch is required.
regexMatch A .NET Regular Expression to match against the full request URL, including the protocol. Either extensionList or regexMatch is required.
tracing Required attribute. (Valid options are Enabled, Disabled.)

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

See Disable tracing on transactions.

Inlining

Supported .NET Library versions

.NET Library

Config option

Inlining

Description

If a method is inlined by CLR, it cannot be instrumented. You can use this option to disable inlining for all applications. See the troubleshooting section Are custom instrumentation spans or other spans missing from traces? for more information.

Valid values

Disabled  
Enabled (Default)

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="Inlining" value="Disabled" />

SecurityTransparencyInstrumentation

Supported .NET Library versions

.NET Library (applicable only to .NET Framework)

Config option

SecurityTransparencyInstrumentation

Description

When an application is instrumented, this may infrequently cause a System.Security.VerificationException to occur and the message for the exception may be Operation could destabilize the runtime. One instance where the verification exception will occur is if the assembly being instrumented has the SecurityTransparent attribute. By default, the transparency checks are enabled and the System.Security.VerificationException may occur. This configuration setting can be used to disable the transparency checks and thus enable the instrumentation of SecurityTransparent assemblies.

Valid values

0 (Default) Disables instrumentation for security transparent assemblies. When this value is set, transparency checks are enabled.
2 Sets the COR_PRF_DISABLE_TRANSPARENCY_CHECKS_UNDER_FULL_TRUST compiler flag that disables transparency checks. When this value is set, System.Security.VerificationException does not occur even if both the SecurityTransparent attribute and SolarWinds Observability instrumentation are present.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="SecurityTransparencyInstrumentation" value="2" />

HttpClientInstrumentation

Supported .NET Library versions

.NET Library and .NET SDK

Config option

HttpClientInstrumentation

Description

Configuration is used to enable or disable HttpClient instrumentation.

Valid values

Disabled: HttpClient instrumentation is disabled for .NET Framework and .NET applications.

DisabledFramework: HttpClient instrumentation is disabled for .NET Framework applications (default value).

Enabled: HttpClient instrumentation is enabled for .NET Framework and .NET applications.

History

Introduced with version 5.3.3 of the .NET Instrumentation Library.

LogCreationSchedule

Supported .NET Library versions

.NET Library (applicable only to .NET Framework)

Config option

LogCreationSchedule

Description

Use this option to specify when the current log file ages out and a new log file is generated.

Valid values

  • Daily (Default)
  • Weekly

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LogCreationSchedule" value="Daily" />

LogFileMaxSize

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

LogFileMaxSize

Description

The maximum size, in bytes, that a log file can be. After the maximum is reached, no additional messages are written to it. Log messages are written again when a new log file is generated. The default is 10000000 (10 MB).

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LogFileMaxSize" value="10000000" />

LogLevel

Supported .NET Library versions

.NET Library and .NET SDK

Config option

LogLevel

Environment variable

SW_APM_LOG_LEVEL

Description

Use this option to specify the severity level of the events that are logged. Events of the specified level and all higher levels are logged. For example, Info (the default) logs events with severity levels of Info, Warning, Error, and Fatal.

Valid values

The following values are in descending order of severity:

Fatal Logs errors that caused .NET instrumentation to stop.
Error Logs errors that caused an instrumented trace to fail.
Warning Logs issues that might be problems (such as an unexpected configuration value) but do not prevent the .NET instrumentation from generating traces.
Info (Default) Logs information such as configuration settings that were loaded on startup.
Debug Logs diagnostic information used by Support to resolve technical issues.
Trace Logs information such as functions called and exception stack traces. This is the highest level of logging.
None Does not log any messages.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LogLevel" value="Info" />

Note

Levels Info and higher do not log messages per request when the .NET Library is running as expected.

LogFileLocation

Supported .NET Library versions

.NET Library and .NET SDK

Environment variable

SW_APM_LOG_FILE_LOCATION

Config option

LogFileLocation

Description

The directory where log files are created. The setting is applicable only when the LogType is 'File'. The specified directory is created if doesn't exist.

Default values

Windows: %TEMP%\Solarwinds (where %TEMP% is the environment variable TEMP)

Linux: /var/tmp/solarwinds

History

Introduced with version 5.3.3 of the .NET Instrumentation Library.

LogType

Supported .NET Library versions

.NET Library and .NET SDK

Environment variable

SW_APM_LOG_TYPE

Config option

LogType

Description

Destination for log messages.

Valid values

File Logs are outputted to files (default value).
StdOut Logs are outputted to stdout for Linux and Console for Windows.
StdErr Logs are outputted to stderr for Linux and Console for Windows.
Disabled Logging is disabled.

History

Introduced with version 5.3.3 of the .NET Instrumentation Library.

LogRetentionDays

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

LogRetentionDays

Description

This option specifies the number of days to retain log files. After this period, they are deleted. The default is 45 days.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LogRetentionDays" value="45" />

ReserveDiskSpace

Supported .NET Library versions

.NET Library (only applicable to .NET Framework)

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 are not written if there is insufficient disk space. The default is 200000000 (200 MB).

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="ReserveDiskSpace" value="200000000" />

IncludeQueryString

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

IncludeQueryString

Description

By default, the query string parameters are included in the URLs reported in IIS spans. Set the IncludeQueryString configuration to Disabled if query string parameters should be excluded from URLs reported in IIS spans.

Valid values

Disabled  
Enabled (Default)

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="IncludeQueryString" value="Enabled" />

PrependDomain

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

PrependDomain

Description

Optional configuration. Use this option to indicate whether the domain should be prepended to the transaction name.

Valid values

Disabled (Default)
Enabled  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="PrependDomain" value="Enabled" />

Profiling

Supported .NET Library versions

.NET Library (Windows only)

Config option

Profiling

Description

Optional configuration. Use this option to indicate whether profiling should be enabled.

Valid values

Disabled (Default)
Enabled  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="Profiling" value="Enabled" />

ProfileSampleInterval

Supported .NET Library versions

.NET Library (Windows only)

Config option

ProfileSampleInterval

Description

Optional configuration. This option specifies the sample interval for profile snapshots. The sample interval is in milliseconds.

Valid values

A valid value is an integer between 30 and 3000. The default is 50.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="ProfileSampleInterval" value="30" />

Backtraces

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

Backtraces

Description

Optional configuration. Use this option to explicitly control backtrace reporting.

Valid values

Disabled Disables backtrace reporting for all span events, including error span events.
ErrorsOnly Reports backtraces only for error span events. This is the recommended setting to increase library performance but still get useful details about application errors.
EnabledAll (Default) Enables backtrace reporting.
 

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="Backtraces" value="ErrorsOnly" />

applicationPool

Supported .NET Library versions

.NET Library (Windows only)

Config option

applicationPool

Description

Optional configuration. Use this option for application-pool-specific configuration.

Parameters

name The name of the application pool.
serviceName If you want the application pool to be identified as a different service, use a unique Service name.
apmAgent

Optional attribute. Valid options are:

  • Disabled
  • Enabled (Default)

To disable instrumentation for an application pool set the apmAgent attribute to Disabled.
iisInstrumentation

Optional attribute. Valid options are: 

  • DisabledIISFramework
  • DisabledIISCore
  • Enabled (Default)

To disable .NET Framework instrumentation set the iisInstrumentation attribute to DisabledIISFramework.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

See Configure the Service name in the config file.

iisSite

Supported .NET Library versions

.NET Library (Windows only)

Config option

iisSite

Description

Optional configuration. Use this option for IIS site-specific configuration.

Parameters

name The name of the IIS site. If a virtual directory needs to be identified as a different service, then the format for the name must combine the IIS site name and virtual directory name in this format: iis_site_name/virtual_directory_name.
serviceName To distinguish the IIS Site as a separate service from other sites within an application pool, specify a specific Service name with the serviceName parameter.
hostName Optional attribute. The host name can be specified if a service also needs to be separated by host names.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

See Configure the service name for an IIS site.

application

Supported .NET Library versions

.NET Library

Config option

application

Description

Optional configuration. Use this option to configure non-IIS applications.

Parameters

name The name of the application to instrument.
serviceName Optional attribute. If the application is a different service, then a specific Service name for this application can be specified.
inlining

Optional attribute. Valid options are:

  • Disabled
  • Enabled

If the inlining attribute is not set in the application element, the appSettingsInlining value is used.
apmAgent

Optional attribute. Valid options are:

  • Disabled
  • Enabled (Default)

To disable the .NET Library for an application set the apmAgent attribute to Disabled.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<application name="ApplicationToInstrument1.exe" serviceName="YourServiceName" />

InsertLogTraceIdIntoLogs

Supported .NET Library versions

.NET Library

Config option

InsertLogTraceIdIntoLogs

Description

Optional configuration. Use this option to indicate if the Trace ID should be automatically inserted into log files.

Valid values

Disabled (Default)
Enabled  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="InsertLogTraceIdIntoLogs" value="Enabled" />

AddAttributeLogTraceId

Supported .NET Library versions

.NET Library

Config option

AddAttributeLogTraceId

Description

Optional configuration. Use this option to indicate if the attribute Trace ID is created automatically.

Valid values

Disabled (Default)
Enabled  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="AddAttributeLogTraceId" value="Enabled" />

LoggedTraceId

Supported .NET Library versions

.NET Library

Config option

LoggedTraceId

Description

Optional configuration. Use this option to indicate if the Trace ID should be logged or created for all transactions or only for sampled transactions.

Valid values

All  (Default) Logs or creates the Trace ID for all transactions. 
SampledOnly  Logs or creates the Trace ID only for sampled transactions. 

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LoggedTraceId" value="All" />

TriggerTrace

Supported .NET Library versions

.NET Library

Config option

TriggerTrace

Description

Optional configuration. Use this option to enable trigger trace functionality.

Valid values

  • Disabled
  • Enabled (Default)

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="TriggerTrace" value="Enabled" />

ProxyUrl

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

ProxyUrl

Environment variable

SW_APM_PROXY

Description

Optional configuration. This option can be used to connect through a proxy. It can be set in the config file ProxyUrl element or through the environment variable SW_APM_PROXY. Note that while HTTP is the only type of connection supported between the library and proxy (hence only http:// is allowed in the schema of the config value), the library traffic to the SolarWinds APM collector is still encrypted using SSL/TLS.

Valid values

Proxy that requires Basic Authentication: http://<username>:<password>@<proxy-host>:<proxy-port>

Proxy that does not require authentication: http://<proxy-host>:<proxy-port>

SolarWinds recommends using the library-specific configuration. However, the library's underlying network library uses a system-wide proxy defined in the environment variables grpc_proxy, https_proxy or http_proxy if library-specific configuration is not set. Refer to gRPC environment variables for more information.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Examples

<add key="ProxyUrl" value="http://user:password@my-proxy:3128" />

<add key="ProxyUrl" value="http://my-proxy:3128" />

EventViewerLogLevel

Supported .NET Library versions

.NET Library (Windows only)

Config option

EventViewerLogLevel

Description

Use this option to specify the severity level of the events recorded by the SolarWinds Observability Profiler into the Application Event Log. Events of the specified level and all higher levels are logged. This information can be used to troubleshoot whether the library is being successfully loaded on application startup.

Valid values

The following values are in descending order of severity:

Fatal (Default) Logs errors that caused .NET instrumentation to stop.
Error Logs errors that caused an instrumented trace to fail.
Warning Logs issues that might be problems (such as an unexpected configuration value) but do not prevent the .NET instrumentation from generating traces.
Info Logs information such as configuration settings that were loaded on startup.
Debug Logs diagnostic information used by Support to resolve technical issues.
Trace Logs information such as functions called and exception stack traces. This is the highest level of logging.
None Does not log any messages.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="EventViewerLogLevel" value="Fatal" />

SolarWindsAPMHttpModule

Supported .NET Library versions

.NET Library (only applicable to .NET Framework)

Config option

SolarWindsAPMHttpModule

Description

Optional configuration. This option is used to indicate if the SolarWindsAPMHttpModule should be used to start and end traces. This setting is only applicable for application pools set to Integrated - Managed Pipeline Mode. The SolarWindsAPMHttpModule is always used for application pools set to Classic - Managed Pipeline Mode.

Valid values

Disabled (Default)
Enabled  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="SolarWindsAPMHttpModule" value="Enabled" />

MaximumQueryLength

Supported .NET Library versions

.NET Library

Config option

MaximumQueryLength

Description

Optional configuration. This option specifies the maximum length for the Query value reported in database spans.

Valid values

The configured length must be between 2048 and 128000.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="MaximumQueryLength" value="2048" />

IISInstrumentation

Supported .NET Library versions

.NET Library

Config option

IISInstrumentation

Description

Optional configuration. Use this option to indicate whether IIS Instrumentation should be enabled or disabled.

Valid values

Disabled Disables IIS Instrumentation for .NET Framework and .NET 6+.
DisabledIISFramework Disables IIS Instrumentation for .NET Framework
DisabledIISCore Disables IIS Instrumentation for .NET 6+
Enabled (Default) Enables IIS Instrumentation. The .NET Library installer sets this value based on the installation components selected.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="IISInstrumentation" value="Enabled" />

LogLevel.Instrumentation.ProfilerService

Supported .NET Library versions

.NET Library

Config option

LogLevel.Instrumentation.ProfilerService

Description

Use this option to specify the severity level of the events recorded by the profiling snapshot feature. Events of the specified level and all higher levels are logged.

Valid values

None  
Fatal  
Error  
Warning  
Info (Default)
Debug  
Trace  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LogLevel.Instrumentation.ProfilerService" value="Info" />

LogLevel.Instrumentation.Internal

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

LogLevel.Instrumentation.Internal

Description

Use this option to specify the severity level of the events recorded for the internal unmanaged library used by the .NET Library. Events of the specified level and all higher levels are logged.

Valid values

None  
Fatal  
Error  
Warning  
Info (Default)
Debug  
Trace  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LogLevel.Instrumentation.Internal" value="Info" />

LogLevel.Instrumentation.Internal.Collector

Supported .NET Library versions

.NET Library and .NET Core SDK

Config option

LogLevel.Instrumentation.Internal.Collector

Description

Use this option to specify the severity level of the events recorded for the communication between the .NET Library and the SolarWinds APM collector. Events of the specified level and all higher levels are logged.

Valid values

None  
Fatal  
Error  
Warning  
Info (Default)
Debug  
Trace  

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="LogLevel.Instrumentation.Internal.Collector" value="Info" />

MvcInstrumentation

Supported .NET Library versions

.NET Framework library

Config option

MvcInstrumentation

Description

Optional configuration. Use this option to indicate if MVC Instrumentation should be enabled, MVC View instrumentation only, or disabled.

Valid values

Disabled Disables MVC Instrumentation and MVC View Instrumentation.
MvcViewEnabled Enables only MVC View Instrumentation.
Enabled (Default) Enables MVC Instrumentation and MVC View Instrumentation.

History

Introduced with version 5.0.0 of the .NET Instrumentation Library.

Example

<add key="MvcInstrumentation" value="MvcViewEnabled" />

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.