Serilog Sinks: InsightOps

A sink for Serilog that writes events to insightOps by Rapid7.

A Serilog sink that writes log events to 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.

---

Table of Contents

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

---

Getting started (simple, text based logging)

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

Install-Package Serilog.Sinks.InsightOps

Next, define you insightOps account settings:

var settings = new InsightOpsSinkSettings
{
    Region = "<to fill in by you>", // au, eu, jp or us
    Token = "<to fill in by you>", // Guid, taken from your 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.InsightOps():

Log.Logger = new LoggerConfiguration()
    .WriteTo.InsightOps(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 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.InsightOps 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.

Example appSettings.json code (copy/paste friendly)

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

Structured Logging

To get structured logging with 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.InsightOps(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.InsightOps" ],
        "MinimumLevel": {
            "Default": "Debug",
            "Override": {
                "System": "Debug",
                "Microsoft": "Debug"
            }
        },
        "WriteTo": [
            {
                "Name": "Console"
            },
            {
                "Name": "InsightOps",
                "Args": {
                    "Token": "<to be manually set>",
                    "Region": "au",
                    "UseSsl": "true",
                    "Formatter": "Serilog.Formatting.Compact.RenderedCompactJsonFormatter, Serilog.Formatting.Compact"
                }
            }
        ]
    }
}

For more detailed explanation of these, this is a blog post from the Serilog author.

---

Copyright © 2019 Serilog Contributors - Provided under the Apache License, Version 2.0.

See also: Serilog Documentation