Logstash provider for the ASP.NET Core logging framework.

• Installation
• Startup
• Logging
• Correlation
• LogMessage
• Sample

To add the toolbox to a project, you add the package to the project.json :

"dependencies": {
    "Toolbox.Logstash":  "0.7.0"
 }

In Visual Studio you can use the NuGet Package Manager to do this.

To start using the Logstash toolbox, call the AddLogstashHttp extension method on the ILoggerFactory. You have to pass in the IApplicationBuilder instance, so this is best done in de Configure method of the Startup class.

You can pass in the needed options, like this :

loggerFactory.AddLogstashHttp(app, opt => 
            {
                opt.AppId = "MyApplication";
                opt.Index = "MyApplication";
                opt.MessageVersion = "1";
                opt.MinimumLevel = LogLevel.Information;
                opt.Url = "http://my.logstash.url/api/v2/messages";
            });

or specify a IConfiguration instance that contains the needed options :

loggerFactory.AddLogstashHttp(Configuration.GetSection("Logstash"));   // where you have previously loaded the Configuration instance from a config file

The configuration section has the following layout :

{
    "AppId": "MyApplication",
    "Index": "MyApplicationIndex",
    "MessageVersion": "1",
    "MinimumLevel": "Information",
    "Url": "http://my.logstash.url/api/v2/messages"   
}

• AppId
  The id or name of the application. This value will be used in the source of the messages.
• Index
  The Logstash index to write to.
• MessageVersion
  The version of your message structure. This field can be used in Logstash during parsing (different parsing logic depending on the message format).
• MinimumLevel
  The minimum level that has to be written to Logstash.
• Url
  The url to the Logstash HTTP endpoint.

The Logstash toolbox adds a provider to the ASP.NET Core logging framework, so you can use the standard logging functions :

Logger.LogDebug("this is a debug log message.");
Logger.LogInformation("this is an information log message.");
// ...

One of the advantages of using the Logstash toolbox is that it adds metadata to the messages. If you want ameaningful correlation id in the messages, so that you can trace the messages back to their origin, add the Correlation Toolbox to your pipeline. The Correlation Toolbox will read the correlation header from an incoming HTTP request, keep it in memory and pass it on whenever you do a further call to another API. When this chain of calls logs their messages with the correlation id to the Logstash logs, you can trace back the call over several messages.

More info about the Correlation Toolbox is found here : https://github.com/digipolisantwerp/correlation_aspnetcore.

The message that the Logstash Toolbox sends to Logstash has the following layouyt :

{
    "Header": {
        "Correlation": {
            "CorrelationId":"f0b208e1-7fc4-4585-8419-a089229978a6",
            "ApplicationId":"LogstashToolboxSample"
        },
        "TimeStamp":"2016-03-13T10:51:29.5352657+01:00",
        "Source": {
            "ApplicationId":"LogstashToolboxSample",
            "ComponentId":"Microsoft.AspNet.Hosting.Internal.HostingEngine"
        },
        "IPAddress":"158.149.0.167",
        "ProcessId":"15720",
        "ThreadId":"7",
        "Index":"LogstashToolboxSample",
        "VersionNumber":"1"
    },
    "Body": {
        "User": {
            "UserId":"userid",
            "IPAddress":"158.149.0.167"
        },
        "Level":2,
        "Content":"This is an information log message.",
        "VersionNumber":"1"
    }
}

The Content field is the message that is passed to the Log methods of the ASP.NET Core Logger. If you need more structure in this message, you can send a JSON string.

The samples directory contains an API project that can be used as a guideline.