What Logging API to Use?

We recommend you write your application against the classes provided by Microsoft.Extensions.Logging.  This is used throughout .NET and has extensive features.  Integrating with it lets your log data be sent to Loupe, other log destinations, and be merged together with data emitted by .NET itself and other third party libraries.

For more information, see Developer's Reference - Microsoft.Extensions.Logging Introduction.

Useful Information to Log

1. Application Session start/stop. We recommend including a log statement as early and as late as possible in your application session.  Also, if your program has complex setup or teardown logic, include additional messages at the start and end of these sections.
2. User Session start/stop. For many applications such as services and web apps, there may be many user sessions within a single application session.  Log distinctive messages at the start and end of each of these logical sessions.
3. Unhandled Exceptions. Loupe will log unhandled exceptions by default.  But, if you write your own exception handler, be sure to log each exception to Loupe.
4. Handled Exceptions.  We strongly recommend that in all cases where an exception is consumed within a catch block that you log the exception with an Informational severity rather than silently swallowing the error.
5. Significant User Actions. We recommend that you log every significant action taken by the user and that you use a specific category for these log messages. This makes it easy to reconstruct reproduction steps for defect reports.  Some examples of this include:
   1. Windows/forms/dialogs opening and closing.
   2. Changing tabs
   3. Change of focus between major controls (not between minor fields)
   4. Button clicks.
      
      We do not recommend logging high-frequency user interactions such as MouseMove. Use MouseDown, MouseUp or MouseClick instead.
6. Help requests.  From a usability perspective, every request for help is a hint that something could be made clearer in the user interface.
7. Cancelled Actions.  When a user begins an action then abandons it without completing, it may also point to usability issues.
8. Log Thread start/stop.  If your application creates background threads, consider creating a helper class to create threads that will automatically log thread start/stop.
9. Asynchronous request start/stop.  We recommend logging the start and stop of most asynchronous requests – possibly excluding high frequency activities such as loading the individual elements of a web page.

What Not to Log

1. Avoid excessive logging.  While judicious logging can be extremely helpful, do not blindly log every method entry/exit.  Apply judgment and include logging only where it provides useful information to help you understand application flow.
2. Avoid logging in tight loops that will be executed many times a second.  While Loupe can easily sustain logging rates of over 1000 messages a second, such long logs are unwieldy. You can get a very good sense of what an application is doing with relatively few well-placed log messages.  You and your support staff will be thankful later.
3. Think carefully about sensitive information. Be sensitive to privacy and intellectual property considerations when adding log messages to your application.  For example, passwords and sensitive information such as social-security numbers should never be logged.

Tips & Tricks

1. Use the same default logging in Debug and Release builds.  If logging is used judiciously (following the guidelines above) there is no need to disable logging for release builds which reduces the risk of different behaviors in release builds.  If some logging is selectively disabled, have it disabled by default in both Debug and Release builds.
2. Avoid side-effects.  Be careful not to pass arguments to log statements whose evaluation will change object state.
3. Consider using a custom Event Metric for usability events such as Help Requests and Cancelled Actions.
4. Consider using a custom Event Metric for tracking request durations.  Long requests such as database transactions or cross-process network calls are notorious for being performance hot spots.  By recording the duration of these calls in a custom metric, you make it easy to identify and troubleshoot hot spots when they arise.
5. Differentiate Caption/Description. Loupe treats the first line of a multi-line message as its caption and the remaining lines as a description.  You can use this to your advantage.  For example, if you have a variety of messages that share the same caption with differing details, the Loupe Session Viewer will let you group these messages together.