diff --git a/README.md b/README.md index 80d974f..f08f23a 100644 --- a/README.md +++ b/README.md @@ -1626,7 +1626,7 @@ rating above. The same breakdown appears as a hint on any points value in the | Scope Or Context | 71.75 ns | 71.75 ns | 100 | 120 B | 120 B | 100 | | Template Rendering | 35.27 ns | 35.27 ns | 100 | 0 B | 0 B | 100 | | Buffered Logging | — | 93.36 ns | 0 | — | 0 B | 0 | -| Create Logger | 44.44 μs | 1.08 μs | 15.6 | 21.25 KB | 3.07 KB | 38.1 | +| Prepare Logger | 44.44 μs | 1.08 μs | 15.6 | 21.25 KB | 3.07 KB | 38.1 | | Formatted Output | — | 222.72 ns | 0 | — | 0 B | 0 | #### 2. NLog — 1143 of 1800 @@ -1640,7 +1640,7 @@ rating above. The same breakdown appears as a hint on any points value in the | Scope Or Context | 92.22 ns | 71.75 ns | 88.3 | 248 B | 120 B | 72.8 | | Template Rendering | 84.18 ns | 35.27 ns | 65.3 | 232 B | 0 B | 30.6 | | Buffered Logging | 93.36 ns | 93.36 ns | 100 | 120 B | 0 B | 40.8 | -| Create Logger | 5.21 μs | 1.08 μs | 45.5 | 24.46 KB | 3.07 KB | 35.6 | +| Prepare Logger | 5.21 μs | 1.08 μs | 45.5 | 24.46 KB | 3.07 KB | 35.6 | | Formatted Output | 222.72 ns | 222.72 ns | 100 | 272 B | 0 B | 28.5 | #### 3. Serilog — 983 of 1800 @@ -1654,7 +1654,7 @@ rating above. The same breakdown appears as a hint on any points value in the | Scope Or Context | 238.47 ns | 71.75 ns | 55.1 | 544 B | 120 B | 50.4 | | Template Rendering | 213.07 ns | 35.27 ns | 41.2 | 432 B | 0 B | 22.9 | | Buffered Logging | 395.4 ns | 93.36 ns | 48.8 | 160 B | 0 B | 36.1 | -| Create Logger | 1.08 μs | 1.08 μs | 100 | 3.07 KB | 3.07 KB | 100 | +| Prepare Logger | 1.08 μs | 1.08 μs | 100 | 3.07 KB | 3.07 KB | 100 | | Formatted Output | 417.86 ns | 222.72 ns | 73.1 | 296 B | 0 B | 27.4 | #### 4. log4net — 833 of 1800 @@ -1668,7 +1668,7 @@ rating above. The same breakdown appears as a hint on any points value in the | Scope Or Context | 343.96 ns | 71.75 ns | 45.9 | 848 B | 120 B | 40.6 | | Template Rendering | 135.52 ns | 35.27 ns | 51.5 | 280 B | 0 B | 28.1 | | Buffered Logging | 516.38 ns | 93.36 ns | 42.7 | 848 B | 0 B | 16.6 | -| Create Logger | 14.52 μs | 1.08 μs | 27.2 | 6.79 KB | 3.07 KB | 67.4 | +| Prepare Logger | 14.52 μs | 1.08 μs | 27.2 | 6.79 KB | 3.07 KB | 67.4 | | Formatted Output | 252.91 ns | 222.72 ns | 93.9 | 217 B | 0 B | 31.6 | #### 5. OpenTelemetry — 818 of 1800 @@ -1682,7 +1682,7 @@ rating above. The same breakdown appears as a hint on any points value in the | Scope Or Context | 185.52 ns | 71.75 ns | 62.5 | 168 B | 120 B | 86.6 | | Template Rendering | 282 ns | 35.27 ns | 35.8 | 112 B | 0 B | 42 | | Buffered Logging | 198.24 ns | 93.36 ns | 68.8 | 48 B | 0 B | 57.7 | -| Create Logger | 256.53 μs | 1.08 μs | 6.483 | 81.1 KB | 3.07 KB | 19.5 | +| Prepare Logger | 256.53 μs | 1.08 μs | 6.483 | 81.1 KB | 3.07 KB | 19.5 | | Formatted Output | — | 222.72 ns | 0 | — | 0 B | 0 | #### 6. ZLogger — 559 of 1800 @@ -1696,7 +1696,7 @@ rating above. The same breakdown appears as a hint on any points value in the | Scope Or Context | — | 71.75 ns | 0 | — | 120 B | 0 | | Template Rendering | — | 35.27 ns | 0 | — | 0 B | 0 | | Buffered Logging | 124.11 ns | 93.36 ns | 86.8 | 0 B | 0 B | 100 | -| Create Logger | 66.86 μs | 1.08 μs | 12.7 | 21.36 KB | 3.07 KB | 38 | +| Prepare Logger | 66.86 μs | 1.08 μs | 12.7 | 21.36 KB | 3.07 KB | 38 | | Formatted Output | 381.63 ns | 222.72 ns | 76.5 | 0 B | 0 B | 100 | @@ -1803,11 +1803,11 @@ Enqueues one event to a library-provided async or buffering wrapper and validate ![Logging Buffered Logging benchmark](reports/Logging/charts/07-buffered-logging.png) -#### 08 · Create Logger +#### 08 · Prepare Logger Creates, verifies, and releases one Information-enabled logger with an in-memory sink. -![Logging Create Logger benchmark](reports/Logging/charts/08-create-logger.png) +![Logging Prepare Logger benchmark](reports/Logging/charts/08-prepare-logger.png) #### 09 · Formatted Output diff --git a/build/build.csproj b/build/build.csproj index a150658..b4f495b 100644 --- a/build/build.csproj +++ b/build/build.csproj @@ -17,7 +17,7 @@ runtime; build; native; contentfiles; analyzers; buildtransitive - + diff --git a/metadata/Logging/features.json b/metadata/Logging/features.json index f7597e7..9033d1d 100644 --- a/metadata/Logging/features.json +++ b/metadata/Logging/features.json @@ -46,7 +46,7 @@ { "id": "PrepareLogger", "order": 8, - "name": "Create Logger", + "name": "Prepare Logger", "description": "Creates, verifies, and releases one Information-enabled logger with an in-memory sink." }, { diff --git a/readme/art_overview/en_overview.md b/readme/art_overview/en_overview.md index 467d20a..e459a31 100644 --- a/readme/art_overview/en_overview.md +++ b/readme/art_overview/en_overview.md @@ -9,7 +9,7 @@ The principle behind the project is *Evidence, not faith*. - Interactive matrix: [matrix.dev-team.org](https://matrix.dev-team.org/) - Repository: [github.com/DevTeam/dotnet-matrix](https://github.com/DevTeam/dotnet-matrix) (MIT) -The matrix currently holds **6 categories, 40 libraries and 67 scenarios**. +The matrix currently holds **8 categories, 53 libraries and 99 scenarios**. This article is for .NET developers who: @@ -84,16 +84,18 @@ Results add up into an overall rating: scenarios are collected into groups (for | Category | Rating leader | Libraries | Scenarios | |---|---|---:|---:| -| CSV Processing | Sep | 3 | 10 | +| CSV Processing | Sep | 4 | 10 | | Dependency Injection | Pure.DI | 23 | 15 | | JSON Serialization | System.Text.Json | 3 | 14 | -| Logging | Microsoft.Extensions.Logging | 5 | 8 | +| LINQ Queries | ZLinq | 6 | 18 | +| Logging | Microsoft.Extensions.Logging | 6 | 9 | | Object Mapping | Mapperly | 4 | 10 | -| Validation | DataAnnotations | 3 | 10 | +| Validation | Microsoft.Extensions.Validation | 4 | 10 | +| ZIP Archives | SharpZipLib | 3 | 13 | The measured numbers are deliberately left out of this article: they are tied to specific package versions and to the environment the tests ran in, and they go stale quickly. For current figures, charts and the feature matrix, use the application: [matrix.dev-team.org](https://matrix.dev-team.org/). -The **baselines** deserve a separate word. Several categories include a "zero option" alongside the libraries: `HandCoded` — code written by hand — in Dependency Injection and Object Mapping, and `System.Text.Json`, `DataAnnotations` and `Microsoft.Extensions.Logging`, which the platform already ships. It is a genuinely useful data point, because it answers the question of **how much you are paying for the library** and whether it is worth taking at all. And sometimes the answer is a surprise: in Validation and JSON Serialization the rating is currently led by the platform options — `DataAnnotations` and `System.Text.Json`. +The **baselines** deserve a separate word. Several categories include a "zero option" alongside the libraries: `HandCoded` — code written by hand — in Dependency Injection, LINQ Queries and Object Mapping, and `System.Linq`, `System.Text.Json`, `DataAnnotations`, `System.IO.Compression` and `Microsoft.Extensions.Logging`, which the platform already ships. It is a genuinely useful data point, because it answers the question of **how much you are paying for the library** and whether it is worth taking at all. And sometimes the answer is a surprise: in Validation and JSON Serialization the rating is currently led by the platform options — `Microsoft.Extensions.Validation` and `System.Text.Json`. --- diff --git a/readme/art_overview/ru_overview.md b/readme/art_overview/ru_overview.md index 4b7bcb1..d796ef8 100644 --- a/readme/art_overview/ru_overview.md +++ b/readme/art_overview/ru_overview.md @@ -9,7 +9,7 @@ - Интерактивная матрица: [matrix.dev-team.org](https://matrix.dev-team.org/) - Репозиторий: [github.com/DevTeam/dotnet-matrix](https://github.com/DevTeam/dotnet-matrix) (MIT) -Сейчас в матрице **6 категорий, 40 библиотек и 67 сценариев**. +Сейчас в матрице **8 категорий, 53 библиотеки и 99 сценариев**. Статья рассчитана на .NET-разработчиков, которым: @@ -84,16 +84,18 @@ | Категория | Лидер рейтинга | Библиотек | Сценариев | |---|---|---:|---:| -| CSV Processing | Sep | 3 | 10 | +| CSV Processing | Sep | 4 | 10 | | Dependency Injection | Pure.DI | 23 | 15 | | JSON Serialization | System.Text.Json | 3 | 14 | -| Logging | Microsoft.Extensions.Logging | 5 | 8 | +| LINQ Queries | ZLinq | 6 | 18 | +| Logging | Microsoft.Extensions.Logging | 6 | 9 | | Object Mapping | Mapperly | 4 | 10 | -| Validation | DataAnnotations | 3 | 10 | +| Validation | Microsoft.Extensions.Validation | 4 | 10 | +| ZIP Archives | SharpZipLib | 3 | 13 | Цифры статистики намеренно не приводятся: они привязаны к версиям пакетов и к окружению, в котором проходили тесты, и быстро устареют. Актуальные числа, графики и матрицу возможностей смотрите в приложении: [matrix.dev-team.org](https://matrix.dev-team.org/). -Отдельно стоит сказать про **эталонные реализации** (baseline). В нескольких категориях помимо библиотек участвует «нулевой вариант»: `HandCoded` — код, написанный руками, в Dependency Injection и Object Mapping; `System.Text.Json`, `DataAnnotations` и `Microsoft.Extensions.Logging` — то, что уже есть в платформе. Это довольно полезный показатель, он отвечает на вопрос, **сколько вы «платите» за библиотеку**, и стоит ли её использовать. И иногда ответ неожиданный: в Validation и JSON Serialization рейтинг сейчас возглавляют именно платформенные варианты — `DataAnnotations` и `System.Text.Json`. +Отдельно стоит сказать про **эталонные реализации** (baseline). В нескольких категориях помимо библиотек участвует «нулевой вариант»: `HandCoded` — код, написанный руками, в Dependency Injection, LINQ Queries и Object Mapping; `System.Linq`, `System.Text.Json`, `DataAnnotations`, `System.IO.Compression` и `Microsoft.Extensions.Logging` — то, что уже есть в платформе. Это довольно полезный показатель, он отвечает на вопрос, **сколько вы «платите» за библиотеку**, и стоит ли её использовать. И иногда ответ неожиданный: в Validation и JSON Serialization рейтинг сейчас возглавляют именно платформенные варианты — `Microsoft.Extensions.Validation` и `System.Text.Json`. --- diff --git a/reports/Logging/benchmarks.json b/reports/Logging/benchmarks.json index 8cb82ce..019806e 100644 --- a/reports/Logging/benchmarks.json +++ b/reports/Logging/benchmarks.json @@ -442,7 +442,7 @@ { "Order": 8, "Id": "PrepareLogger", - "Name": "Create Logger", + "Name": "Prepare Logger", "Results": [ { "LibraryId": "log4net", diff --git a/reports/Logging/charts/08-create-logger.png b/reports/Logging/charts/08-create-logger.png deleted file mode 100644 index c477578..0000000 Binary files a/reports/Logging/charts/08-create-logger.png and /dev/null differ diff --git a/reports/Logging/charts/08-prepare-logger.png b/reports/Logging/charts/08-prepare-logger.png index 10be0e1..02071e2 100644 Binary files a/reports/Logging/charts/08-prepare-logger.png and b/reports/Logging/charts/08-prepare-logger.png differ diff --git a/reports/Logging/charts/overview-prepare.png b/reports/Logging/charts/overview-prepare.png index 6130ea9..94f5909 100644 Binary files a/reports/Logging/charts/overview-prepare.png and b/reports/Logging/charts/overview-prepare.png differ diff --git a/reports/Logging/features.json b/reports/Logging/features.json index 27e6c43..7087d05 100644 --- a/reports/Logging/features.json +++ b/reports/Logging/features.json @@ -317,7 +317,7 @@ { "Order": 8, "Id": "PrepareLogger", - "Name": "Create Logger", + "Name": "Prepare Logger", "Results": [ { "LibraryId": "log4net", diff --git a/src/Matrix.Logging/Benchmarks/Common/08_PrepareLogger.cs b/src/Matrix.Logging/Benchmarks/Common/08_PrepareLogger.cs index 125f732..c94d076 100644 --- a/src/Matrix.Logging/Benchmarks/Common/08_PrepareLogger.cs +++ b/src/Matrix.Logging/Benchmarks/Common/08_PrepareLogger.cs @@ -6,6 +6,6 @@ namespace Matrix.Logging.Benchmarks; [MatrixFeature( "PrepareLogger", 8, - "Create Logger", + "Prepare Logger", "Creates, verifies, and releases one Information-enabled logger with an in-memory sink.")] public partial class PrepareLogger; diff --git a/workflows/feature-contracts/logging.md b/workflows/feature-contracts/logging.md index 776a1ea..07693f2 100644 --- a/workflows/feature-contracts/logging.md +++ b/workflows/feature-contracts/logging.md @@ -104,7 +104,7 @@ Application category is `Matrix.Logging`. - Rating: feature-only because enqueue completion is not equivalent to synchronous sink delivery. -## 8. Create Logger +## 8. Prepare Logger - Operation: construct a logger configuration with one in-memory sink and Information minimum level, obtain the named logger, verify it is enabled, @@ -117,6 +117,24 @@ Application category is `Matrix.Logging`. invocation. - Rating: `prepare`. +## 9. Formatted Output + +- Operation: submit the Information message `Formatted event` through the + library's own output formatter into a bounded in-memory sink. +- Inside invocation: event creation, layout/template formatting, and + synchronous delivery of the formatted text or UTF-8 bytes to the sink. +- Outside invocation: setup builds the formatter with a library-appropriate + timestamp/level/logger/message layout; cleanup validates all three + validation invocations. +- Validation: the sink has received three formatted records and the last one + ends with `Formatted event`. +- Supported: the library defines a text output formatter that the matrix can + drive synchronously; matrix-owned formatting is not support. +- Unsupported: the library defines no comparable output formatter. This is + the case for Microsoft.Extensions.Logging, whose core package ships none, + and for OpenTelemetry, which exports log records instead. +- Rating: `structured`. + ## Availability meanings - `Supported`: every observable assertion above passes.