Merge pull request #41 from serilog/dev

2.3.0 Release

.gitignore

@@ -236,3 +236,6 @@ _Pvt_Extensions
 .fake/
 
 BenchmarkDotNet.Artifacts/
+.idea
+*.orig
+

README.md

@@ -1,9 +1,53 @@
-# Serilog.Sinks.PeriodicBatching
+# Serilog.Sinks.PeriodicBatching [![Build status](https://ci.appveyor.com/api/projects/status/w2agqyd8rn0jur9y?svg=true)](https://ci.appveyor.com/project/serilog/serilog-sinks-periodicbatching) [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.periodicbatching.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.periodicbatching/)
 
-A base for Serilog sinks that batch and asynchronously send events to a slow/remote target.
+A wrapper for Serilog sinks that asynchronously emits events in batches, useful when logging to a slow and/or remote target.
 
-[![Build status](https://ci.appveyor.com/api/projects/status/w2agqyd8rn0jur9y?svg=true)](https://ci.appveyor.com/project/serilog/serilog-sinks-periodicbatching) [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.periodicbatching.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.periodicbatching/)
+### Getting started
 
-* [Documentation](https://github.com/serilog/serilog/wiki)
+Sinks that, for performance reasons, need to emit events in batches, can be implemented using `PeriodicBatchingSink`
+from this package.
 
-Copyright © 2016 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html).
+First, install the package into your Sink project:
+
+```
+dotnet add package Serilog.Sinks.PeriodicBatching
+```
+
+Then, instead of implementing Serilog's `ILogEventSink`, implement `IBatchedLogEventSink` in your sink class:
+
+```csharp
+class ExampleBatchedSink : IBatchedLogEventSink
+{
+    public async Task EmitBatchAsync(IEnumerable<LogEvent> batch)
+    {
+        foreach (var logEvent in batch)
+            Console.WriteLine(logEvent);
+    }
+
+    public Task OnEmptyBatchAsync() { }
+}
+```
+
+Finally, in your sink's configuration method, construct a `PeriodicBatchingSink` that wraps your batched sink:
+
+```csharp
+public static class LoggerSinkExampleConfiguration
+{
+    public static LoggerConfiguration Example(this LoggerSinkConfiguration loggerSinkConfiguration)
+    {
+        var exampleSink = new ExampleBatchedSink();
+
+        var batchingOptions = new PeriodicBatchingSinkOptions
+        {
+            BatchSize = 100,
+            Period = TimeSpan.FromSeconds(2),
+            EagerlyEmitFirstEvent = true,
+            QueueSizeLimit = 10000
+        };
+
+        var batchingSink = new PeriodicBatchingSink(exampleSink, batchingOptions);
+
+        return loggerSinkConfiguration.Sink(batchingSink);
+    }
+}
+```

appveyor.yml

@@ -1,7 +1,6 @@
 version: '{build}'
 skip_tags: true
-image: Visual Studio 2017
-configuration: Release
+image: Visual Studio 2019
 install:
   - ps: mkdir -Force ".\build\" | Out-Null
   - ps: Invoke-WebRequest "https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/dotnet-install.ps1" -OutFile ".\build\installcli.ps1"

serilog-sinks-periodicbatching.sln.DotSettings

@@ -0,0 +1,6 @@
+<wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=backoff/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=liveness/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=ramping/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Serilog/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=sink_0027s/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

src/Serilog.Sinks.PeriodicBatching/Serilog.Sinks.PeriodicBatching.csproj

@@ -1,12 +1,13 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>The periodic batching sink for Serilog</Description>
-    <VersionPrefix>2.2.0</VersionPrefix>
+    <VersionPrefix>2.3.0</VersionPrefix>
     <Authors>Serilog Contributors</Authors>
     <TargetFrameworks>net45;netstandard1.1;netstandard1.2;netstandard2.0</TargetFrameworks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <AssemblyName>Serilog.Sinks.PeriodicBatching</AssemblyName>
+    <RootNamespace>Serilog</RootNamespace>
     <AssemblyOriginatorKeyFile>../../assets/Serilog.snk</AssemblyOriginatorKeyFile>
     <SignAssembly>true</SignAssembly>
     <PublicSign Condition=" '$(OS)' != 'Windows_NT' ">true</PublicSign>

src/Serilog.Sinks.PeriodicBatching/Sinks/PeriodicBatching/BatchedConnectionStatus.cs

@@ -1,4 +1,4 @@
-// Copyright 2013-2016 Serilog Contributors
+// Copyright 2013-2020 Serilog Contributors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -19,7 +19,7 @@ namespace Serilog.Sinks.PeriodicBatching
     /// <summary>
     /// Manages reconnection period and transient fault response for <see cref="PeriodicBatchingSink"/>.
     /// During normal operation an object of this type will simply echo the configured batch transmission
-    /// period. When availabilty fluctuates, the class tracks the number of failed attempts, each time
+    /// period. When availability fluctuates, the class tracks the number of failed attempts, each time
     /// increasing the interval before reconnection is attempted (up to a set maximum) and at predefined
     /// points indicating that either the current batch, or entire waiting queue, should be dropped. This
     /// Serves two purposes - first, a loaded receiver may need a temporary reduction in traffic while coming

src/Serilog.Sinks.PeriodicBatching/Sinks/PeriodicBatching/BoundedConcurrentQueue.cs

@@ -1,36 +1,45 @@
-using System;
+// Copyright 2013-2020 Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
 using System.Collections.Concurrent;
 using System.Threading;
 
 namespace Serilog.Sinks.PeriodicBatching
 {
-    class BoundedConcurrentQueue<T> 
+    class BoundedConcurrentQueue<T>
     {
-        const int NON_BOUNDED = -1;
+        public const int Unbounded = -1;
 
         readonly ConcurrentQueue<T> _queue = new ConcurrentQueue<T>();
         readonly int _queueLimit;
 
         int _counter;
 
-        public BoundedConcurrentQueue() 
-        {
-            _queueLimit = NON_BOUNDED;
-        }
-
-        public BoundedConcurrentQueue(int queueLimit)
+        public BoundedConcurrentQueue(int? queueLimit = null)
         {
-            if (queueLimit <= 0)
-                throw new ArgumentOutOfRangeException(nameof(queueLimit), "queue limit must be positive");
+            if (queueLimit.HasValue && queueLimit <= 0)
+                throw new ArgumentOutOfRangeException(nameof(queueLimit), "Queue limit must be positive, or `null` to indicate unbounded.");
 
-            _queueLimit = queueLimit;
+            _queueLimit = queueLimit ?? Unbounded;
         }
 
         public int Count => _queue.Count;
 
         public bool TryDequeue(out T item)
         {
-            if (_queueLimit == NON_BOUNDED)
+            if (_queueLimit == Unbounded)
                 return _queue.TryDequeue(out item);
 
             var result = false;
@@ -50,7 +59,7 @@ public bool TryDequeue(out T item)
 
         public bool TryEnqueue(T item)
         {
-            if (_queueLimit == NON_BOUNDED)
+            if (_queueLimit == Unbounded)
             {
                 _queue.Enqueue(item);
                 return true;

src/Serilog.Sinks.PeriodicBatching/Sinks/PeriodicBatching/IBatchedLogEventSink.cs

@@ -0,0 +1,38 @@
+// Copyright 2013-2020 Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Serilog.Events;
+
+namespace Serilog.Sinks.PeriodicBatching
+{
+    /// <summary>
+    /// Interface for targets that accept events in batches.
+    /// </summary>
+    public interface IBatchedLogEventSink
+    {
+        /// <summary>
+        /// Emit a batch of log events, running asynchronously.
+        /// </summary>
+        /// <param name="batch">The batch of events to emit.</param>
+        Task EmitBatchAsync(IEnumerable<LogEvent> batch);
+
+        /// <summary>
+        /// Allows sinks to perform periodic work without requiring additional threads
+        /// or timers (thus avoiding additional flush/shut-down complexity).
+        /// </summary>
+        Task OnEmptyBatchAsync();
+    }
+}