Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/serilog/serilog-settings-configuration
A Serilog configuration provider that reads from Microsoft.Extensions.Configuration
https://github.com/serilog/serilog-settings-configuration
Last synced: 7 days ago
JSON representation
A Serilog configuration provider that reads from Microsoft.Extensions.Configuration
- Host: GitHub
- URL: https://github.com/serilog/serilog-settings-configuration
- Owner: serilog
- License: apache-2.0
- Created: 2015-06-12T07:12:16.000Z (over 9 years ago)
- Default Branch: dev
- Last Pushed: 2024-11-23T21:01:32.000Z (19 days ago)
- Last Synced: 2024-11-28T19:18:56.173Z (14 days ago)
- Language: C#
- Homepage:
- Size: 1.08 MB
- Stars: 458
- Watchers: 24
- Forks: 130
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
Awesome Lists containing this project
- awesome-dotnet-core - Serilog.Settings.Configuration - A Serilog configuration provider that reads from Microsoft.Extensions.Configuration. (Frameworks, Libraries and Tools / Logging)
- awesome-dotnet-core - Serilog.Settings.Configuration - Serilog设置库。 (框架, 库和工具 / 日志)
- fucking-awesome-dotnet-core - Serilog.Settings.Configuration - A Serilog configuration provider that reads from Microsoft.Extensions.Configuration. (Frameworks, Libraries and Tools / Logging)
- awesome-dotnet-core - Serilog.Settings.Configuration - A Serilog configuration provider that reads from Microsoft.Extensions.Configuration. (Frameworks, Libraries and Tools / Logging)
README
# Serilog.Settings.Configuration [](https://github.com/serilog/serilog-settings-configuration/actions) [](https://www.nuget.org/packages/Serilog.Settings.Configuration/)
A Serilog settings provider that reads from [Microsoft.Extensions.Configuration](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1) sources, including .NET Core's `appsettings.json` file.
By default, configuration is read from the `Serilog` section that should be at the **top level** of the configuration file.
```json
{
"Serilog": {
"Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
"MinimumLevel": "Debug",
"WriteTo": [
{ "Name": "Console" },
{ "Name": "File", "Args": { "path": "Logs/log.txt" } }
],
"Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
"Destructure": [
{ "Name": "With", "Args": { "policy": "Sample.CustomPolicy, Sample" } },
{ "Name": "ToMaximumDepth", "Args": { "maximumDestructuringDepth": 4 } },
{ "Name": "ToMaximumStringLength", "Args": { "maximumStringLength": 100 } },
{ "Name": "ToMaximumCollectionCount", "Args": { "maximumCollectionCount": 10 } }
],
"Properties": {
"Application": "Sample"
}
}
}
```
After installing this package, use `ReadFrom.Configuration()` and pass an `IConfiguration` object.
```csharp
static void Main(string[] args)
{
var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json")
.AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production"}.json", true)
.Build();
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(configuration)
.CreateLogger();
logger.Information("Hello, world!");
}
```
This example relies on the _[Microsoft.Extensions.Configuration.Json](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Json/)_, _[Serilog.Sinks.Console](https://github.com/serilog/serilog-sinks-console)_, _[Serilog.Sinks.File](https://github.com/serilog/serilog-sinks-file)_, _[Serilog.Enrichers.Environment](https://github.com/serilog/serilog-enrichers-environment)_ and _[Serilog.Enrichers.Thread](https://github.com/serilog/serilog-enrichers-thread)_ packages also being installed.
For a more sophisticated example go to the [sample](sample/Sample) folder.
## Syntax description
### Root section name
Root section name can be changed:
```yaml
{
"CustomSection": {
...
}
}
```
```csharp
var options = new ConfigurationReaderOptions { SectionName = "CustomSection" };
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(configuration, options)
.CreateLogger();
```
### Using section and auto-discovery of configuration assemblies
`Using` section contains list of **assemblies** in which configuration methods (`WriteTo.File()`, `Enrich.WithThreadId()`) reside.
```yaml
"Serilog": {
"Using": [ "Serilog.Sinks.Console", "Serilog.Enrichers.Thread", /* ... */ ],
// ...
}
```
For .NET Core projects build tools produce `.deps.json` files and this package implements a convention using `Microsoft.Extensions.DependencyModel` to find any package among dependencies with `Serilog` anywhere in the name and pulls configuration methods from it, so the `Using` section in example above can be omitted:
```yaml
{
"Serilog": {
"MinimumLevel": "Debug",
"WriteTo": [ "Console" ],
...
}
}
```
In order to utilize this convention for .NET Framework projects which are built with .NET Core CLI tools specify `PreserveCompilationContext` to `true` in the csproj properties:
```xml
true
```
In case of [non-standard](#azure-functions-v2-v3) dependency management you can pass a custom `DependencyContext` object:
```csharp
var functionDependencyContext = DependencyContext.Load(typeof(Startup).Assembly);
var options = new ConfigurationReaderOptions(functionDependencyContext) { SectionName = "AzureFunctionsJobHost:Serilog" };
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(hostConfig, options)
.CreateLogger();
```
Alternatively, you can also pass an array of configuration assemblies:
```csharp
var configurationAssemblies = new[]
{
typeof(ConsoleLoggerConfigurationExtensions).Assembly,
typeof(FileLoggerConfigurationExtensions).Assembly,
};
var options = new ConfigurationReaderOptions(configurationAssemblies);
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(configuration, options)
.CreateLogger();
```
For legacy .NET Framework projects it also scans default probing path(s).
For all other cases, as well as in the case of non-conventional configuration assembly names **DO** use [Using](#using-section-and-auto-discovery-of-configuration-assemblies) section.
#### .NET 5.0 onwards Single File Applications
Currently, auto-discovery of configuration assemblies is not supported in bundled mode. **DO** use [Using](#using-section-and-auto-discovery-of-configuration-assemblies) section or explicitly pass a collection of configuration assemblies for workaround.
### MinimumLevel, LevelSwitches, overrides and dynamic reload
The `MinimumLevel` configuration property can be set to a single value as in the sample above, or, levels can be overridden per logging source.
This is useful in ASP.NET Core applications, which will often specify minimum level as:
```json
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"System": "Warning"
}
}
```
`MinimumLevel` section also respects dynamic reload if the underlying provider supports it.
```csharp
var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile(path: "appsettings.json", reloadOnChange: true)
.Build();
```
Any changes for `Default`, `Microsoft`, `System` sources will be applied at runtime.
(Note: only existing sources are respected for a dynamic update. Inserting new records in `Override` section is **not** supported.)
You can also declare `LoggingLevelSwitch`-es in custom section and reference them for sink parameters:
```json
{
"Serilog": {
"LevelSwitches": { "controlSwitch": "Verbose" },
"WriteTo": [
{
"Name": "Seq",
"Args": {
"serverUrl": "http://localhost:5341",
"apiKey": "yeEZyL3SMcxEKUijBjN",
"controlLevelSwitch": "$controlSwitch"
}
}
]
}
}
```
Level updates to switches are also respected for a dynamic update.
Since version 7.0.0, both declared switches (i.e. `Serilog:LevelSwitches` section) and minimum level override switches (i.e. `Serilog:MinimumLevel:Override` section) are exposed through a callback on the reader options so that a reference can be kept:
```csharp
var allSwitches = new Dictionary();
var options = new ConfigurationReaderOptions
{
OnLevelSwitchCreated = (switchName, levelSwitch) => allSwitches[switchName] = levelSwitch
};
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(configuration, options)
.CreateLogger();
LoggingLevelSwitch controlSwitch = allSwitches["$controlSwitch"];
```
### WriteTo, Enrich, AuditTo, Destructure sections
These sections support simplified syntax, for example the following is valid if no arguments are needed by the sinks:
```json
"WriteTo": [ "Console", "DiagnosticTrace" ]
```
Or alternatively, the long-form (`"Name":` ...) syntax from the example above can be used when arguments need to be supplied.
By `Microsoft.Extensions.Configuration.Json` convention, array syntax implicitly defines index for each element in order to make unique paths for configuration keys. So the example above is equivalent to:
```yaml
"WriteTo": {
"0": "Console",
"1": "DiagnosticTrace"
}
```
And
```yaml
"WriteTo:0": "Console",
"WriteTo:1": "DiagnosticTrace"
```
(The result paths for the keys will be the same, i.e. `Serilog:WriteTo:0` and `Serilog:WriteTo:1`)
When overriding settings with [environment variables](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1#environment-variables) it becomes less convenient and fragile, so you can specify custom names:
```yaml
"WriteTo": {
"ConsoleSink": "Console",
"DiagnosticTraceSink": { "Name": "DiagnosticTrace" }
}
```
### Properties section
This section defines a static list of key-value pairs that will enrich log events.
### Filter section
This section defines filters that will be applied to log events. It is especially useful in combination with _[Serilog.Expressions](https://github.com/serilog/serilog-expressions)_ (or legacy _[Serilog.Filters.Expressions](https://github.com/serilog/serilog-filters-expressions)_) package so you can write expression in text form:
```yaml
"Filter": [{
"Name": "ByIncludingOnly",
"Args": {
"expression": "Application = 'Sample'"
}
}]
```
Using this package you can also declare `LoggingFilterSwitch`-es in custom section and reference them for filter parameters:
```yaml
{
"Serilog": {
"FilterSwitches": { "filterSwitch": "Application = 'Sample'" },
"Filter": [
{
"Name": "ControlledBy",
"Args": {
"switch": "$filterSwitch"
}
}
]
}
```
Level updates to switches are also respected for a dynamic update.
Since version 7.0.0, filter switches are exposed through a callback on the reader options so that a reference can be kept:
```csharp
var filterSwitches = new Dictionary();
var options = new ConfigurationReaderOptions
{
OnFilterSwitchCreated = (switchName, filterSwitch) => filterSwitches[switchName] = filterSwitch
};
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(configuration, options)
.CreateLogger();
ILoggingFilterSwitch filterSwitch = filterSwitches["filterSwitch"];
```
### Nested configuration sections
Some Serilog packages require a reference to a logger configuration object. The sample program in this project illustrates this with the following entry configuring the _[Serilog.Sinks.Async](https://github.com/serilog/serilog-sinks-async)_ package to wrap the _[Serilog.Sinks.File](https://github.com/serilog/serilog-sinks-file)_ package. The `configure` parameter references the File sink configuration:
```yaml
"WriteTo:Async": {
"Name": "Async",
"Args": {
"configure": [
{
"Name": "File",
"Args": {
"path": "%TEMP%/Logs/serilog-configuration-sample.txt",
"outputTemplate":
"{Timestamp:o} [{Level:u3}] ({Application}/{MachineName}/{ThreadId}) {Message}{NewLine}{Exception}"
}
}
]
}
},
```
### Destructuring
Destructuring means extracting pieces of information from an object and create properties with values; Serilog offers the `@` [structure-capturing operator](https://github.com/serilog/serilog/wiki/Structured-Data#preserving-object-structure). In case there is a need to customize the way log events are serialized (e.g., hide property values or replace them with something else), one can define several destructuring policies, like this:
```yaml
"Destructure": [
{
"Name": "With",
"Args": {
"policy": "MyFirstNamespace.FirstDestructuringPolicy, MyFirstAssembly"
}
},
{
"Name": "With",
"Args": {
"policy": "MySecondNamespace.SecondDestructuringPolicy, MySecondAssembly"
}
},
{
"Name": "With",
"Args": {
"policy": "MyThirdNamespace.ThirdDestructuringPolicy, MyThirdAssembly"
}
},
],
```
This is how the first destructuring policy would look like:
```csharp
namespace MyFirstNamespace;
public record MyDto(int Id, int Name);
public class FirstDestructuringPolicy : IDestructuringPolicy
{
public bool TryDestructure(object value, ILogEventPropertyValueFactory propertyValueFactory,
[NotNullWhen(true)] out LogEventPropertyValue? result)
{
if (value is not MyDto dto)
{
result = null;
return false;
}
result = new StructureValue(new List
{
new LogEventProperty("Identifier", new ScalarValue(deleteTodoItemInfo.Id)),
new LogEventProperty("NormalizedName", new ScalarValue(dto.Name.ToUpperInvariant()))
});
return true;
}
}
```
Assuming Serilog needs to destructure an argument of type **MyDto** when handling a log event:
```csharp
logger.Information("About to process input: {@MyDto} ...", myDto);
```
it will apply **FirstDestructuringPolicy** which will convert **MyDto** instance to a **StructureValue** instance; a Serilog console sink would write the following entry:
```text
About to process input: {"Identifier": 191, "NormalizedName": "SOME_UPPER_CASE_NAME"} ...
```
## Arguments binding
When the configuration specifies a discrete value for a parameter (such as a string literal), the package will attempt to convert that value to the target method's declared CLR type of the parameter. Additional explicit handling is provided for parsing strings to `Uri`, `TimeSpan`, `enum`, arrays and custom collections.
Since version 7.0.0, conversion will use the invariant culture (`CultureInfo.InvariantCulture`) as long as the `ReadFrom.Configuration(IConfiguration configuration, ConfigurationReaderOptions options)` method is used. Obsolete methods use the current culture to preserve backward compatibility.
### Static member support
Static member access can be used for passing to the configuration argument via [special](https://github.com/serilog/serilog-settings-configuration/blob/dev/test/Serilog.Settings.Configuration.Tests/StringArgumentValueTests.cs#L35) syntax:
```yaml
{
"Args": {
"encoding": "System.Text.Encoding::UTF8",
"theme": "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console"
}
}
```
### Complex parameter value binding
If the parameter value is not a discrete value, it will try to find a best matching public constructor for the argument:
```yaml
{
"Name": "Console",
"Args": {
"formatter": {
// `type` (or $type) is optional, must be specified for abstract declared parameter types
"type": "Serilog.Templates.ExpressionTemplate, Serilog.Expressions",
"template": "[{@t:HH:mm:ss} {@l:u3} {Coalesce(SourceContext, '')}] {@m}\n{@x}"
}
}
}
```
For other cases the package will use the configuration binding system provided by _[Microsoft.Extensions.Options.ConfigurationExtensions](https://www.nuget.org/packages/Microsoft.Extensions.Options.ConfigurationExtensions/)_ to attempt to populate the parameter. Almost anything that can be bound by `IConfiguration.Get` should work with this package. An example of this is the optional `List` parameter used to configure the .NET Standard version of the _[Serilog.Sinks.MSSqlServer](https://github.com/serilog/serilog-sinks-mssqlserver)_ package.
### Abstract parameter types
If parameter type is an interface or an abstract class you need to specify the full type name that implements abstract type. The implementation type should have parameterless constructor.
```yaml
"Destructure": [
{ "Name": "With", "Args": { "policy": "Sample.CustomPolicy, Sample" } },
...
],
```
### IConfiguration parameter
If a Serilog package requires additional external configuration information (for example, access to a `ConnectionStrings` section, which would be outside of the `Serilog` section), the sink should include an `IConfiguration` parameter in the configuration extension method. This package will automatically populate that parameter. It should not be declared in the argument list in the configuration source.
### IConfigurationSection parameters
Certain Serilog packages may require configuration information that can't be easily represented by discrete values or direct binding-friendly representations. An example might be lists of values to remove from a collection of default values. In this case the method can accept an entire `IConfigurationSection` as a call parameter and this package will recognize that and populate the parameter. In this way, Serilog packages can support arbitrarily complex configuration scenarios.
## Samples
### Azure Functions (v2, v3)
hosts.json
```json
{
"version": "2.0",
"logging": {
"applicationInsights": {
"samplingExcludedTypes": "Request",
"samplingSettings": {
"isEnabled": true
}
}
},
"Serilog": {
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"System": "Warning"
}
},
"Enrich": [ "FromLogContext" ],
"WriteTo": [
{ "Name": "Seq", "Args": { "serverUrl": "http://localhost:5341" } }
]
}
}
```
In `Startup.cs` section name should be prefixed with [AzureFunctionsJobHost](https://docs.microsoft.com/en-us/azure/azure-functions/functions-app-settings#azurefunctionsjobhost__)
```csharp
public class Startup : FunctionsStartup
{
public override void Configure(IFunctionsHostBuilder builder)
{
builder.Services.AddSingleton(sp =>
{
var functionDependencyContext = DependencyContext.Load(typeof(Startup).Assembly);
var hostConfig = sp.GetRequiredService();
var options = new ConfigurationReaderOptions(functionDependencyContext) { SectionName = "AzureFunctionsJobHost:Serilog" };
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(hostConfig, options)
.CreateLogger();
return new SerilogLoggerProvider(logger, dispose: true);
});
}
}
```
In order to make auto-discovery of configuration assemblies work, modify Function's csproj file
```xml
```
### Versioning
This package tracks the versioning and target framework support of its [_Microsoft.Extensions.Configuration_](https://nuget.org/packages/Microsoft.Extensions.Configuration) dependency.