Serilog.Sinks.OpenObserve-YC 1.1.1

Serilog Sink for OpenObserve

Fork notice: This package (Serilog.Sinks.OpenObserve-YC) is a fork of Serilog.Sinks.OpenObserve-KKP by Konrad Kamiński - Pawlak, with additional features. The original package remains the upstream reference implementation.

New in this fork (v1.1.1): fix HttpClient BaseAddress Setting — useful for use sub path.

This Serilog sink allows to log to OpenObserve as the observability backend from your .NET application.

The sink is built to make use of the REST endpoint of the OpenObserve server.

Quick start

Precondition: Serilog has to be referenced in your project.

Install sink in your project.

dotnet add package Serilog.Sinks.OpenObserve-KKP

Using code configuration

Register the sink in code (Program.cs or similar).

var logger = new LoggerConfiguration()
    .WriteTo
    .OpenObserve(
        "url",
        "organization",
        "login",
        "key"
    ).CreateLogger();

Use serilog log method to log details (please check sample project).

logger.Debug("Debug message");

See Configuration specification for information about all possible parameters.

Using appsettings.json configuration

First install Serilog.Settings.Configuration package if you don't already have it:

dotnet add package Serilog.Settings.Configuration

Register the sink in code (Program.cs or similar).

var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(builder.Configuration)
	.CreateLogger();

In your appsettings.json file, extend the Serilog node or fully add the following:

{
  "Serilog": {
    "Using": ["Serilog.Sinks.OpenObserve-KKP"], // Enable OpenObserve-KKP sink
    "MinimumLevel": "Debug", // General minimum level of Serilog
    "WriteTo": [
      {
        "Name": "OpenObserve", // Name of this sink, don't change
        "Args": {
          "url": "https://api.openobserve.ai",
          "organization": "[organization]",
          "login": "[username]",
          "key": "[password or token]",
          "streamName": "[custom stream name if desired]", // Optional
          "restrictedToMinimumLevel": "Information" // Optional
        }
      }
    ],
    "Properties": {
      "Application": "OpenObserve.Tests"
    }
  }
}

Use serilog log method to log details (please check sample project).

logger.Debug("Debug message");

See Configuration specification for information about all possible parameters.

Data generated

With provided configuration following data will be send to the observability backend:

{"@t":"2023-08-03T20:53:20.2872427Z","@m":"Debug message","@mt":"Debug message","@i":"9515f1e2","@l":"Debug","SourceContext":"OpenObsere.Sample.CustomBackgroundService","Application":"OpenObserve.Tests"}

On server side it should look like this:

{
  "_i": "9515f1e2",
  "_l": "Debug",
  "_m": "Debug message",
  "_mt": "Debug message",
  "_t": "2023-08-03T20:53:20.2872427Z",
  "_timestamp": 1691096013274896,
  "application": "OpenObserve.Tests",
  "sourcecontext": "OpenObsere.Sample.CustomBackgroundService"
}

Please note:

• field _timestamp is added on server side
• field _mt contains message template, e.g Counter: {CounterValue}
• field _m contains rendered message, e.g. Counter: 2
• field _i is calculated on message template text, it's different for each different message template

More information about using Serilog is available in the Serilog Documentation.

Configuration specification

Parameters

Please note: It is NOT recommended to store your user password in a configuration of your application. Those credentials allow to login into the OpenObserve web interface. It is highly recommended to only use the token as key.

What is a token?

A token is a generated text string, having the function of a password, usually used for authentication. It allows to authenticate against the api without providing your actual user password.

How to retrieve my credentials / token

The OpenObserve web interface provides configuration examples under "Data sources".

"Data sources" - "Custom" - "Logs" - "Curl" shows the current username and token (format: username:token).
"Data sources" - "Custom" - "Logs" - "Syslog-Ng" shows a configuration similiar (not identical!) to one required for this sink.

Note: Currently OpenObserve only allows one token per user. It can be resetted in the "Data sources" page however no additional tokens can be generated. The token cannot be limited to any stream or organization.

What is an organization?

An organization is a management unit of users. For the self hosted system you may create any amount of organizations. The active organization can be seen in the web interface top right corner.

What is a stream?

A stream is a storage endpoint within OpenObserve. Streams can be created in the web interface but will also be automatically created as soon as log data specifying a stream is inbound. A stream contains specific storage configuration such as data retention.

REST

The sink is creating a REST POST command to the provided endpoint. Specifically the data will be sent to endpoint POST /api/{organization}/{stream}/_multi.

Please refer to the OpenObserve API documentation for more information.