Logger Plugin

This unofficial TaleSpire plugin for adding unified logging to other plugins.

This plugin, like all others, is free but if you want to donate, use: http://LordAshes.ca/TalespireDonate/Donate.php

Change Log

1.0.1: Updated documentation. No plugin change.
1.0.0: Initial release

Install

Install using R2ModMan or similar.

Usage

The use of this plugin is passive. It is a dependency plugin which allows other plugins to perform logging functionality in a consistent manner.

User Configuration

The plugin has two options in terms of plugin logging levels. Many plugins have a configuration for the logging level in which case it can be convenient to be able to configure the logging level from the plugin's configuration whereas in other cases it can be convenient to be able to set the logging levels for all plugins in a single unified source such as the logger configuration. To address This the logger configuration has the following setting:

Allow Plugins Logging Level (Default true)

When this setting is set to true, the logging levels configured in the logger configuration are used as the starting logging level but plugins can change the logging level at runtime. This allows The plugins to set the logging level based on their own configuration. Any plugin that does not set its logging level will end up using the value configured in the logger.

When this settings is set to false, all request by plugins to change their logging levels will be ignored and the configured logging level in the logger configuration will be used instead.

Plugin Logging Level (Default \*:info)

The logger configuration can configure different logging levels for each plugin. This setting is a comma delimited list of plugins with their desired logging level. The plugin name (as it appears in the log) is seperated from the logging level by a colon. The \* entry should always be present and it represents the logging level for all plugins that have not been listed. For example, "AssetDataPlugin:debug,*:info" would set the logging level for the Asset Data Plugin to debug while setting the logging level for all other plugins to info.

Logger Own Logging Level (Default error)

This setting determins the logger plugin's own logging level. It is separated from the plugin list since these log messages are not generated by others but are instead geenrated by the logger itself. Typically this logging level should not need to be set high unless a problem with the logger itself is suspected.

Log Entry Format (Default {TIMESTAMP} - {LEVEL} - {NAME} - {CONTENT})

This setting determines the content of the log. The setting can make use of a number of place holders to automatically insert various information into the log along with the log message. The following place holders are supported:

{NAME!} = Name of the logging plugin
{NAME} = Name of the logging plugin padded to the specified length (see below)
{LEVEL!} = Severity of the message (e.g. error, warning, info, debug, trace)
{LEVEL} = Severity of the message padded to the longest entry (i.e. warning)
{LEVEL#} = Severity of the message expressed as a numeric value
{TIMESTAMP} = Date and time that the message was logged
{DATE} = Date in YYYY.MM.DD format when the message was logged
{TIME} = Time in HH:MM:DD.SSS format when the message was logged
{CONTENT} = The message to be logged

Length Of Plugin Name (Default 20)

This setting indicated the length to which the plugin name is padded when using {NAME}. Unlike the the severity levels which are an enumeration and thus the longest possible entry can be determined so that all entries can be padded to that length, the plugin name is not predictable since a new plugin can be added at any time with a longer name. As such the padding for the plugin name is set using this setting.

Plugin Creators

The Logging Plugin is intended to be as simple as possible. In its simplest use case, you can use it without any initialization. To use it, like any other library, you need to add a project reference to the Logging Plugin and then add a BepInEx dependency such as:

[BepInDependency(LordAshes.LoggingPlugin.Guid, BepInDependency.DependencyFlags.HardDependency)]
public partial class HideBasePlugin : BaseUnityPlugin
{
  ...
}

However, to simplify the logging calls (so that they don't need to prefixed with the Logging Plugin name) you can add the following using statement at the beginning of the code:

using static LordAshes.LoggingPlugin;

With that done, logging can be done using the log methods for each severity. Such as:

LogError("My Error Message")
LogWarning("My Warning Message")
LogInfo("My Info Message")
LogDebug("My Debug Message")
LogTrace("My Trace Message")

All logs, in the above order, that are of equal or lower to the log level will be logged. For example, if the log level is set to info then logs with a severity level of error, warning and info would be logged but logs with a severity of debug or trace would be ignored.

Plugin Set Log level

Many plugin have a configuration for the log level associated with the plugin. This log level can easily be passed to the Logging Plugin using a simple one line method call, such as:

SetLogLevel(pluginLogLevel)

This is usually linked to the plugin configuration using something like:

SetLogLevel(Config.Bind("Settings", "Log Level", DiagnosticLevel.error).Value);

This will set the logging level for the particular plugin (not all plugins) if the Logging Plugin configuration allow it. The configuration of the Logging Plugin can disallow this operation forcing the logging levels to be configured on the Logging Plugin configuration only. See the setting called "Allow Plugins Logging Level" above for explanation.

Monitoring Plugins

The Logging Plugin supports a Subscribe method. This method is used to trigger a callback when a log message for a particular plugin (source) comes in and the log severity meets the subscribed severity criteria (equal to or lower). This allows building monitoring plugins which process specific log messages to provide some additional functionality. The subscribe method allows only the specification of one plugin (source) - with no wild card support - but the method can be called multiple times to Subscribe to multiple sources.

Subscribe(MonitoringCallback, DiagnosticLevel.error, "AssetDataPlugin");

void MonitoringCallback(string pluginName, DiagnosticLevel logSeverity, string logContent)
{
  ...
}