How to Configure log4net

You can easily send your application logs to Retrace if you are using log4net.

1. Add our nuget package
2. Add our logging appender to your log4net configuration
3. Specify your Stackify license key in your configuration

The code for Stackify's .NET library and logging appenders are all available on Github.

Getting Started Using NuGet

The Stackify logging appender is designed to be used with log4net v2.0.0 and newer. We have a different nuget package for older versions.

Install our nuget package:

PM> Install-Package StackifyLib.log4net

Add the Stackify ApiKey to your Config

In order for the NuGet installation to complete, copy your Stackify Activation Key (license key) from your Stackify account page and paste it here.

Please note that this example is for a .NET Framework config file. If you are using .NET Core, the configuration would be done in the same manner in json.

<appSettings>
    <add key="Stackify.ApiKey" value="Your Activation Key" />
    <add key="Stackify.AppName" value="Your App Name"/> <!-- optional - will be inferred by Stackify if this is running on a monitored server -->
    <add key="Stackify.Environment" value="Your Environment"/> <!-- optional - will be inferred by Stackify if this is running on a monitored server -->
</appSettings>

The AppName and Environment are not required but are recommended if you are logging from a server without Retrace installed.

Once this is complete, you are done with the installation and configuration of the Stackify log4net appender.

Basic Appender Configuration

Below is the simplest log4net configuration needed to log to Retrace.

<log4net>
    <root>
        <level value="DEBUG" />
        <appender-ref ref="StackifyAppender" />
    </root>
    <appender name="StackifyAppender" type="StackifyLib.log4net.StackifyAppender, StackifyLib.log4net" />
</log4net>

Assembly Binding Redirects

The binding redirect that you need may vary. Here is an example of one.

 <dependentAssembly>
    <assemblyIdentity name="log4net" publicKeyToken="669e0ddf0bb1aa2a" culture="neutral" />
    <bindingRedirect oldVersion="2.0.3.0-2.0.8.0" newVersion="2.0.8.0" />
  </dependentAssembly>

Logging Custom Properties

Retrace supports logging custom fields, which is sometimes called structured logging. This is really powerful for logging things like a customer number with each logging statement.

We have provided some handy extension methods to make it easy to log custom properties.

using StackifyLib; //extension methods are here

//create your logger
static log4net.ILog logger = log4net.LogManager.GetLogger(typeof(Program));

logger.Debug("Some cool logging message", new { clientid = 54732}); //extension method

//You can also log an object like a dictionary
Dictionary<string, object> dictionary = new Dictionary<string, object>();
dictionary["clientid"] = 54732;

logger.Debug("Another cool logging message", dictionary); //extension method

Control which logs are sent to Stackify

With log4net you can easily specify if you want to log DEBUG, INFO, FATAL, or etc logs. You should consider what logging level you want to send to Stackify. It may make sense to ignore debug level logging.

If you have other appenders in addition to Stackify that you want to continue logging to, but you want to log at different levels to each appender, you can easily alter your logging level for Stackify by utilizing the LevelRangeFilter inside of your appender configuration section for StackifyAppender. Also see the Apache log4net configuration document for more information.

<log4net>
    <root>
        <level value="INFO" />
        <appender-ref ref="StackifyAppender" />
        <appender-ref ref="Console" />
    </root>
    <appender name="StackifyAppender" type="StackifyLib.log4net.StackifyAppender, StackifyLib.log4net">
<!-- Log DEBUG through FATAL just in Stackify by using filters and setting levelMin and levelMax appropriately -->
        <filter type="log4net.Filter.LevelRangeFilter">
            <levelMin value="DEBUG" />
            <levelMax value="FATAL" />
        </filter>
    </appender>
    <appender name="Console" type="log4net.Appender.ConsoleAppender">
        <layout type="log4net.Layout.PatternLayout">
            <conversionPattern value="%date %-5level: %message%newline" />
        </layout>
    </appender>
</log4net>

Recording Context Values

If you are using logical or thread context keys within log4net and would like to collect and send those to Retrace, you can. We support 4 different types of context keys that can be specified in the appender configuration. You can review our code to get a better of how it works.

Review the log4net documentation to learn more about using contexts.

We suggest using the LogicalThreadContext. You would want to set that somewhere when the ASP.NET request first starts like so:

log4net.LogicalThreadContext.Properties["key1"] = "abc123";

The values that we capture will show up as custom json properties with the logging message.

<appender name="StackifyAppender" type="StackifyLib.log4net.ExceptionAppender, StackifyLib.log4net">
    ...
    <globalContextKeys value="key1,key2" />
    <threadContextKeys value="key1,key2" />
    <logicalThreadContextKeys value="key1,key2" />
    <callContextKeys value="key1,key2" />
</appender>

How to use Log4net v1.2.10

If using log4net version 1.2.10, use the "Stackify Log4Net v1.2.10 Appender" NuGet package. This package works only with log4net 1.2.10 as there is a breaking change to the API in 1.2.11 and the strong name token was changed in later releases.

View your logs with Prefix

You can use Prefix to view your logs on your workstation. It requires adding the log4net appender to pick up and show your logs within Prefix. You do not need to configure a Stackify ApiKey for Prefix to work properly.