Rock Logging Engine

Rock Logging Engine

Starting with Rock v17, there is a new logging engine in Rock. Logging is an important part of writing a quality application. It can communicate issues to the administrator, help troubleshoot customer issues, and if not used correctly could bring the system to its knees. The current logging implementation takes ~8 microseconds to write something to the log file. This sounds fast, but if done inside a loop these times could add up fast.

Rock uses the Microsoft.Extensions.Logging library and pattern for logging. But since we don't have full Dependency Injection, there are two steps to performing logging.

First, create the logger with a call like:

var logger = RockLogger.LoggerFactory.CreateLogger<YourClassName>();

You can then use the logger by issuing a call such as this:

logger.LogWarning( "your text");

There are 6 verbosity levels you can log for (Critical, Error, Warning, Information, Debug, Trace). The majority of your logging should take place at the Verbosity Level of Debug and Information, because these levels will be actually written the least and have a smaller chance of unintentionally hurting performance.

Logging is also enabled or disabled based on category. The category is always the full class name of your class, such as Rock.Jobs.RockCleanup. Only categories (classes) that are marked with the C# attribute Rock.Logging.RockLoggingCategoryAttribute will show up in the list. You'll want to add this C# attribute on any class that you add logs to.

[RockLoggingCategory]
public class RockCleanup : RockJob

If you want to add a specific project namespace as a category, you can add this to your project's AssemblyInfo.cs.

// Register friendly logging category names.
[assembly: Rock.Logging.RockLoggingCategory( "com.RockSolidChurch.MyProject" )]

But don't worry, even if you don't mark it you can still log to it and add your category under the Advanced section. The attribute just controls if it will show up in the Categories to Log drop down list. So you should only decorate classes that you expect will be high-profile logging. If it's just something you want to be able to enable while developing, consider not decorating it and manually entering it in the Advanced section.

For log entries to be written, the logger must first be enabled under Admin Tools > System Settings > Rock Logs as seen here:

Once enabled, the logs will appear on that same page.

Advanced Configuration

If you need to enable logging for a category not marked with the RockLoggingCategoryAttribute then it can be enabled in the Advanced section. For example, if you want to enable the legacy "CMS" logging domain at the "Information" (and above) level as well as the plugin category "com.rocksolidchurch.MyLogicController" at the "Error" (and above) level, you could enter the following in the Custom Settings text box.

{
    "LogLevel": {
        "CMS": "Information",
        "com.rocksolidchurch.MyLogicController": "Error"
    }
}