release 4.0.0

Added - [BREAKING CHANGE] Support for Serilog.Settings.Configuration required changing the extension methods configuring a HTTP sink. 'Options' and 'DurableOptions' no longer exist, and their properties are now optional parameters on the extension methods instead. - Support for HTTP body configuration using 'IBatchFormatter' and 'ITextFormatter'. This enables full control of how messages are serialized before being sent over the network. (contribution by @kvpt) - Support for specifying the maximum number of retained buffer files and their rotation period on the durable HTTP sink. (contribution by @rob-somerville) Fixes #8 Fixes #11 Fixes #19
FantasticFiasco · Jun 6, 2017 · 0c60d67 · 0c60d67
1 parent b7e2279
commit 0c60d67
Show file tree

Hide file tree

Showing 5 changed files with 158 additions and 39 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ This project adheres to [Semantic Versioning](http://semver.org/) and is followi
 
 ## Unreleased
 
+## [4.0.0] - 2017-06-06
+
 ### Added
 
 - [#8](https://github.com/FantasticFiasco/serilog-sinks-http/issues/8) [BREAKING CHANGE] Support for [Serilog.Settings.Configuration](https://github.com/serilog/serilog-settings-configuration) required changing the extension methods configuring a HTTP sink. `Options` and `DurableOptions` no longer exist, and their properties are now optional parameters on the extension methods instead.
@@ -16,19 +18,19 @@ This project adheres to [Semantic Versioning](http://semver.org/) and is followi
 
 - [#11](https://github.com/FantasticFiasco/serilog-sinks-http/issues/11) Enum `FormattingType` has been replaces with public access to the formatters `NormalRenderedTextFormatter`, `NormalTextFormatter`, `CompactRenderedTextFormatter` and `CompactTextFormatter`. Removing the enum opens up the possibility to specify your own text formatter.  (contribution by [@kvpt](https://github.com/kvpt))
 
-## 3.1.1 2017-04-24
+## [3.1.1] - 2017-04-24
 
 ### Fixed
 
 - Package project URL
 
-## 3.1.0 2017-03-12
+## [3.1.0] - 2017-03-12
 
 ### Added
 
 - Support for the formatting types: `FormattingType.NormalRendered`, `FormattingType.Normal`, `FormattingType.CompactRendered` and `FormattingType.Compact`. The formatting type can be configured via `Options` and `DurableOptions`.
 
-## 3.0.0 2017-03-04
+## [3.0.0] - 2017-03-04
 
 ### Added
 
@@ -39,12 +41,12 @@ This project adheres to [Semantic Versioning](http://semver.org/) and is followi
 - [BREAKING CHANGE] The syntax for creating a non-durable sink has been changed from `Http(string)` to `Http(string, Options)` to accommodate for the syntax to create a durable sink. A non-durable sink will lose data after a system or process restart.
 - Improve compatibility by supporting .NET Standard 1.3
 
-## 2.0.0 2016-11-23
+## [2.0.0] - 2016-11-23
 
 ### Changed
 
 - [#1](https://github.com/FantasticFiasco/serilog-sinks-http/pull/1) [BREAKING CHANGE] Sinks can be configured to use a custom implementation of `IHttpClient` (contribution by [@lhaussknecht](https://github.com/lhaussknecht))
 
-## 1.0.0 2016-11-03
+## [1.0.0] - 2016-11-03
 
 Initial version.
diff --git a/README.md b/README.md
@@ -1,21 +1,33 @@
-# Serilog.Sinks.Http
+# Serilog.Sinks.Http - A Serilog sink sending log events over HTTP
 
 [![Build status](https://ci.appveyor.com/api/projects/status/ayvak8yo23k962sg/branch/master?svg=true)](https://ci.appveyor.com/project/FantasticFiasco/serilog-sinks-http) [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.Http.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.Http/) [![Documentation](https://img.shields.io/badge/docs-wiki-yellow.svg)](https://github.com/serilog/serilog/wiki) [![Join the chat at https://gitter.im/serilog/serilog](https://img.shields.io/gitter/room/serilog/serilog.svg)](https://gitter.im/serilog/serilog) [![Help](https://img.shields.io/badge/stackoverflow-serilog-orange.svg)](http://stackoverflow.com/questions/tagged/serilog)
 
-A [Serilog](http://serilog.net/) sink that sends HTTP POST requests over the network.
-
 **Package** - [Serilog.Sinks.Http](https://www.nuget.org/packages/serilog.sinks.http)
-| **Platforms** - .NET 4.5, .NETStandard 1.3
+| **Platforms** - .NET 4.5, .NET Standard 1.3
+
+## Table of contents
+
+- [Super simple to use](#super-simple-to-use)
+- [Typical use case](#typical-use-case)
+- [HTTP sink](#http-sink)
+- [Durable HTTP sink](#durable-http-sink)
+- [Formatters](#formatters)
+- [Install via NuGet](#install-via-nuget)
+- [Credit](#credit)
 
-### Getting started
+---
 
-In the following example, the sink will send a HTTP POST request to `www.mylogs.com`.
+## Super simple to use
+
+In the following example, the sink will POST log events to `www.mylogs.com` over HTTP.
 
 ```csharp
-Serilog.ILogger log = new LoggerConfiguration()
+ILogger log = new LoggerConfiguration()
   .MinimumLevel.Verbose()
-  .WriteTo.Http("www.mylogs.com", new Options())
+  .WriteTo.Http("www.mylogs.com")
   .CreateLogger();
+
+log.Information("Logging {@Heartbeat} from {Computer}", heartbeat, computer);
 ```
 
 The sink is batching multiple log events into a single request, and the following hypothetical payload is sent over the network as JSON.
@@ -53,31 +65,90 @@ The sink is batching multiple log events into a single request, and the followin
 }
 ```
 
-### Durability
-
-A sink can be created as durable by calling `Http(string, DurableOptions)` instead of `Http(string, Options)`. A durable sink will persist log events on disk before sending them over the network, thus protecting against data loss after a system or process restart.
+## Typical use case
 
-### Typical use case
-
-Producing log events is only half the story. Unless you are consuming them in a matter that benefits you in development or operations, there is really no need to produce them in the first place.
+Producing log events is only half the story. Unless you are consuming them in a matter that benefits you in development or production, there is really no need to produce them in the first place.
 
 Integration with [Elastic Stack](https://www.elastic.co/products) (formerly know as ELK, an acronym for Elasticsearch, Logstash and Kibana) is powerful beyond belief, but there are many alternatives to get the log events into Elasticsearch.
 
-#### Send log events to Elasticsearch
+### Send log events to Elasticsearch
 
 The log events can be sent directly to Elasticsearch using [Serilog.Sinks.Elasticsearch](https://github.com/serilog/serilog-sinks-elasticsearch). In this case you've solved your problem without using this sink, and all is well in the world.
 
-#### Send log events to Logstash
+### Send log events to Logstash
 
 If you would like to send the log events to Logstash for further processing instead of sending them directly to Elasticsearch, this sink in combination with the [Logstash HTTP input plugin](https://www.elastic.co/blog/introducing-logstash-input-http-plugin) is the perfect match for you. It is a much better solution than having to install [Filebeat](https://www.elastic.co/products/beats/filebeat) on all your instances, mainly because it involves fewer moving parts.
 
-### Formatting types
+## HTTP sink
+
+The non-durable HTTP sink will send log events using HTTP POST over the network. A non-durable sink will lose data after a system or process restart.
+
+### Arguments
+
+The following arguments are available when creating a HTTP sink.
+
+- `requestUri` - The URI the request is sent to.
+- `batchPostingLimit` - The maximum number of events to post in a single batch. Default value is 1000.
+- `period` - The time to wait between checking for event batches. Default value is 2 seconds.
+- `textFormatter` - The formatter rendering individual log events into text, for example JSON. Default value is `NormalRenderedTextFormatter`.
+- `batchFormatter` - The formatter batching multiple log events into a payload that can be sent over the network. Default value is `DefaultBatchFormatter`.
+- `restrictedToMinimumLevel` - The minimum level for events passed through the sink. Default value is `LevelAlias.Minimum`.
+- `httpClient` - A custom `IHttpClient` implementation. Default value is `HttpClient`.
+
+## Durable HTTP sink
 
-#### FormattingType.NormalRendered
+The durable HTTP sink will send log events using HTTP POST over the network. A durable sink will persist log events on disk before sending them, thus protecting against data loss after a system or process restart.
+
+### Arguments
+
+The following arguments are available when creating a durable HTTP sink.
+
+- `requestUri` - The URI the request is sent to.
+- `bufferPathFormat` - The path format for a set of files that will be used to buffer events until they can be successfully sent over the network. Default value is `"Buffer-{Date}.json"`. To use file rotation that is on an 30 or 60 minute interval pass `"Buffer-{Hour}.json"` or `"Buffer-{HalfHour}.json"`.
+- `bufferFileSizeLimitBytes` - The maximum size, in bytes, to which the buffer log file for a specific date will be allowed to grow. By default no limit will be applied.
+- `retainedBufferFileCountLimit` - The maximum number of buffer files that will be retained, including the current buffer file. Under normal operation only 2 files will be kept, however if the log server is unreachable, the number of files specified by `retainedBufferFileCountLimit` will be kept on the file system. For unlimited retention, pass `null`. Default value is 31.
+- `batchPostingLimit` - The maximum number of events to post in a single batch. Default value is 1000.
+- `period` - The time to wait between checking for event batches. Default value is 2 seconds.
+- `textFormatter` - The formatter rendering individual log events into text, for example JSON. Default value is `NormalRenderedTextFormatter`.
+- `batchFormatter` - The formatter batching multiple log events into a payload that can be sent over the network. Default value is `DefaultBatchFormatter`.
+- `restrictedToMinimumLevel` - The minimum level for events passed through the sink. Default value is `LevelAlias.Minimum`.
+- `httpClient` - A custom `IHttpClient` implementation. Default value is `HttpClient`.
+
+## Formatters
+
+Formatters build a pipeline that takes a sequence of log events and turn them into something that can be sent over the network. There are two types of formatters, the _event formatter_ and the _batch formatter_.
+
+The event formatter has the responsibility of turning a single log event into a textual representation. It can serialize the log event into JSON, XML or anything else that matches the expectations of the receiving log server.
+
+The batch formatter has the responsibility of batching a sequence of log events into a single payload that can be sent over the network. It does not care about individual log event formatting but instead focuses on how these events are serialized together into a single HTTP request. 
+
+### Event formatters
+
+The sink comes pre-loaded with four event formatters where `NormalRenderedTextFormatter` is the default. You can decide to configure your sink to use any of these four, or write your own by implementing `ITextFormatter`.
+
+```csharp
+/// <summary>
+/// Formats log events in a textual representation.
+/// </summary>
+public interface ITextFormatter
+{
+  /// <summary>
+  /// Format the log event into the output.
+  /// </summary>
+  /// <param name="logEvent">
+  /// The event to format.
+  /// </param>
+  /// <param name="output">
+  /// The output.
+  /// </param>
+  void Format(LogEvent logEvent, TextWriter output);
+}
+```
+
+#### Formatter 1 - `NormalRenderedTextFormatter`
 
 The log event is normally formatted and the message template is rendered into a message. This is the most verbose formatting type and its network load is higher than the other options.
 
-Example:
 ```json
 {
   "Timestamp": "2016-11-03T00:09:11.4899425+01:00",
@@ -94,11 +165,10 @@ Example:
 }
 ```
 
-#### FormattingType.Normal
+#### Formatter 2 - `NormalTextFormatter`
 
- The log event is normally formatted and its data normalized. The lack of a rendered message means improved network load compared to `FormattingType.NormalRendered`. Often this formatting type is complemented with a log server that is capable of rendering the messages of the incoming log events.
+The log event is normally formatted and its data normalized. The lack of a rendered message means improved network load compared to `NormalRenderedTextFormatter`. Often this formatting type is complemented with a log server that is capable of rendering the messages of the incoming log events.
 
-Example:
 ```json
 {
   "Timestamp": "2016-11-03T00:09:11.4899425+01:00",
@@ -114,17 +184,16 @@ Example:
 }
 ```
 
-#### FormattingType.CompactRendered
+#### Formatter 3 - `CompactRenderedTextFormatter`
 
-The log event is formatted with minimizing size as a priority but still render the message template into a message. This formatting type greatly reduce the network load and should be used in situations where bandwidth is of importance.
+The log event is formatted with minimizing size as a priority but still render the message template into a message. This formatting type reduces the network load and should be used in situations where bandwidth is of importance.
 
 The compact formatter adheres to the following rules:
 
 - Built-in field names are short and prefixed with an `@`
 - The `Properties` property is flattened
 - The Information level is omitted since it is considered to be the default
 
-Example:
 ```json
 {
   "@t": "2016-11-03T00:09:11.4899425+01:00",
@@ -138,17 +207,16 @@ Example:
 }
 ```
 
-#### FormattingType.Compact
+#### Formatter 4 - `CompactTextFormatter`
 
-The log event is formatted with minimizing size as a priority and its data is normalized. The lack of a rendered message means even smaller network load compared to `FormattingType.CompactRendered` and should be used in situations where bandwidth is of importance. Often this formatting type is complemented with a log server that is capable of rendering the messages of the incoming log events.
+The log event is formatted with minimizing size as a priority and its data is normalized. The lack of a rendered message means even smaller network load compared to `CompactRenderedTextFormatter` and should be used in situations where bandwidth is of importance. Often this formatting type is complemented with a log server that is capable of rendering the messages of the incoming log events.
 
 The compact formatter adheres to the following rules:
 
 - Built-in field names are short and prefixed with an `@`
 - The `Properties` property is flattened
 - The Information level is omitted since it is considered to be the default
 
-Example:
 ```json
 {
   "@t": "2016-11-03T00:09:11.4899425+01:00",
@@ -161,7 +229,56 @@ Example:
 }
 ```
 
-### Install via NuGet
+### Batch formatters
+
+The sink comes pre-loaded with a batch formatter called `DefaultBatchFormatter`. It creates a JSON object with a property called `events` that holds the log events sent over the network.
+
+Example:
+```json
+{
+  "events": [
+    { "Message": "Event n" },
+    { "Message": "Event n+1" }
+  ]
+}
+```
+
+You can decide to use this batch formatter, or write your own by implementing `IBatchFormatter`.
+
+```csharp
+/// <summary>
+/// Formats batches of log events into payloads that can be sent over the network.
+/// </summary>
+public interface IBatchFormatter
+{
+  /// <summary>
+  /// Format the log events into a payload.
+  /// </summary>
+  /// <param name="logEvents">
+  /// The events to format.
+  /// </param>
+  /// <param name="formatter">
+  /// The formatter turning the log events into a textual representation.
+  /// </param>
+  /// <param name="output">
+  /// The payload to send over the network.
+  /// </param>
+  void Format(IEnumerable<LogEvent> logEvents, ITextFormatter formatter, TextWriter output);
+
+  /// <summary>
+  /// Format the log events into a payload.
+  /// </summary>
+  /// <param name="logEvents">
+  /// The events to format.
+  /// </param>
+  /// <param name="output">
+  /// The payload to send over the network.
+  /// </param>
+  void Format(IEnumerable<string> logEvents, TextWriter output);
+}
+```
+
+## Install via NuGet
 
 If you want to include the HTTP sink in your project, you can [install it directly from NuGet](https://www.nuget.org/packages/Serilog.Sinks.Http/).
 
@@ -171,7 +288,7 @@ To install the sink, run the following command in the Package Manager Console:
 PM> Install-Package Serilog.Sinks.Http
 ```
 
-### Credit
+## Credit
 
 Thank you [JetBrains](https://www.jetbrains.com/) for your important initiative to support the open source community with free licenses to your products.
 

diff --git a/src/Serilog.Sinks.Http/LoggerSinkConfigurationExtensions.cs b/src/Serilog.Sinks.Http/LoggerSinkConfigurationExtensions.cs
@@ -32,7 +32,7 @@ namespace Serilog
     public static class LoggerSinkConfigurationExtensions
     {
         /// <summary>
-        /// Adds a non durable sink that sends log events using HTTP POST over the network. A
+        /// Adds a non-durable sink that sends log events using HTTP POST over the network. A
         /// non-durable sink will lose data after a system or process restart.
         /// </summary>
         /// <param name="sinkConfiguration">The logger configuration.</param>
@@ -104,7 +104,7 @@ public static LoggerConfiguration Http(
         /// <param name="retainedBufferFileCountLimit">
         /// The maximum number of buffer files that will be retained, including the current buffer
         /// file. Under normal operation only 2 files will be kept, however if the log server is
-        /// unreachable, the number of files specifieid by <paramref name="retainedBufferFileCountLimit"/>
+        /// unreachable, the number of files specified by <paramref name="retainedBufferFileCountLimit"/>
         /// will be kept on the file system. For unlimited retention, pass null. Default value is 31.
         /// </param>
         /// <param name="batchPostingLimit">

diff --git a/src/Serilog.Sinks.Http/Serilog.Sinks.Http.csproj b/src/Serilog.Sinks.Http/Serilog.Sinks.Http.csproj
@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Version>3.1.1</Version>
+    <VersionPrefix>4.0.0</VersionPrefix>
     <AssemblyName>Serilog.Sinks.Http</AssemblyName>
     <Description>Serilog event sink that sends HTTP POST requests over the network.</Description>
     <TargetFrameworks>net45;netstandard1.3</TargetFrameworks>

diff --git a/src/Serilog.Sinks.Http/Sinks/Http/Private/Sinks/HttpSink.cs b/src/Serilog.Sinks.Http/Sinks/Http/Private/Sinks/HttpSink.cs
@@ -26,7 +26,7 @@
 namespace Serilog.Sinks.Http.Private.Sinks
 {
     /// <summary>
-    /// A non durable sink that sends log events using HTTP POST over the network. A non-durable
+    /// A non-durable sink that sends log events using HTTP POST over the network. A non-durable
     /// sink will lose data after a system or process restart.
     /// </summary>
     /// <seealso cref="PeriodicBatchingSink" />