Gelf.Extensions.Logging

GELF provider for Microsoft.Extensions.Logging for sending logs to Graylog, Logstash and more from .NET Standard 1.3+ compatible components.

Usage

The following examples are for ASP.NET Core. The samples directory contains example console apps with and without ASP.NET Core. For more information on providers and logging in general, see the aspnetcore logging documentation.

ASP.NET Core 2.x

In Program.cs, import the LoggingBuilder.AddGelf() extension method from Gelf.Extensions.Logging and add the following to your WebHost configuration.

var webHost = WebHost
    .CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging((context, builder) =>
    {
        // Read GelfLoggerOptions from appsettings.json
        builder.Services.Configure<GelfLoggerOptions>(context.Configuration.GetSection("Graylog"));

        // Optionally configure GelfLoggerOptions further.
        builder.Services.PostConfigure<GelfLoggerOptions>(options =>
            options.AdditionalFields["machine_name"] = Environment.MachineName);

        // Read Logging settings from appsettings.json and add providers.
        builder.AddConfiguration(context.Configuration.GetSection("Logging"))
            .AddConsole()
            .AddDebug()
            .AddGelf();
    })
    .Build();

You can then configure the "GELF" provider in appsettings.json in the same way as other providers.

{
  "Logging": {
    "IncludeScopes": false, 
    "LogLevel": {
      "Default": "Error"
    },
    "Console": {
      "LogLevel": {
        "Default": "Debug"
      }
    },
    "GELF": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "Graylog": {
    "Host": "localhost",
    "Port": 12201,
    "LogSource": "application-name"
  }
}

ASP.NET Core 1.x

In Startup.cs, import the LoggerFactory.AddGelf() extension method from Gelf.Extensions.Logging and add the following to your Configure() method.

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole()
        .AddDebug()
        .AddGelf(new GelfLoggerOptions
        {
            Host = "localhost",
            LogSource = "application-name",
            LogLevel = LogLevel.Information
        });

    ...
}

Http Headers

Http headers can be added to all logs using Http Protocol by setting them in GelfLoggerOptions.Headers.

Additional Fields

By default, logger and exception fields are included on all messages (the exception field is only added when an exception is passed to the logger). There are a number of other ways to attach data to logs.

Global Fields

Global fields can be added to all logs by setting them in GelfLoggerOptions.AdditionalFields.

var options = new GelfLoggerOptions
{
    Host = "graylog-host",
    LogSource = "my-application",
    AdditionalFields =
    {
        ["machine_name"] = Environment.MachineName,
        ["foo"] = "bar"
    }
});

Scoped Fields

Log scopes can also be used to attach fields to a group of related logs. Create a log scope with a ValueTuple<string, string>, ValueTuple<string, int/byte/double> (or any other numeric value) or Dictionary<string, object> to do so. Note that any other types passed to BeginScope() will be ignored, including Dictionary<string, string> and ValueTuple<string, object>.

using (_logger.BeginScope(("correlation_id", correlationId)))
{
    // Field will be added to all logs within this scope (using any ILogger<T> instance).
}

using (_logger.BeginScope(new Dictionary<string, object>
{
    ["order_id"] = orderId,
    ["customer_id"] = customerId
}))
{
    // Fields will be added to all logs within this scope (using any ILogger<T> instance).
}

Structured/Semantic Logging

Semantic logging is also supported meaning fields can be extracted from individual log lines.

_logger.LogInformation("Order {order_id} took {order_time} seconds to process", orderId, orderTime);

In the example above, the message will contain an order_id and order_time.

Log Filtering

When using .NET Core 2.x, the log filtering API should be used to filter the "GELF" provider (details here). In .NET Core 1.x, log filtering can be overridden by setting a custom filter with GelfLoggerOptions.Filter, overriding the default filter that uses GelfLoggerOptions.LogLevel.

Testing

This repository contains a Docker Compose file that can be used for creating local a Graylog stack with a single command using the Graylog Docker image. This can be useful for testing application logs locally. Requires Docker and Docker Compose.

• docker-compose up
• Navigate to http://localhost:9000
• Credentials: admin/admin
• Create a UDP input and send logs to localhost:12201

Contributing

Pull requests welcome! In order to run tests, first run docker-compose up to create the Graylog stack. Existing tests log messages and use the Graylog API to assert that they have been sent correctly. A UDP input will be created as part of the test setup (if not already present), so there is no need to create one manually. Build and tests are run on CI in Docker, meaning it is possible to run the build locally in identical conditions using docker-compose -f docker-compose.ci.build.yml -f docker-compose.yml up --abort-on-container-exit.