Scripting Example - Logging¶

This article reviews Logging, which will be available in Vinyl 3.2. This feature leverages Microsoft's Logging API. Logging helps debugging and maintaining a plugin, giving insight on current values, expected and unexpected behaviors. The example in this article demonstrates how to log messages.

Log Severity¶

A message will only be logged if the Severity level is equal to or higher than the value configured on Minimum Severity under App Server Log Configuration for each log target configuration (Memory, Database, and Disk).

Severity Levels¶

Microsoft Severity	Vinyl Severity	Description
`Off`	`Off`	Configuration status where target log won't write any message, not intended for usage when logging.
`Trace`	`Trace`	Detailed message of minute steps, this status should be avoided in production enviroments.
`Debug`	`Debug`	Used during development to investigate state and behavior.
`Information`	`Info`	Used to track expected behavior, for example successfully processing a file.
`Warning`	`Warn`	Used when a behavior or state is not detrimental yet, but should be noted, for example disk running out of space.
`Error`	`Error`	Used when the current process has to stop due to a failure, for example unexpected data value from a file.
`Critical`	`Fatal`	Used when a failure requires immediate attention.

App Server Configuration screen, illustrating the Info Severity set for Memory Log Configuration

Script¶

using Microsoft.Extensions.Logging;

var logger = Services.GetRequiredService<ILogger>();

logger.LogWarning("My warning message");

Scope¶

Scoping is supported and allows additional information to be appended to the log record.

using Microsoft.Extensions.Logging;
using System.Collections.Generic;

var logger = Services.GetRequiredService<ILogger>();

logger.LogError("My unscoped error message");

// Appends "MyScope" to the log source
using (logger.BeginScope("MyScope")) {

    logger.LogWarning("My scoped warning");

    // Tags log records with the extra identifing properties.
    using (logger.BeginScope(new Dictionary<string, object>{
        ["CustomerId"] = 123,
        ["OrderId"] = 12
    })) {

        logger.LogWarning("My warning with extra data");

    }
}

Memory Logs example output with Scoping configured

Note

Any property added by the scope will be secured, meaning that to be recorded and displayed Log Secure Data has to be ON.

More Information¶

You can find more about Microsoft's Logger API as well as its extension methods on Microsoft's .NET API Browser.