You can get started logging with log4net with minimal changes to your project. You essentially just add a few DLLs to your project and then add some configuration details to your .config file specifying an additional (or replacement) log appender. The appender is available via Nuget in Visual Studio and additional documentation can be found on our Github page.
Getting Started Using NuGet
If you're using NuGet from Visual Studio, you can find and integrate the Stackify log4net libraries and configurations quickly and easily. Just search for Stackify and then install the Stackify Log4Net Appender. The NuGet package entitled "Stackify Log4Net Appender" depends on version 2.0.0 of Log4Net. If using version, use the "Stackify Log4Net v1.2.10 Appender" NuGet package. Newer versions of Log4Net will work with a valid assembly binding redirect. Check out our Github page on details to configure this.
You can also enter the following command in the Nuget Package Manager Console to install the appender:
PM> Install-Package StackifyLib.log4net
A Note About Error Results on Unmonitored Servers
If you are logging errors from a server that doesn't have a Stackify monitoring agent on it, you have to add an Environment key to the appSettings section of your configuration, as it cannot be inferred by Stackify without an agent running on the machine.
It should also be noted that if you are logging errors for your application and that application doesn't appear as an app in the App Stacks page, the only way to see error telemetry is from the global Error Dashboard page, as there will be no App Dashboard for that application if it's not installed on a server that is being monitored.
Below is the required configuration entry if logging from an unmonitored server:
<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>
Advanced Features: GDC, MDC, and NDC
The GDC (Global Diagnostic Context) is a map of name-value pairs that give additional information to the context of the logging event. The GDC is global for all logging events (not thread-scoped). We don't have access to the entire name-value pair map, but we can access a value given its name. This requires additional configuration in the log4net appender. Each GDC field specified (with a non-null value) will be added to the custom properties for the log event.
The MDC (Mapped Diagnostic Context) is a map of name-value pairs that give additional information to the context of the logging event. The MDC is thread-scoped. We don't have access to the entire name-value pair map, but we can access a value given its name. This requires additional configuration in the log4net appender. Each MDC field specified (with a non-null value) will be added to the custom properties for the log event.
The NDC (Nested Diagnostic Context) is a stack of string values that give additional information to the context of the logging event. If the NDC is set, we will get a copy of the top value and add it to the custom properties for the log event. The property will be named "NDC". No extra configuration is required to use this feature.
<appender name="StackifyAppender" type="StackifyLib.log4net.ExceptionAppender, StackifyLib.log4net"> ... <gdcKeys value="GDC_Key1, GDC_Key2" /> <mdcKeys value="MDC_Key1, MDC_Key2" /> </appender>
If you're logging details in this manner, you can see those custom properties in the Custom Properties section of the Error Details page in Stackify.
Configuring for Exception Logging
By default, the Stackify appender will capture all Exception log statements and display them in the Stackify Portal. Below will show you how to extend the appender to other log levels to be displayed in Stackify.
Configuring Logging for Other Log Statements
When installing the Stackify log4net appender, by default it is set up to only do exception level logging. Changing the configurations will allow you to send all log statements to Stackify and take full advantage of Log Aggregation. To configure the Stackify log4net appender, you simply edit a few lines in the Web.config file:
1. Comment out the appender section shown above so that the ExceptionAppender is no longer utilized.
2. Uncomment the commented out StackifyAppender appender section. (This appender will send all DEBUG, INFO, WARN, ERROR, and FATAL level logging messages to the Log Management Dashboard, depending on your chosen logging level.)
Note: The level value in the Web.config can be changed to the minimum log level you wish to send to Stackify in the Logging Dashboard. For example, if you do not want to see DEBUG or INFO statements, you would set the level value to "WARN".
Logging Through Stackify at a Different Logging Level
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.
<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 --> <!-- http://logging.apache.org/log4net/release/manual/configuration.html --> <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>