uship/uship.logging

Fluent log4net logging library

uShip.Logging

Opinionated fluent library for logging to Logstash and Graphite based on log4net.

Basic Usage

Logstash

var logger = Logger.GetInstance();

// log plain message with severity WARN
logger
.Message("This is a warning.")
.Warn()
.Write();

// log exception with custom data
var exception = new Exception();
logger
.Exception(exception)
.Data("userId", 1027)
.Write();

Graphite

// Implement IGraphiteKey interface
public class GraphiteKey : IGraphiteKey
{
  public static GraphiteKey AccountCreated = new GraphiteKey("AccountCreated");

  private readonly string _key;

  private GraphiteKey(string key)
  {
      _key = key;
  }

  public string Key { get { return _key; } }
}


var logger = Logger.GetInstance();

// count
logger.Write(GraphiteKey.AccountCreated, null /*Optional SubKey*/);

// timing
logger.Write(GraphiteKey.AccountCreated, null /*Optional SubKey*/, 100 /*milliseconds*/)

Configuration Settings

Custom Configuration Section

uShip.Logging exposes the following configuration settings via a custom configuration section.

Setting	Description
graphiteMetricPath	The prefix of all metrics that are logged to graphite
minimalDataLogMessage	The message to log when calling .WriteMinimalDataLog
jsonReplacements	The names of JSON fields that should be sanitized and not logged such as passwords and credit card numbers
urlFormEncodedReplacements	The names of form fields that should sanitized and not logged such as passwords and credit card numbers
regexReplacements	Regex patterns for fields that should be sanitized and not logged that do not fit into the JSON or URL encoded category above
targetStackTraces	Stacktraces that you designate as the root causes of any exception. These values are usually the root namespaces of your project

log4net configuration

In addition to the custom configuration section, uShip.Logging depends on the following loggers to be configured

Logger	Purpose
Logstash	All exceptions and messages written via .Exception and .Message will be sent to this logger
Graphite	All graphite metrics logged will be sent to this logger
Minimal	All messages written via WriteMinimalDataLog will be sent to this logger

The following appenders are available in addition to the appenders provided by log4net

Appender	Purpose	Relevant Settings
uShip.Logging.Appender.LogstashAppender	Writes messages to Logstash	remoteAddress, remotePort
uShip.Logging.Appender.ApiErrorLogAppender	Writes messages to an API as a webhook	apiUrl
uShip.Logging.Appender.FileLogAppender	Writes messages to disk	baseDirectory

Example Configuration

See an example App.config here.

Contributing

See CONTRIBUTING.md

uship.logging's Issues

Minimal Logger invalid JSON breaks future messages

To reproduce with a fresh Elastic Search index:

var logger = Logger.GetInstance();

logger.WriteMinimalDataLog("invalid json data");

const string json = "{\"property\":\"value\"}";
logger.WriteMinimalDataLog(json, Severity.Info);

The first message makes it into the index. The type of "properties.data" is now a string because of the JSON deserialization fallback in MinimalLogDataBuilder.cs. When the second message is sent, it is silently dropped since it does not match the type (since it converted into an object since it is valid JSON).

Proposed solution:
Wrap all invalid JSON in a object as shown below

const string json = "{\"message\":\"invalid json data\"}";

Doing .Data() over a "logged already/logged for free" property makes the logger fail in a silent fashion.

Doing something like...

_logger.Message('mah message').Data('RequestBody', requestBody).Info().Write();

Causes the logger to log an INFO message with "Error Building Log Properties".

No exception is thrown/bubbled up, so the programmer is pretty much left at a loss / assumes it never may be logged.

Possible fixes/Proposals:

Just allowing users to override these required properties/already logged properties could be bad (per the advice of @digitalpacman ) due to possible differences in data types/etc, that might cause true silent failure in the logger.

we could change the Error Building Log Properties to ERROR, but apparently this bugs people (personally, I think it should. Let's fix our logs instead of just ignoring them...)

@digitalpacman proposes the .Data() method utilize a prefix on custom fields.