Skip to content
Rolf Kristensen edited this page Sep 4, 2024 · 31 revisions

A specialized layout that renders CSV-formatted events.

Platforms Supported: All

Configuration Syntax

<targets>
  <target>
    <layout xsi:type="CsvLayout">
      <!-- CSV Columns -->
      <column layout="Layout" name="String"/> <!-- repeated -->

      <!-- CSV Options -->
      <quoting>Enum</quoting>
      <quoteChar>String</quoteChar>
      <withHeader>Boolean</withHeader>
      <customColumnDelimiter>String</customColumnDelimiter>
      <delimiter>Enum</delimiter>
    </layout>
  </target>
</targets>

Parameters

Columns

Array-collection where each item is represented by <column /> element with the following attributes:

  • name - Name of the column (Becomes part of the Header for the CSV-output)
  • layout - Layout for the column value. Layout Required.
  • quoting - Column specific override of the default column quoting (Ex. for column with multiline exception-output)

    Introduced with NLog 4.6

CSV Options

  • quoting - Default Quoting mode for columns to ensure valid CSV output. Default: Auto
    Possible values:

    • Auto - Only add quotes when detecting value contains the quote symbol, the separator or newlines (Slow)
    • All - Add quotes for all values. Useful for data known to be multiline such as Exception-ToString (Fast)
    • Nothing - Quote nothing, but make sure not to include newlines or quote-delimiter in output (Very Fast)
  • quoteChar - Quote Character. Default: "

  • withHeader - Indicates whether CSV should include header. Boolean. Default true

  • customColumnDelimiter - Custom column delimiter value (valid when delimiter is set to Custom).

  • delimiter - Column delimiter. Default: Auto
    Possible values:

    • Auto - Automatically detect from regional settings.
    • Comma - Comma , character (ASCII 44).
    • Custom - Custom string, specified by the CustomColumnDelimiter.
    • Pipe - Pipe | character (ASCII 124).
    • Semicolon - Semicolon ; character (ASCII 59).
    • Space - Space character (ASCII 32).
    • Tab - Tab character (ASCII 9).

Example

<target xsi:type="File" name="csvFileExample" fileName="./CsvLogExample.csv">
    <layout xsi:type="CsvLayout" delimiter="Tab" withHeader="false">
        <column name="time" layout="${longdate}" />
        <column name="level" layout="${level:upperCase=true}"/>
        <column name="message" layout="${message}" />
        <column name="exception" layout="${exception:format=ToString}"/>
        <column name="property1" layout="${event-properties:property1}"/>
    </layout>
</target>

Performance

NLog 4.6 introduces some performance optimizations for the CsvLayout. Reducing memory allocation by better buffer reuse. It is also possible to reduce the overhead of the automatic quoting logic for individual columns:

This is example will greatly reduce the overhead of default Auto-quoting, because of the override for the individual columns:

    <layout xsi:type="CsvLayout" delimiter="Tab" withHeader="false">
        <column name="time" layout="${longdate}" quoting="Nothing" />
        <column name="level" layout="${level:upperCase=true}" quoting="Nothing"/>
        <column name="message" layout="${message}" quoting="All" />
        <column name="exception" layout="${exception:format=ToString}" quoting="All"/>
        <column name="property1" layout="${event-properties:property1}"/>
    </layout>

From code

Layout = new CsvLayout()
{
   Columns =
   {
      new CsvColumn("time", "${longdate}"),
      new CsvColumn("level", "${level:upperCase=true}"),
      new CsvColumn("message", "${message}"),
      new CsvColumn("exception", "${exception:format=ToString}"),
      new CsvColumn("property1", "${event-properties:property1}"),
   }
}
Clone this wiki locally