Elastic.CommonSchema.NLog

Elastic Common Schema NLog Layout

This Layout implementation formats an NLog event into a JSON representation that adheres to the Elastic Common Schema specification.

Packages

The .NET assemblies are published to NuGet under the package name Elastic.CommonSchema.NLog

How to use from API

var config = new LoggingConfiguration();
var consoleTarget = new ConsoleTarget("console") { Layout = new EcsLayout() };  // Use the ECS layout.
config.AddRule(LogLevel.Debug, LogLevel.Fatal, consoleTarget);
LogManager.Configuration = config;
var logger = LogManager.GetCurrentClassLogger();

The sample above uses EcsLayout with the NLog console target, but you are free to use any target of your choice, perhaps consider the NLog FileTarget and Elastic Filebeat for durable and reliable ingestion.

How to use from NLog.config

<nlog>
  <extensions>
    <add assembly="Elastic.CommonSchema.NLog"/>
  </extensions>
  <targets>
    <target name="console" xsi:type="console">
      <layout xsi:type="EcsLayout">
        <metadata name="MyProperty" layout="MyPropertyValue" /> <!-- repeated, optional -->
        <label name="MyLabel" layout="MyLabelValue" />          <!-- repeated, optional -->
        <tag layout="MyTagValue" />                             <!-- repeated, optional -->
      </layout>
    </target>
  </targets>
  <rules>
    <logger name="*" minLevel="Debug" writeTo="Console" />
  </rules>
</nlog>

EcsLayout Parameter Options

• Metadata Options

  • IncludeEventProperties - Include LogEvent properties as metadata. Default: true
  • IncludeScopeProperties - Include NLog Scope Context Properties as metadata. Default: false
  • ExcludeProperties - Comma separated string with names which properties to exclude.

• Event Options

  • EventAction -
  • EventCategory -
  • EventId -
  • EventKind -
  • EventSeverity -

• Agent Options

  • AgentId -
  • AgentName -
  • AgentType -
  • AgentVersion -

• Process Options

  • ProcessExecutable - Default: ${processname:FullName=true}
  • ProcessId - Default: ${processid}
  • ProcessName - Default: ${processname:FullName=false}
  • ProcessTitle - Default: ${processinfo:MainWindowTitle}
  • ProcessThreadId - Default: ${threadid}
  • ProcessThreadName -

• Server Options

  • ServerAddress -
  • ServerIp -
  • ServerUser - Default: ${environment-user}

• Host Options

  • HostId -
  • HostIp -
  • HostName - Default: ${machinename}

• Log Origin Options

  • LogOriginCallSiteMethod - Default: ${exception:format=method}
  • LogOriginCallSiteFile - Default: ${exception:format=source}
  • LogOriginCallSiteLine -

• Http Options

  • HttpRequestId - Default: ${aspnet-trace-identifier}
  • HttpRequestMethod - Default: ${aspnet-request-method}
  • HttpRequestBytes - Default: ${aspnet-request-contentlength}
  • HttpRequestReferrer - Default: ${aspnet-request-referrer}
  • HttpResponseStatusCode - Default: ${aspnet-response-statuscode}

• Url Options

  • UrlScheme - Default: ${aspnet-request-url:IncludeScheme=true:IncludeHost=false:IncludePath=false}
  • UrlDomain - Default: ${aspnet-request-url:IncludeScheme=false:IncludeHost=true:IncludePath=false}
  • UrlPath - Default: ${aspnet-request-url:IncludeScheme=false:IncludeHost=false:IncludePath=true}
  • UrlPort - Default: ${aspnet-request-url:IncludeScheme=false:IncludeHost=false:IncludePath=false:IncludePort=true}
  • UrlQuery - Default: ${aspnet-request-url:IncludeScheme=false:IncludeHost=false:IncludePath=false:IncludeQueryString=true}
  • UrlUserName - Default: ${aspnet-user-identity}

• Trace Options

  • ApmTraceId - Default: System.Diagnostics.Activity.Current.TraceId
  • ApmSpanId - Default: System.Diagnostics.Activity.Current.SpanId

• Transaction Options

  • ApmTransactionId - Default: ${ElasticApmTransactionId}

ECS Aware Message Templates

Additionally any valid ECS log template properties that is available under LogTemplateProperties.* e.g LogTemplateProperties.TraceId is supported and will directly set the appropriate ECS fields.

logger.Info("The time is {TraceId}", "my-trace-id");

Will override trace.id on the resulting ECS json document.

Example output from EcsLayout

An example of the output is given below:

{
  "@timestamp": "2020-02-20T16:07:06.7109766+11:00",
  "log.level": "Info",
  "message": "Info \"X\" 2.2",
  "ecs.version": "9.0.0",
  "log": {
    "logger": "Elastic.CommonSchema.NLog.Tests.LogTestsBase"
  },
  "labels": {
    "ValueX": "X"
  },
  "agent": {
    "type": "Elastic.CommonSchema.NLog",
    "version": "1.6.0"
  },
  "event": {
    "created": "2020-02-20T16:07:06.7109766+11:00",
    "severity": 6,
    "timezone": "Romance Standard Time"
  },
  "host": {
    "ip": [ "127.0.0.1" ],
    "name": "LOCALHOST"
  },
  "process": {
    "executable": "C:\\Program Files\\dotnet\\dotnet.exe",
    "name": "dotnet",
    "pid": 17592,
    "thread.id": 17592,
    "title": "15.0.0.0"
  },
  "server": { "user": { "name": "MyUser" } },
  "service": {
    "name": "Elastic.CommonSchema",
    "type": "dotnet",
    "version": "1.6.0"
  },
  "metadata": {
    "SomeY": 2.2
  },
  "MessageTemplate": "Info {ValueX} {SomeY} {NotX}"
}

Copyright and License

This software is Copyright (c) 2014-2020 by Elasticsearch BV.

This is free software, licensed under: The Apache License Version 2.0.