diff --git a/CHANGES.md b/CHANGES.md index 424dd8e..a821f52 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,3 +1,9 @@ +2.2.0-* + * #11 - default to UTF-8 encoding **without BOM** + +2.1.0 + * #7 - overload accepting an `ITextFormatter` + 2.0.0 -- Moved to new project -- DotNet Core support \ No newline at end of file + * Moved to new project + * .NET Core support diff --git a/README.md b/README.md index 368518b..87de3f8 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,37 @@ Writes [Serilog](https://serilog.net) events to a set of text files, one per day. -The filename can include the `{Date}` placeholder, which will be replaced with the date of the events contained in the file. +### Getting started + +Install the [Serilog.Sinks.RollingFile](https://nuget.org/packages/serilog.sinks.rollingfile) package from NuGet: + +```powershell +Install-Package Serilog.Sinks.RollingFile +``` + +To configure the sink in C# code, call `WriteTo.RollingFile()` during logger configuration: ```csharp var log = new LoggerConfiguration() .WriteTo.RollingFile("log-{Date}.txt") .CreateLogger(); + +Log.Information("This will be written to the rolling file set"); +``` + +The filename should include the `{Date}` placeholder, which will be replaced with the date of the events contained in the file. Filenames use the `yyyyMMdd` date format so that files can be ordered using a lexicographic sort: + +``` +log-20160631.txt +log-20160701.txt +log-20160702.txt ``` -To avoid sinking apps with runaway disk usage the rolling file sink **limits file size to 1GB by default**. The limit can be changed or removed using the `fileSizeLimitBytes` parameter. +> **Important:** Only one process may write to a log file at a given time. For multi-process scenarios, either use separate files or [one of the non-file-based sinks](https://github.com/serilog/serilog/wiki/Provided-Sinks). + +### Limits + +To avoid bringing down apps with runaway disk usage the rolling file sink **limits file size to 1GB by default**. The limit can be changed or removed using the `fileSizeLimitBytes` parameter. ```csharp .WriteTo.RollingFile("log-{Date}.txt", fileSizeLimitBytes: null) @@ -22,6 +44,110 @@ For the same reason, only **the most recent 31 files** are retained by default ( .WriteTo.RollingFile("log-{Date}.txt", retainedFileCountLimit: null) ``` -> **Important:** Only one process may write to a log file at a given time. For multi-process scenarios, either use separate files or one of the non-file-based sinks. +### XML `` configuration + +To use the rolling file sink with the [Serilog.Settings.AppSettings](https://github.com/serilog/serilog-settings-appsettings) package, first install that package if you haven't already done so: + +```powershell +Install-Package Serilog.Settings.AppSettings +``` + +Instead of configuring the logger in code, call `ReadFrom.AppSettings()`: + +```csharp +var log = new LoggerConfiguration() + .ReadFrom.AppSettings() + .CreateLogger(); +``` + +In your application's `App.config` or `Web.config` file, specify the rolling file sink assembly and required path format under the `` node: + +```xml + + + + +``` + +The parameters that can be set through the `serilog:write-to:RollingFile` keys are the method parameters accepted by the `WriteTo.RollingFile()` configuration method. This means, for example, that the `fileSizeLimitBytes` parameter can be set with: + +```xml + +``` + +Omitting the `value` will set the parameter to `null`: + +```xml + +``` + +In XML and JSON configuration formats, environment variables can be used in setting values. This means, for instance, that the log file path can be based on `TMP` or `APPDATA`: + +```xml + +``` + +### JSON `appsettings.json` configuration + +To use the rolling file sink with _Microsoft.Extensions.Configuration_, for example with ASP.NET Core or .NET Core, use the [Serilog.Settings.Configuration](https://github.com/serilog/serilog-settings-configuration) package. First install that package if you have not already done so: + +```powershell +Install-Package Serilog.Settings.Configuration +``` + +Instead of configuring the rolling file directly in code, call `ReadFrom.Configuration()`: + +```csharp +var configuration = new ConfigurationBuilder() + .AddJsonFile("appsettings.json") + .Build(); + +var logger = new LoggerConfiguration() + .ReadFrom.Configuration(configuration) + .CreateLogger(); +``` + +In your `appsettings.json` file, under the `Serilog` node, : + +```json +{ + "Serilog": { + "WriteTo": [ + { "Name": "RollingFile", "Args": { "pathFormat": "log-{Date}.txt" } } + ] + } +} +``` + +See the XML `` example above for a discussion of available `Args` options. + +### Controlling event formatting + +The rolling file sink creates events in a fixed text format by default: + +``` +2016-07-06 09:02:17.148 +10:00 [Information] HTTP "GET" "/" responded 200 in 1994 ms +``` + +The format is controlled using an _output template_, which the rolling file configuration method accepts as an `outputTemplate` parameter. + +The default format above corresponds to an output template like: + +```csharp + .WriteTo.RollingFile("log-{Date}.txt", + outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level}] {Message}{NewLine}{Exception}") +``` + +##### JSON event formatting + +To write events to the file in an alternative format such as JSON, pass an `ITextFormatter` as the first argument: + +```csharp + .WriteTo.RollingFile(new JsonFormatter(), "log-{Date}.txt") +``` + +### Alternatives + +The default rolling file sink is designed to suit most applications. So that we can keep it maintainable and reliable, it does not provide a large range of optional behavior. Check out alternative implemementations like [this one](https://github.com/BedeGaming/sinks-rollingfile) if your needs aren't met by the default version. _Copyright © 2016 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html)._ diff --git a/src/Serilog.Sinks.RollingFile/Sinks/RollingFile/RollingFileSink.cs b/src/Serilog.Sinks.RollingFile/Sinks/RollingFile/RollingFileSink.cs index 3e63e10..0644672 100644 --- a/src/Serilog.Sinks.RollingFile/Sinks/RollingFile/RollingFileSink.cs +++ b/src/Serilog.Sinks.RollingFile/Sinks/RollingFile/RollingFileSink.cs @@ -74,7 +74,7 @@ public RollingFileSink(string pathFormat, _textFormatter = textFormatter; _fileSizeLimitBytes = fileSizeLimitBytes; _retainedFileCountLimit = retainedFileCountLimit; - _encoding = encoding ?? Encoding.UTF8; + _encoding = encoding ?? new UTF8Encoding(encoderShouldEmitUTF8Identifier: false); _buffered = buffered; } diff --git a/src/Serilog.Sinks.RollingFile/project.json b/src/Serilog.Sinks.RollingFile/project.json index 0a191b0..bce4ede 100644 --- a/src/Serilog.Sinks.RollingFile/project.json +++ b/src/Serilog.Sinks.RollingFile/project.json @@ -1,5 +1,5 @@ { - "version": "2.1.0-*", + "version": "2.2.0-*", "description": "The rolling file sink for Serilog - Simple .NET logging with fully-structured events", "authors": [ "Serilog Contributors" ], "packOptions": { @@ -23,8 +23,9 @@ "dependencies": { "System.IO": "4.1.0", "System.IO.FileSystem.Primitives": "4.0.1", - "System.Runtime.InteropServices": "4.1.0" + "System.Runtime.InteropServices": "4.1.0", + "System.Text.Encoding.Extensions": "4.0.11" } } } -} \ No newline at end of file +}