External configuration rules

Prerequisites:

ConfigurableLog is essentially a CompositeLog with named components and rules for filtering and enrichment. Rules can be supplied from any external source and support reconfiguration without application restart.

Log configuration rules

Every rule contains some of the following:

Property

Type

Default value

Description

Enabled

bool

true

Enables/disables the logging in scope of the rule entirely.

Log

string

null

Limits the scope of the rule to the log with given name. If not specified, the rule applies to all logs.

Source

string

null

Limits the scope of the rule to events with source context having given prefix.

Operation

string

null

Limits the scope of the rule to events with operation context having given prefix.

MinimumLevel

LogLevel?

null

Sets the minimum log level for the events in scope of the rule.

Properties

Dictionary

null

Adds given set of properties to every event in scope of the rule.

There are also some important points to remember when defining rules:

  • You should never create two rules with identical scopes (Log + Source + Operation). Consider merging them instead.

  • Rules without Log scope are evaluated before any log-specific rules are considered.

  • When evaluating whether to log an event, the most specific of the matching rules gets to decide.

    • A rule with Source scope is more specific than a rule without any scope.

    • A rule with Operation scope is more specific than a rule without any scope.

    • A rule with Operation scope is more specific than a rule with Source scope.

    • A rule with Source + Operation scope is the most specific one possible.

  • Additional properties are added from all matching rules.

Create a ConfigurableLog

var rules = new[]
{
new LogConfigurationRule { Log = "c1", Source = "noisy", MinimumLevel = LogLevel.Warn},
new LogConfigurationRule { Log = "c2", Enabled = false },
new LogConfigurationRule { Log = "c3", Properties = new Dictionary<string, string> { ["key"] = "value" } }
};
var log = new ConfigurableLogBuilder()
.AddLog("c1", new SynchronousConsoleLog())
.AddLog("c2", new SynchronousConsoleLog())
.AddLog("c3", new SynchronousConsoleLog())
.SetRules(rules)
.Build();

Rules can also be supplied with an IObservable<LogConfigurationRule[]>. Here's an equivalent of the configuration above using Vostok.Configuration library and storing rules in JSON file:

var source = new JsonFileSource("log-rules.json");
var rulesObservable = ConfigurationProvider.Default.Observe<LogConfigurationRule[]>(source);
var log = new ConfigurableLogBuilder()
.AddLog("c1", new SynchronousConsoleLog())
.AddLog("c2", new SynchronousConsoleLog())
.AddLog("c3", new SynchronousConsoleLog())
.SetRules(rulesObservable)
.Build();
[
{ "Log": "c1", "Source": "noisy", "MinimumLevel": "Warn" },
{ "Log": "c2", "Enabled": "false" },
{ "Log": "c3", "Properties": { "key": "value" } }
]