Serilog.Sinks.Grafana.Loki 8.3.0

dotnet add package Serilog.Sinks.Grafana.Loki --version 8.3.0
NuGet\Install-Package Serilog.Sinks.Grafana.Loki -Version 8.3.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Serilog.Sinks.Grafana.Loki" Version="8.3.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Serilog.Sinks.Grafana.Loki --version 8.3.0
#r "nuget: Serilog.Sinks.Grafana.Loki, 8.3.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Serilog.Sinks.Grafana.Loki as a Cake Addin
#addin nuget:?package=Serilog.Sinks.Grafana.Loki&version=8.3.0

// Install Serilog.Sinks.Grafana.Loki as a Cake Tool
#tool nuget:?package=Serilog.Sinks.Grafana.Loki&version=8.3.0

Serilog.Sinks.Grafana.Loki

Made in Ukraine Build status NuGet version Latest release Documentation

Terms of use

By using this project or its source code, for any purpose and in any shape or form, you grant your implicit agreement to all the following statements:

  • You condemn Russia and its military aggression against Ukraine
  • You recognize that Russia is an occupant that unlawfully invaded a sovereign state
  • You support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas
  • You reject false narratives perpetuated by Russian state propaganda

Glory to Ukraine! πŸ‡ΊπŸ‡¦

Table of contents

What is this sink and Loki?

The Serilog Grafana Loki sink project is a sink (basically a writer) for the Serilog logging framework. Structured log events are written to sinks and each sink is responsible for writing it to its own backend, database, store etc. This sink delivers the data to Grafana Loki, a horizontally-scalable, highly-available, multi-tenant log aggregation system. It allows you to use Grafana for visualizing your logs.

You can find more information about what Loki is over on Grafana's website here.

Features:

  • Formats and batches log entries to Loki via HTTP (using actual API)
  • Global and contextual labels support
  • Flexible Loki labels configuration possibilities
  • Collision avoiding mechanism for labels
  • Integration with Serilog.Settings.Configuration
  • Customizable HTTP clients
  • HTTP client with gzip compression
  • Using fast System.Text.Json library for serialization
  • Possibility of sending json logs to Loki
  • No dependencies on another sinks

Comparison

Features comparison table could be found here

Breaking changes

The list of breaking changes could be found here

Quickstart

The Serilog.Sinks.Grafana.Loki NuGet package could be found here. Alternatively you can install it via one of the following commands below:

NuGet command:

Install-Package Serilog.Sinks.Grafana.Loki

.NET Core CLI:

dotnet add package Serilog.Sinks.Grafana.Loki

In the following example, the sink will send log events to Loki available on http://localhost:3100

ILogger logger = new LoggerConfiguration()
    .WriteTo.GrafanaLoki(
        "http://localhost:3100")
    .CreateLogger();

logger.Information("The god of the day is {@God}", odin)

Used in conjunction with Serilog.Settings.Configuration the same sink can be configured in the following way:

{
  "Serilog": {
    "Using": [
      "Serilog.Sinks.Grafana.Loki"
    ],
    "MinimumLevel": {
      "Default": "Debug"
    },
    "WriteTo": [
      {
        "Name": "GrafanaLoki",
        "Args": {
          "uri": "http://localhost:3100",
          "labels": [
            {
              "key": "app",
              "value": "web_app"
            }
          ],
          "propertiesAsLabels": [
            "app"
          ]
        }
      }
    ]
  }
}

Description of parameters and configuration details could be found here.

Custom HTTP Client

Serilog.Loki.Grafana.Loki exposes ILokiHttpClient interface with the main operations, required for sending logs. In order to use a custom HttpClient you can extend of default implementations:

  • Serilog.Sinks.Grafana.Loki.HttpClients.BaseLokiHttpClient (implements creation of internal HttpClient and setting credentials)
  • Serilog.Sinks.Grafana.Loki.HttpClients.LokiHttpClient (default client which sends logs via HTTP)
  • Serilog.Sinks.Grafana.Loki.HttpClients.LokiGzipHttpClient (default client which sends logs via HTTP with gzip compression)

or create one implementing Serilog.Sinks.Grafana.Loki.ILokiHttpClient.

// CustomHttpClient.cs

public class CustomHttpClient : BaseLokiHttpClient
{
    public override Task<HttpResponseMessage> PostAsync(string requestUri, Stream contentStream)
    {
        return base.PostAsync(requestUri, contentStream);
    }
}
// Usage

Log.Logger = new LoggerConfiguration()
    .WriteTo.GrafanaLoki(
         "http://localhost:3100",
         httpClient: new CustomHttpClient()
    )
    .CreateLogger();

Sending json content to Loki

From v8 Serilog.Sinks.Grafana.Loki uses LokiJsonTextFormatter by default, which allows to send logs to Loki as a JSON-payloads. This allows easier filtering in Loki v2, more information about how to filter can be found here

Also, you could implement your own formatter, implementing Serilog.Formatting.ITextFormatter interface and pass it to the sink configuration.

Example configuration:

{
  "Serilog": {
    "Using": [
      "Serilog.Sinks.Grafana.Loki"
    ],
    "MinimumLevel": {
      "Default": "Debug"
    },
    "WriteTo": [
      {
        "Name": "GrafanaLoki",
        "Args": {
          "uri": "http://localhost:3100",
          "textFormatter": "My.Awesome.Namespace.MyTextFormatter, MyCoolAssembly"
        }
      }
    ]
  }
}

Inspiration and Credits

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (41)

Showing the top 5 NuGet packages that depend on Serilog.Sinks.Grafana.Loki:

Package Downloads
Convey.Logging

Convey.Logging

Only.CoffeeFace.Web

Only.CoffeeFace web api stuff

Flour.Logging

Flour.Logging

Genocs.Logging

The logging library useful to build .NET Core projects.

LDFCore.Serilog

Package Description

GitHub repositories (6)

Showing the top 5 popular GitHub repositories that depend on Serilog.Sinks.Grafana.Loki:

Repository Stars
snatch-dev/Convey
A simple recipe for .NET Core microservices.
slskd/slskd
A modern client-server application for the Soulseek file sharing network.
MUnique/OpenMU
This project aims to create an easy to use, extendable and customizable server for a MMORPG called "MU Online".
mizrael/SuperSafeBank
Sample Event Sourcing implementation with .NET Core
compujuckel/AssettoServer
Custom Assetto Corsa server with focus on freeroam
Version Downloads Last updated
8.3.0 204,946 1/30/2024
8.2.0 374,708 10/30/2023
8.2.0-beta.3 87 10/28/2023
8.2.0-beta.2 4,221 10/5/2023
8.2.0-beta.1 8,534 7/17/2023
8.2.0-beta.0 146 7/10/2023
8.1.0 1,159,999 11/26/2022
8.0.1 226,595 10/13/2022
8.0.0 329,483 7/19/2022
8.0.0-beta.0 8,336 4/1/2022
7.1.1 993,130 3/23/2022
7.1.0 801,657 9/21/2021
7.0.2 45,653 8/30/2021
7.0.1 14,652 8/17/2021
7.0.0 1,445 8/15/2021
6.0.1 97,002 6/7/2021
6.0.0 21,956 6/2/2021
5.1.3 36,133 5/10/2021
5.1.2 46,971 4/13/2021
5.0.0 130,578 11/29/2020
4.0.2 5,635 11/15/2020
4.0.1 1,080 11/14/2020
4.0.0 1,780 11/8/2020
3.1.0 7,657 5/19/2020
3.0.1 1,889 5/18/2020
3.0.0 2,921 5/17/2020

For release notes, please see the change log on GitHub.