Serilog.Sinks.InsightIdr 1.1.1

<h1 align="center">Serilog Sinks: insightIDR (InsightOps)</h1>

<div align="center"> A sink for Serilog that writes events to insightIDR (InsightOps) by Rapid7. </div>

<br />

A Serilog sink that writes log events to insightIDR (InsightOps) via TCP or HTTPS.

This sink is also configured for the most common scenario's - an easy way to get started for most people. As such some advanced features are (by design) left out of this sink.

<hr/>

Table of Contents

• Getting started (simple, text-based logging)
• Advanced: loading insightIDR settings via a configuration file
• Structured Logging
• Advanced Structured Logging: loading insightIDR settings via a configuration file

<hr/>

Getting started (simple, text-based logging)

To use the console sink, first install the NuGet package:

Install-Package Serilog.Sinks.InsightIDR

Next, define you insightIDR (InsightOps) account settings:

var settings = new InsightIdrSinkSettings
{
    Region = "<to fill in by you>", // au, eu, jp or us
    Token = "<to fill in by you>", // Guid, taken from your insightIDR (InsightOps) log account
    UseSsl = false, // or True for sending via HTTPS. Make sure you can handle TLS1.2 (or newer)
    Debug = false // or True to see low level R7 Insight ops debug messages in the console (this is helpful actually!)

    // Optional settings people rarely use. You can ignore these, unless you know what you're doing:
    // (and these are the defaults)
    IsUsingDataHub = false, // Set to true to use custom DataHub instance instead of Logentries service.
    DataHubAddress = null, // DataHub server address
    DataHubPort = 0, // DataHub server port
    LogHostname = null, // Set to true to send HostName alongside with the log message
    HostName = null, // User-defined host name. If empty the library will try to obtain it automatically
    LogID = null // Log ID
};

Then enable the sink using WriteTo.InsightIDR():

Log.Logger = new LoggerConfiguration()
    .WriteTo.InsightIDR(settings)
    .CreateLogger();

And now log something. Here's an example of some semantic logging:

var position = new { Latitude = 25, Longitude = 134 };
var elapsedMs = 34;
log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);

Log events will look like this at insightIDR (InsightOps):

13 Nov 2019 00:59:47.645 Processed { Latitude: 25, Longitude: 134 } in 034 ms.

Log view

Table view

More advanced getting started (loading settings via configuration file)

Probably the best way to load the configuration settings is via your appSettings.config file(s).

Here's a lovely example:

1. ⚠ Make sure you install the Serilog.Sinks.InsightIDR nuget package, otherwise the Serilog won't be able to load the configuration settings.
2. Add the relevant section to your appSettings.config file(s)
   • Using section
   • WriteTo section
   • Name and Args key/values.

<details> <summary>Example appSettings.json code (copy/paste friendly)</summary>

{
    "Serilog": {
        "Using": [ "Serilog.Sinks.InsightIDR" ],
        "MinimumLevel": {
            "Default": "Debug",
            "Override": {
                "System": "Debug",
                "Microsoft": "Debug"
            }
        },
        "WriteTo": [
            {
                "Name": "Console"
            },
            {
                "Name": "InsightOps",
                "Args": {
                    "Token": "<to be manually set>",
                    "Region": "eu",
                    "UseSsl": "true"
                }
            }
        ]
    }
}

</details>

Structured Logging

To get structured logging with InsightIDR (insightOps), we will need to send the data (over the wire) as JSON.
To do that, we need to do the following:

Log.Logger = new LoggerConfiguration()
    // 🤘🏻 Notice how we've defined the JSON formatter! 🤘🏻
    .WriteTo.InsightIDR(settings, new RenderedCompactJsonFormatter())
    .CreateLogger();

and this will now send the data up to insightOps as Structed Logging:

Log view

Table View

For the record, there are the types of JSON data formats you can use:

• JsonFormatter()
• CompactJsonFormatter() [This has no @m "message" property. Only the @mt "message template"]
• RenderedCompactJsonFormatter() [This has an @m message property, plus other values]

Structured Logging (Advanced) : Settings via configuration file

Here's an example section of loading the settings via the appSettings.config file:

Note the Formatter arg.

{
    "Serilog": {
        "Using": [ "Serilog.Sinks.InsightIDR" ],
        "MinimumLevel": {
            "Default": "Debug",
            "Override": {
                "System": "Debug",
                "Microsoft": "Debug"
            }
        },
        "WriteTo": [
            {
                "Name": "Console"
            },
            {
                "Name": "InsightIDR",
                "Args": {
                    "Token": "<to be manually set>",
                    "Region": "eu",
                    "UseSsl": "true",
                    "Formatter": "Serilog.Formatting.Compact.RenderedCompactJsonFormatter, Serilog.Formatting.Compact"
                }
            }
        ]
    }
}

This library provides a sink for InsightIdr for Serilog. Serilog is copyright © 2019 Serilog Contributors - Provided under the Apache License, Version 2.0. For more detailed explanation of these, this is a blog post from the Serilog author. See also: Serilog Documentation