Merge pull request #30 from serilog/dev

1.1.0 Release

README.md

@@ -1,4 +1,4 @@
-# Serilog.Formatting.Compact [![Build status](https://ci.appveyor.com/api/projects/status/ch5il2airviylofn?svg=true)](https://ci.appveyor.com/project/serilog/serilog-formatting-compact) [![NuGet](https://img.shields.io/nuget/vpre/Serilog.Formatting.Compact.svg)](https://nuget.org/packages/Serilog.Formatting.Compact)
+# Serilog.Formatting.Compact [![Build status](https://ci.appveyor.com/api/projects/status/ch5il2airviylofn?svg=true)](https://ci.appveyor.com/project/serilog/serilog-formatting-compact) [![NuGet](https://img.shields.io/nuget/v/Serilog.Formatting.Compact.svg)](https://nuget.org/packages/Serilog.Formatting.Compact)
 
 A simple, compact JSON-based event format for Serilog. `CompactJsonFormatter` significantly reduces the byte count of small log events when compared with Serilog's default `JsonFormatter`, while remaining human-readable. It achieves this through shorter built-in property names, a leaner format, and by excluding redundant information.
 
@@ -15,16 +15,44 @@ A simple `Hello, {User}` event.
 Install from [NuGet](https://nuget.org/packages/Serilog.Formatting.Compact):
 
 ```powershell
-Install-Package Serilog.Formatting.Compact -Pre
+Install-Package Serilog.Formatting.Compact
 ```
 
-The formatter is used in conjunction with sinks that accept `ITextFormatter`. For example, the [rolling file](https://github.com/serilog/serilog-sinks-rollingfile) sink:
+The formatter is used in conjunction with sinks that accept `ITextFormatter`. For example, the [file](https://github.com/serilog/serilog-sinks-file) sink:
 
 ```csharp
 Log.Logger = new LoggerConfiguration()
-  .WriteTo.Sink(new RollingFileSink("./logs/myapp.txt", new CompactJsonFormatter(), null, null))
+  .WriteTo.File(new CompactJsonFormatter(), "./logs/myapp.json")
   .CreateLogger();
 ```
+#### XML `<appSettings>` configuration
+To specify the formatter in XML `<appSettings>` provide its assembly-qualified type name:
+
+```xml
+<appSettings>
+  <add key="serilog:using:File" value="Serilog.Sinks.File" />
+  <add key="serilog:write-to:File.path" value="./logs/myapp.json" />
+  <add key="serilog:write-to:File.formatter"
+       value="Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact" />
+```
+#### JSON `appsettings.json` configuration
+To specify formatter in json `appsettings.json` provide its assembly-qualified type name:
+
+```json
+{
+  "Serilog": {
+    "WriteTo": [
+      {
+        "Name": "File",
+        "Args": {
+          "path": "./logs/myapp.json",
+          "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
+        }
+      }
+    ]
+  }
+}
+```
 
 ### Rendered events
 
@@ -58,13 +86,13 @@ The format defines a handful of reified properties that have special meaning:
 | `@l` | Level | An implementation-specific level identifier (string or number) | Absence implies "informational"  |
 | `@x` | Exception | A language-dependent error representation potentially including backtrace | |
 | `@i` | Event id | An implementation specific event id (string or number) | |
-| `@r` | Renderings | If `@mt` includes properties with programming-language-specific formatting, an array of pre-rendered values for each such property | |
+| `@r` | Renderings | If `@mt` includes tokens with programming-language-specific formatting, an array of pre-rendered values for each such token | May be omitted; if present, the count of renderings must match the count of formatted tokens exactly |
 
 The `@` sigil may be escaped at the start of a user property name by doubling, e.g. `@@name` denotes a property called `@name`.
 
 ##### Batch format
 
-When events are batched into a single payload, a newline-delimited stream of JSON documents is required. Either `\n` or `\r\n` delimiters may be used.
+When events are batched into a single payload, a newline-delimited stream of JSON documents is required. Either `\n` or `\r\n` delimiters may be used. Batches of newline-separated compact JSON events can use the (unofficial) MIME type `application/vnd.serilog.clef`.
 
 ##### Versioning
 
@@ -110,7 +138,16 @@ See `test/Serilog.Formatting.Compact.Tests/FormattingBenchmarks.cs`.
 
 |                      Formatter |    Median  |    StdDev | Scaled |
 |:------------------------------ |----------: |---------: |------: |
-|                `JsonFormatter` | 11.2775 us | 0.0682 us |   1.00 |
-|         `CompactJsonFormatter` |  6.0315 us | 0.0429 us |   0.53 |
-|        `RenderedJsonFormatter` | 13.7585 us | 0.1194 us |   1.22 |
-| `RenderedCompactJsonFormatter` |  7.0680 us | 0.0605 us |   0.63 |
+|                `JsonFormatter` | 11.2775 &micro;s | 0.0682 &micro;s |   1.00 |
+|         `CompactJsonFormatter` |  6.0315 &micro;s | 0.0429 &micro;s |   0.53 |
+|        `RenderedJsonFormatter` | 13.7585 &micro;s | 0.1194 &micro;s |   1.22 |
+| `RenderedCompactJsonFormatter` |  7.0680 &micro;s | 0.0605 &micro;s |   0.63 |
+
+### Tools
+
+Several tools are available for working with the CLEF format.
+
+ * **[`clef-tool`](https://github.com/datalust/clef-tool)** - a CLI application for processing CLEF files
+ * **[Compact Log Format Viewer](https://github.com/warrenbuckley/Compact-Log-Format-Viewer)** - a cross-platform viewer for CLEF JSON files
+ * **[_Serilog.Formatting.Compact.Reader_](https://github.com/serilog/serilog-formatting-compact-reader)** - convert CLEF JSON documents back into Serilog `LogEvent`s
+

Setup.ps1

@@ -0,0 +1,10 @@
+$ErrorActionPreference = "Stop"
+
+$RequiredDotnetVersion =  $(cat ./global.json | convertfrom-json).sdk.version
+
+mkdir "./build"
+Invoke-WebRequest "https://dot.net/v1/dotnet-install.ps1" -OutFile "./build/installcli.ps1"
+& ./build/installcli.ps1 -InstallDir "$pwd/.dotnetcli" -NoPath -Version $RequiredDotnetVersion
+if ($LASTEXITCODE) { exit 1 }
+
+$env:Path = "$pwd/.dotnetcli;$env:Path"

appveyor.yml

@@ -1,13 +1,9 @@
 version: '{build}'
 skip_tags: true
-image: Visual Studio 2015
+image: Visual Studio 2019
 configuration: Release
 install:
-  - ps: mkdir -Force ".\build\" | Out-Null
-  - ps: Invoke-WebRequest "https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0-preview2/scripts/obtain/dotnet-install.ps1" -OutFile ".\build\installcli.ps1"
-  - ps: $env:DOTNET_INSTALL_DIR = "$pwd\.dotnetcli"
-  - ps: '& .\build\installcli.ps1 -InstallDir "$env:DOTNET_INSTALL_DIR" -NoPath -Version 1.0.0-preview2-003121'
-  - ps: $env:Path = "$env:DOTNET_INSTALL_DIR;$env:Path"
+  - ps: ./Setup.ps1
 build_script:
 - ps: ./Build.ps1
 test: off
@@ -16,7 +12,7 @@ artifacts:
 deploy:
 - provider: NuGet
   api_key:
-    secure: nvZ/z+pMS91b3kG4DgfES5AcmwwGoBYQxr9kp4XiJHj25SAlgdIxFx++1N0lFH2x
+    secure: ptRAVPZZO/hlZUv5e/yLnHF7aAh8tQmBfvLt64Qrvhoe7I/mbbPNI6RYm92g5EzG
   skip_symbols: true
   on:
     branch: /^(master|dev)$/

global.json

@@ -1,6 +1,5 @@
 {
-  "projects": [ "src", "test" ],
   "sdk": {
-    "version": "1.0.0-preview2-003121"
+    "version": "3.0.100"
   }
-}
+}

serilog-formatting-compact.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio 14
-VisualStudioVersion = 14.0.25123.0
+# Visual Studio 15
+VisualStudioVersion = 15.0.26114.2
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{037440DE-440B-4129-9F7A-09B42D00397E}"
 EndProject
@@ -10,37 +10,36 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assets", "assets", "{E9D1B5
 		appveyor.yml = appveyor.yml
 		Build.ps1 = Build.ps1
 		CHANGES.md = CHANGES.md
-		global.json = global.json
 		README.md = README.md
 		assets\Serilog.snk = assets\Serilog.snk
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{67B1C971-75EE-4ABE-B184-66AAC8D9D572}"
 EndProject
-Project("{8BB2217D-0F2D-49D1-97BC-3654ED321F3B}") = "Serilog.Formatting.Compact", "src\Serilog.Formatting.Compact\Serilog.Formatting.Compact.xproj", "{D8A74F4C-981B-41F1-B807-FE08DFCC06D4}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Serilog.Formatting.Compact", "src\Serilog.Formatting.Compact\Serilog.Formatting.Compact.csproj", "{E0BB862A-8B2C-46B5-9C90-B2F94C32EAB3}"
 EndProject
-Project("{8BB2217D-0F2D-49D1-97BC-3654ED321F3B}") = "Serilog.Formatting.Compact.Tests", "test\Serilog.Formatting.Compact.Tests\Serilog.Formatting.Compact.Tests.xproj", "{3C2D8E01-5580-426A-BDD9-EC59CD98E618}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Serilog.Formatting.Compact.Tests", "test\Serilog.Formatting.Compact.Tests\Serilog.Formatting.Compact.Tests.csproj", "{BAEECC42-EC0C-4955-8AA1-BD3F4F0F4AAD}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
 		Release|Any CPU = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{D8A74F4C-981B-41F1-B807-FE08DFCC06D4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{D8A74F4C-981B-41F1-B807-FE08DFCC06D4}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{D8A74F4C-981B-41F1-B807-FE08DFCC06D4}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{D8A74F4C-981B-41F1-B807-FE08DFCC06D4}.Release|Any CPU.Build.0 = Release|Any CPU
-		{3C2D8E01-5580-426A-BDD9-EC59CD98E618}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{3C2D8E01-5580-426A-BDD9-EC59CD98E618}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{3C2D8E01-5580-426A-BDD9-EC59CD98E618}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{3C2D8E01-5580-426A-BDD9-EC59CD98E618}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E0BB862A-8B2C-46B5-9C90-B2F94C32EAB3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E0BB862A-8B2C-46B5-9C90-B2F94C32EAB3}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E0BB862A-8B2C-46B5-9C90-B2F94C32EAB3}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E0BB862A-8B2C-46B5-9C90-B2F94C32EAB3}.Release|Any CPU.Build.0 = Release|Any CPU
+		{BAEECC42-EC0C-4955-8AA1-BD3F4F0F4AAD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{BAEECC42-EC0C-4955-8AA1-BD3F4F0F4AAD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{BAEECC42-EC0C-4955-8AA1-BD3F4F0F4AAD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{BAEECC42-EC0C-4955-8AA1-BD3F4F0F4AAD}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
-		{D8A74F4C-981B-41F1-B807-FE08DFCC06D4} = {037440DE-440B-4129-9F7A-09B42D00397E}
-		{3C2D8E01-5580-426A-BDD9-EC59CD98E618} = {67B1C971-75EE-4ABE-B184-66AAC8D9D572}
+		{E0BB862A-8B2C-46B5-9C90-B2F94C32EAB3} = {037440DE-440B-4129-9F7A-09B42D00397E}
+		{BAEECC42-EC0C-4955-8AA1-BD3F4F0F4AAD} = {67B1C971-75EE-4ABE-B184-66AAC8D9D572}
 	EndGlobalSection
 EndGlobal

src/Serilog.Formatting.Compact/Properties/AssemblyInfo.cs

@@ -1,9 +1,5 @@
-using System.Reflection;
-using System.Runtime.CompilerServices;
+using System.Runtime.CompilerServices;
 
-[assembly: AssemblyTitle("Serilog.Formatting.Compact")]
-[assembly: AssemblyDescription("A simple, compact JSON-based event format for Serilog.")]
-[assembly: AssemblyCopyright("Copyright © Serilog Contributors 2013-2016")]
 [assembly: InternalsVisibleTo("Serilog.Formatting.Compact.Tests, PublicKey=" +
                               "0024000004800000940000000602000000240000525341310004000001000100fb8d13fd344a1c" +
                               "6fe0fe83ef33c1080bf30690765bc6eb0df26ebfdf8f21670c64265b30db09f73a0dea5b3db4c9" +

src/Serilog.Formatting.Compact/Serilog.Formatting.Compact.csproj

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <Description>A simple, compact JSON-based event format for Serilog.</Description>
+    <VersionPrefix>1.1.0</VersionPrefix>
+    <Authors>Serilog Contributors</Authors>
+    <TargetFrameworks>net452;netstandard1.1;netstandard2.0</TargetFrameworks>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <AssemblyName>Serilog.Formatting.Compact</AssemblyName>
+    <AssemblyOriginatorKeyFile>../../assets/Serilog.snk</AssemblyOriginatorKeyFile>
+    <SignAssembly>true</SignAssembly>
+    <PublicSign Condition=" '$(OS)' != 'Windows_NT' ">true</PublicSign>
+    <PackageId>Serilog.Formatting.Compact</PackageId>
+    <PackageTags>serilog;json</PackageTags>
+    <PackageIconUrl>http://serilog.net/images/serilog-extension-nuget.png</PackageIconUrl>
+    <PackageProjectUrl>https://github.com/serilog/serilog-formatting-compact</PackageProjectUrl>
+    <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Serilog" Version="2.8.0" />
+  </ItemGroup>
+
+  <ItemGroup Condition=" '$(TargetFramework)' == 'net452' ">
+    <Reference Include="System" />
+    <Reference Include="Microsoft.CSharp" />
+  </ItemGroup>
+
+</Project>

test/Serilog.Formatting.Compact.Tests/Serilog.Formatting.Compact.Tests.csproj

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net452;netcoreapp2.1</TargetFrameworks>
+    <AssemblyName>Serilog.Formatting.Compact.Tests</AssemblyName>
+    <AssemblyOriginatorKeyFile>../../assets/Serilog.snk</AssemblyOriginatorKeyFile>
+    <SignAssembly>true</SignAssembly>
+    <PublicSign Condition=" '$(OS)' != 'Windows_NT' ">true</PublicSign>
+    <IsPackable>false</IsPackable>
+    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.3.0" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.1" />
+    <PackageReference Include="xunit" Version="2.4.1" />
+    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
+    <PackageReference Include="BenchmarkDotNet" Version="0.9.7-beta" />
+  </ItemGroup>
+
+  <ItemGroup Condition=" '$(TargetFramework)' == 'net452' ">
+    <Reference Include="System" />
+    <Reference Include="Microsoft.CSharp" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Serilog.Formatting.Compact\Serilog.Formatting.Compact.csproj" />
+  </ItemGroup>
+
+</Project>