Configuration

Logger configuration

Configuration approaches

There's 2 way to configure logger:

• from App.config,
• from source code.

App.config

First of all you should put the logger configuration section to your App.config (or Web.config). Standard name for this section is 'LoggerConfigurationSection'. The section can also be placed inside any section group you want. To enable IntelliSense you can add XSD schema to you project (as file or from NuGet packet).

Sample App.config:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="LoggerConfigurationSection" type="Qoollo.Logger.Configuration.LoggerConfigurationSectionConfigClass, Qoollo.Logger" allowExeDefinition="MachineToApplication" requirePermission="false" />
  </configSections>
  
  <LoggerConfigurationSection xmlns="Qoollo.Logger.Configuration.LoggerConfigurationSection_NS">
    <logger logLevel="TRACE">
      <asyncQueueWrapper maxQueueSize="4096">
        <groupWrapper>
          <emptyWriter />
          
          <consoleWriter logLevel="INFO"
            template="{DateTime}. {Level}. \n At {StackSource}.{Class}::{Method}.\n Message: {Message}. {Exception, prefix = '\n Exception: ', valueOnNull=''}\n\n"/>
          
          <fileWriter logLevel="DEBUG" fileNameTemplate="logs/{DateTime, format = yyyy-MM-dd}.log"
            template="{DateTime}. {Level}. \n At {StackSource}.{Class}::{Method}.\n Message: {Message}. {Exception, prefix = '\n Exception: ', valueOnNull=''}\n\n"/>
          
          <databaseWriter logLevel="INFO" connectionString="Data Source = (local); Database = LogsDb; Integrated Security=SSPI;" storedProcedureName="[dbo].[LogInsert]" />
          
          <asyncReliableQueueWrapper folderForTemporaryStore="net_rel">
            <networkWriter logLevel="DEBUG" serverAddress="127.0.0.1" />
          </asyncReliableQueueWrapper>
          
          <asyncReliableQueueWrapper folderForTemporaryStore="pipe_rel">
            <pipeWriter logLevel="DEBUG" pipeName="LogPipe" />
          </asyncReliableQueueWrapper>

          <asyncReliableQueueWrapper folderForTemporaryStore="logstash_rel">
            <logstashWriter logLevel="DEBUG" serverAddress="127.0.0.1" port="5001" />
          </asyncReliableQueueWrapper>

          <patternMatchingWrapper pattern="{Level}">
            <match value="WARN">
              <fileWriter fileNameTemplate="logs/WarnOnly_{DateTime, format = yyyy-MM-dd}.log"/>
            </match>
            <default>
              <fileWriter fileNameTemplate="logs/PatternDefault_{DateTime, format = yyyy-MM-dd}.log"/>
            </default>
          </patternMatchingWrapper>
          
        </groupWrapper>
      </asyncQueueWrapper>
    </logger>
  </LoggerConfigurationSection>
  
</configuration>

To create logger from App.config you simply call 'Qoollo.Logger.CreateLoggerFromAppConfig(...)'.

Source code

To configure logger from source you can use configuration classes from namespace 'Qoollo.Logger.Configuration'. The root configuration class is 'LoggerConfiguration'. You can add any child writers and wrappers to this main configuration object.

To create logger from source code you simply call 'Qoollo.Logger.CreateLogger(...)'.

Configuration parameters

Let's look at configuration items and their parameters:

• Root logger configuration (LoggerConfiguration):
  • Level - minimal logging level for messages (supported levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL);
  • IsEnabled - is writing logs to targets enabled;
  • IsStackTraceEnabled - allow to extract additional information (Assembly and Type) from StackTrace;
  • Writer - single child writer (any real writer or wrapper);
• Wrappers:
  • Async queue wrapper - write log messages in separate thread (queue is used to transfer messages to that thread):
    • MaxQueueSize - maximum size of queue;
    • IsDiscardExcess - if queue is overflowed the new messages will be dropped (true) or main thread will be blocked (false);
    • InnerWriter - child writer (any real writer or wrapper);
  • Async reliable queue wrapper - async logs writing with temporary storage of logs on disk to prevent losses:
    • MaxQueueSize - maximum size of queue;
    • IsDiscardExcess - if queue is overflowed the new messages will be dropped (true) or main thread will be blocked (false);
    • FolderForTemporaryStore - folder for files on disk;
    • MaxFileSize - maximum size of single temporary file;
    • InnerWriter - single child writer (any real writer or wrapper);
  • Group wrapper - allow to group writers:
    • InnerWriters - any number of child writers and wrappers;
  • Pattern matching wrapper - allows to route log messages between targets by simple pattern matching:
    • Pattern - template string for pattern;
    • MatchWriters - dictionary with matching string as key and log target (any wrapper or writer) as value;
    • DefaultWriter - writer/wrapper that is used when matching not found;
• Writers:
  • Empty writer - fake writer (not write to any storage);
  • Console writer - write log messages to standard Console:
    • Level - minimal level of logs writed by this writer;
    • Template - log message pattern string;
  • File writer - write logs to text files:
    • Level - minimal level of logs writed by this writer;
    • Template - log message pattern string;
    • FileNameTemplate - pattern string for file names (each log message can be written to separate log file according to FileNameTemplate);
    • IsNeedFileRotate - enable file rotation;
    • Encoding - encoding of text file;
  • Pipe writer - send logs to Pipe server:
    • Level - minimal level of logs writed by this writer;
    • ServerName - address of server;
    • PipeName - unique name of pipe channel;
  • Network writer - send logs to network WCF service:
    • Level - minimal level of logs writed by this writer;
    • ServerAddress - address of server (ip or host name);
    • Port - service TCP port;
  • Database writer - write logs to MS SQL Server database:
    • Level - minimal level of logs writed by this writer;
    • ConnectionString - connection string to your database;
    • StoredProcedureName - name of stored procedure that adds log to your tables.
  • Logstash writer - send logs to Logstash through TCP with JSON encoding:
    • Level - minimal level of logs writed by this writer;
    • ServerAddress - address of Logstash server (ip or host name);
    • Port - logstash server TCP port;

Log message pattern string format

Sample pattern:

"{DateTime}. {Level}. \n At {StackSource}.{Class}::{Method}.\n Message: {Message}. {Exception, prefix = '\n Exception: ', valueOnNull=''}\n\n"

As you can see it supports:

• Plain text;
• {Predefined substitution tokens};
• \n - new line.

The list of substitution tokens:

• {Level} - importance level of this message;
• {DateTime, format = yyyy} - date and time when log message was created (supports format string);
• {Message} - log message;
• {Exception} - description of exception if it was passed with this log message;
• {Method} - method from which the log message was created;
• {Class} - class from which the log message was created;
• {Namespace} - namespace where the {Class} is placed;
• {Assembly} - assembly from which the log message was created;
• {ProcessId} - PID of process created this log message;
• {ProcessName} - name of process created this log message;
• {MachineName} - name of the machine form which current log message was received;
• {StackSource} - names of every stacked logger combined to single string;
• {Context} - special information in log message;
• {MachineIp} - ip address of the machine form which current log message was received;
• {StackSourceHead} - first element of StackSource;
• {StackSourceTail} - last element of StackSource.

All tokens support prefixes, suffixes and special value for Null:

{Token, prefix = '', suffix = '', valueOnNull = ''}