|
6 | 6 |
|
7 | 7 | This project aims to provide a Serilog sink to push structured log events to the [Honeycomb](https://www.honeycomb.io/) platform for observability and monitoring purposes. |
8 | 8 |
|
9 | | -By hooking up to serilog my objective is to allow all existing applications which already produce structured events for logging to easily include Honeycomb as part of their pipeline. |
| 9 | +By hooking up to serilog the goal is to allow all existing applications which already produce structured events for logging to easily include Honeycomb as part of their pipeline. |
| 10 | + |
| 11 | +This library will add an enricher that adds information about the ongoing [Activity/Span](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Api/README.md#introduction-to-opentelemetry-net-tracing-api).The moment the log message's created. |
| 12 | +This adds a `trace.trace_id` property that matches the activities `TraceId` and a `trace.parent_id` property which matches the `SpanId` of the activity to each log event. |
| 13 | +Every event will be tagged with `meta.annotation_type=span_event` in Honeycomb and you'll be able to see them when reviewing a trace. |
10 | 14 |
|
11 | 15 | ## Setup |
12 | 16 |
|
13 | 17 | To start using this sink simply download the package from [Nuget](https://www.nuget.org/packages/Honeycomb.Serilog.Sink/) and add it to your Serilog configuration as another sink in the pipeline. |
14 | 18 |
|
| 19 | +### Parameters |
| 20 | + |
| 21 | +#### Mandatory |
| 22 | + |
| 23 | +- dataset: The name of the dataset to send the log messages to. |
| 24 | +- api key: An API key with `Send Events` permissions on the dataset. |
| 25 | + |
| 26 | +#### Optional |
| 27 | + |
| 28 | +- httpClientFactory: a factory which will provide an instance of HttpClient. When passed it's the responsability of the caller to manage the lifecycle of the client. |
| 29 | +- honeycombUrl: the url to the honeycomb Events API, change it if you want to test or if using [Refinery](https://docs.honeycomb.io/manage-data-volume/refinery/). It defaults to _https://api.honeycomb.io_ |
| 30 | +- Batching Option: |
| 31 | + - batchSizeLimit: The maximum number of log events to send in a batch. Defaults to 1000. |
| 32 | + - period: The maximum amount of time before flushing the events. Defaults to 2 seconds. |
| 33 | + If you see issues with memory utilization troubleshoot the batching options, too big a batch size limmit might result in a lot of memory being used, too low numbers may result in too frequent calls to the API. |
| 34 | + |
15 | 35 | ### Download the package |
16 | 36 |
|
17 | 37 | ```powershell |
18 | | -> dotnet add package Honeycomb.Serilog.Sink |
| 38 | + dotnet add package Honeycomb.Serilog.Sink |
19 | 39 | ``` |
20 | 40 |
|
| 41 | +#### Example |
| 42 | + |
21 | 43 | ```csharp |
22 | 44 | using Honeycomb.Serilog.Sink; |
23 | 45 |
|
24 | | -[...] |
| 46 | +namespace Example |
| 47 | +{ |
| 48 | + public static class Program |
| 49 | + { |
| 50 | + public static int Main(string[] args) |
| 51 | + { |
| 52 | + Activity.DefaultIdFormat = ActivityIdFormat.W3C; |
| 53 | + Activity.ForceDefaultIdFormat = true; |
| 54 | + |
| 55 | + Log.Logger = new LoggerConfiguration() |
| 56 | + .WriteTo.HoneycombSink( |
| 57 | + teamId: dataset, |
| 58 | + apiKey: apiKey) |
| 59 | + .BuildLogger(); |
| 60 | + |
| 61 | + // Do stuff |
| 62 | + } |
| 63 | + } |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +#### Using service provider |
| 68 | + |
| 69 | +```csharp |
| 70 | +namespace Example |
| 71 | +{ |
| 72 | + public static class Program |
| 73 | + { |
| 74 | + public static int Main(string[] args) |
| 75 | + { |
| 76 | + Log.Logger = new LoggerConfiguration() |
| 77 | + .MinimumLevel.Override("Microsoft", LogEventLevel.Information) |
| 78 | + .Enrich.FromLogContext() |
| 79 | + .WriteTo.Console() |
| 80 | + .CreateBootstrapLogger(); |
| 81 | + |
| 82 | + try |
| 83 | + { |
| 84 | + Log.Information("Starting web host"); |
| 85 | + CreateHostBuilder(args).Build().Run(); |
| 86 | + return 0; |
| 87 | + } |
| 88 | + catch (Exception ex) |
| 89 | + { |
| 90 | + Log.Fatal(ex, "Host terminated unexpectedly"); |
| 91 | + return 1; |
| 92 | + } |
| 93 | + finally |
| 94 | + { |
| 95 | + Log.CloseAndFlush(); |
| 96 | + } |
| 97 | + } |
25 | 98 |
|
26 | | -string dataset = "The name of the dataset wher your data will be sent"; |
27 | | -string apiKey = "The api key given to you in Honeycomb"; |
| 99 | + public static IHostBuilder CreateWebHostBuilder(string[] args) |
| 100 | + { |
| 101 | + return Host.CreateDefaultBuilder(args) |
| 102 | + .UseSerilog((_, services, configuration) => |
| 103 | + { |
| 104 | + configuration.WriteTo.HoneycombSink( |
| 105 | + teamId: <Dataset>, |
| 106 | + apiKey: <Api Key>, |
| 107 | + httpClientFactory: () => |
| 108 | + services.GetRequiredService<IHttpClientFactory>() |
| 109 | + .CreateClient("honeycomb")); |
| 110 | + }); |
| 111 | + } |
| 112 | + } |
| 113 | +} |
28 | 114 |
|
29 | | -var logger = new LoggerConfiguration() |
30 | | - .WriteTo |
31 | | - [...] |
32 | | - .HoneycombSink(dataset, apiKey) |
33 | | - [...] |
34 | | - .CreateLogger(); |
35 | 115 | ``` |
0 commit comments