Elastic.NLog.Targets 8.12.1

Elastic.NLog.Targets

A NLog target that writes logs directly to Elasticsearch or Elastic Cloud using the Elastic Common Schema.

Packages

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

How to use from API

var config = new LoggingConfiguration();
var elasticTarget = new ElasticsearchTarget("elastic") { Layout = new EcsLayout(), NodesUri = "http://localhost:9200" };
config.AddRule(LogLevel.Debug, LogLevel.Fatal, elasticTarget);
LogManager.Configuration = config;
var logger = LogManager.GetCurrentClassLogger();

How to use from NLog.config

<nlog>
  <extensions>
    <add assembly="Elastic.CommonSchema.NLog"/>
    <add assembly="Elastic.NLog.Targets"/>
  </extensions>
  <targets>
    <target name="elastic" type="ElasticSearch" nodeUris="http://localhost:9200">
      <layout xsi:type="EcsLayout">
        <metadata name="MyProperty" layout="MyPropertyValue" /> 
        <label name="MyLabel" layout="MyLabelValue" />          
        <tag layout="MyTagValue" />                             
      </layout>
    </target>
  </targets>
  <rules>
    <logger name="*" minLevel="Debug" writeTo="elastic" />
  </rules>
</nlog>

ElasticsearchTarget Parameter Options

• Export Destination

  • NodePoolType - Connection pool type
    • SingleNode - Pool with single node or endpoint
    • Sniffing - Pool with Supports-Reseeding
    • Static - Pool without Supports-Reseeding
    • Sticky - Pool without Supports-Reseeding and stays on the first node.
    • StickySniffing - Pool with Supports-Reseeding and stays on the first node.
    • Cloud - Pool seeded with CloudId
  • NodeUris - URIs of the Elasticsearch nodes in the connection pool (comma delimited)
  • CloudId - When using NodePoolType = Cloud
  • BootstrapMethod - Whether to configure / bootstrap the destination, which requires user has management capabilities (None, Silent, Failure). Default = None

• Export Authentication

  • ApiKey - When using NodePoolType = Cloud and authentication via API key.
  • Username - When basic authenticating via username/password.
  • Password - When basic authenticating via username/password.

• Export Buffering

  • InboundBufferMaxSize - Max number of in flight instances that can be queued in memory. Default = 100000
  • OutboundBufferMaxSize - Max size to export. Default = 1000
  • OutboundBufferMaxLifetimeSeconds - Maximum lifetime of a buffer to export in seconds. Default = 5 sec
  • ExportMaxConcurrency - Max number of consumers allowed to poll for new events on the channel. Default = 1
  • ExportMaxRetries - Max number of times to retry an export. Default = 3

• Export DataStream

  • DataStreamType - Generic type describing the data. Default = 'logs'
  • DataStreamSet - Describes the data ingested and its structure. Default = 'dotnet'
  • DataStreamNamespace - User-configurable arbitrary grouping. Default = 'default'

• Export Index

  • IndexFormat - Format string for the Elastic search index (Ex. dotnet-{0:yyyy.MM.dd} or blank means disabled). Default = ''
  • IndexOffsetHours - Time offset to use for the index (Ex. 0 for UTC or blank means system local). Default = ''
  • IndexOperation - Operation header for each bulk operation (Auto, Index, Create). Default = Auto
  • IndexEventId - Optional override of the per document _id

Notice that export depends on in-memory queue, that is lost on application-crash / -exit. If higher gurantee of delivery is required, then consider using Elastic.CommonSchema.NLog together with NLog FileTarget and use filebeat to ship these logs.

Check out Elastic Agent & Fleet to simplify collecting logs and metrics on the edge.

ElasticsearchTarget Layout Configuration

NLog Layout allows one to configure NLog Target options from environment.

Lookup NodeUris from appsettings.json

  <target name="elastic" type="ElasticSearch" nodeUris="${configsetting:ConnectionStrings.ElasticSearch}">

Example appsettings.json on .NET Core:

  {
    "ConnectionStrings": {
      "ElasticSearch": "http://localhost:9200"
    }
  }

Lookup NodeUris from app.config

  <target name="elastic" type="ElasticSearch" nodeUris="${appsetting:ConnectionStrings.ElasticSearch}">

Example app.config on .NET Framework:

  <configuration>
    <connectionStrings>
      <add name="ElasticSearch" connectionString="http://localhost:9200"/>
    </connectionStrings>
  </configuration>

Lookup ConnectionString from environment-variable

  <target name="elastic" type="ElasticSearch" nodeUris="${environment:ELASTIC_SERVER_URL}">

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.