Define log targets

A log target is the location log messages are written to including file name and log message layout specification. NLog supports over 100 different targets. This documentation is limited to the adaptation of the Alfabet NLog example configuration files to activate the default targets to write log messages to files, console window, Splunk® and Microsoft Windows® Event Log. Consult the NLog documentation to include other targets..

In the example file, parts of the target definitions is based on variables and layout renderers.

To alter the targets, you can change the target itself or the variable value. You can also create new variables or new targets with different names and values. Each variable must have a unique name.

• Target: file

  By default, log messages are written to the specified log file location in a predefined format. To activate logging to file, it is sufficient to specify the log file location. All other configurations are optional.

  Specify the log file location.

  In the line:

  • <variable name="var-logdir" value="../logs/" />

  change the XML attribute value to the absolute or relative path to the target log location on the local file system.

  • Folders are separated with a slash, and the drive is specified with a single slash behind the colon. This is deviating from the path as copied from a Microsoft Windows® file explorer.
  • The specification must end with a slash.

  Optionally change the file name suffix variable.

  The file name suffix is used in the example target definition as last part of the file name.

  Optionally, re-define the file name suffix in the line:

  • <variable name="var-file-suffix" value="-${gdc:appVersionFlat:whenEmpty=}-${gdc:alfabet-alias-name:whenEmpty=Startup}" />

  By default, the last part of the file name consists of the Alfabet release version information and the name of the alias configuration used to start the component. If the message is a start-up message prior to login with a specific alias, the alias name is substituted with the string Startup. Consult the NLog documentation for an overview of layout rendering options that can be used alternatively.

  Optionally change the log layout variable.

  1. Optionally re-define the log message content in the line:
     • <variable name="var-logLayout" value="${logger:shortName=true}|${level}|${date:format=MM-dd-yy HH\:mm\:ss.fffffff zzz}|${scope-property:alfabet-traceid:whenEmpty=${scope-property:RequestId}}|${event-properties:loggerclass}|${message} ${exception:format=tostring}" />

     The format of the messages in the variable includes standard NLog layout renderers:

     • ${logger:shortName=true}: The name of the logger in the rule for which the message is written. The logger name consists of a prefix and a name part separated with a dot. Only the name part is included in the log message. The name part informs about the Alfabet functionality that is logged.
     • ${level}: The log level of the log message.
     • ${date:format=MM-dd-yy HH\:mm\:ss.fffffff zzz} The date and time at which the log message is written. The format is defined in the layout specification. You can change the layout using .NET date and time formats.
     • ${scope-property:alfabet-traceid:whenEmpty=${scope-property:RequestId}}: The trace ID of the request, if provided by the system.
     • ${event-properties:loggerclass}: More detailed information about which functionality has been logged.
     • ${message}: The log message.
     • ${exception:format=tostring}: Includes the inner exception of errors to the log output.

     You can change the format of the log message by re-ordering the information or providing other layout renderers. Consult the NLog documentation for an overview of layout rendering options..

  Optionally change the target definition

  1. Optionally change the definition of the target:
     • <target xsi:type="File" name="file-all" fileName="${var:var-logdir}nlog-${iis-site-name:whenEmpty=${processname:fullName=false}}-${shortdate}${var:var-file-suffix}.log" layout="${var-logLayout}" />

     The target definition includes:

     The following description is limited to an explanation of the settings in the example file. For additional settings or documentation of other allowed settings of the XML attributes used in the example, see the NLog documentation for logging to file.

     • name: A unique name used in logging rules to specify the target.
     • fileName: The file the log information is written to. This includes the path specification. In the example the file name starts with the log file location variable described above. The file name includes the name of the Alfabet component, the date the log file was written, and the Alfabet release version and the server alias name the component was started with. A separate log file is created each time one of these name parts changes. With the example configuration, a separate log file is written for each started Alfabet component each day. If you remove parts of the file name specification, the log behavior changes. For example, if you do not have the date in the file name, the same log file will be used regardless of the date.

       When you are using file compression, the file extension must be .gz instead of .log.

     • layout: Defines the layout of the log messages. The example setting uses the layout variable described above.
     • createDirs: If set to true, directories in file path specifications are created if they do not exist already.

     The following definitions are only relevant if you select the example files including archiving of logfiles, which means writing log information directly in ZIP compressed format.

     • xsi:type="GZipFile": Specifies that files shall be written to ZIP files.
     • archiveOldFileOnStartup: If set to true , an existing log file is archived each time an Alfabet component is started. Archiving requires that this attribute is set to true.
     • keepFileOpen: If set to false , is closed after each writing of a log message and opened again. To enhance performance, it should be set to true, which is the default.
     • compressionLevel: The compression level can be Optimal to optimize compression for resulting small file sizes, Fastest to optimize compression speed, or NoCompression to disable compression.

  Logging to file via NLog is very flexible. You can define additional variables to specify multiple target directories, file names, file name parts, and layouts. You can then define multiple targets each defining logging to files in different output locations and with a different structure. When defining the rules, you can define different rules for each output to log different log levels to different folders, or define identical logging in parallel to multiple targets. Consult the NLog documentation for an overview of the configuration options for logging to file.

• Target: console window

  The writing to console is specified in the lifetimeConsole log target:

  • <target xsi:type="Console" name="lifetimeConsole" layout="${MicrosoftConsoleLayout}" />

  Writing of system messages to the console window is activated by default and does not need any configuration. The layout refers to a standard NLog layout part of the NLog standard..

  To write log messages generated for other parts of the Alfabet functionality, add the lifetimeConsole target either as only value to the XML attribute writeTo of the XML child elements logger of the XML element rules, or add it comma separated to already specified targets. Do this for all content that shall be logged in the Microsoft Windows event log.

  • <logger name="alfabetlogger.UserLogon" minlevel="${var:var-level}" writeTo="lifetimeConsole,file-all" final="true" />

  • For information about the functionality logged for each rule, consult the documentation of rule configuration.
• Target: event log

  You must enable event logging in the NLog configuration file and register Alfabet with the Microsoft Windows® Event Log.

  Activate the event log target in the NLog example files.

  1. The event log target specification is commented out. Cut the target definition from the comment and paste it beneath the comment:
     • <!--Windows event log target
     • -->
     • <target xsi:type="EventLog" name="windowsLog" source ="${var:alfabet-event-source}" eventId="${var:alfabet-event-id}" log="Alfabet" layout="${var-logLayout}" />
  2. In the XML child elements logger of the XML element rules add the windowsLog target either as only value to the XML attribute writeTo, or add it comma separated to other targets. Do this for all content that shall be logged in the Microsoft Windows event log.
     • <logger name="alfabetlogger.UserLogon" minlevel="${var:var-level}" writeTo="windowsLog,file-all" final="true" />
     • For information about the functionality logged for each rule, consult the documentation of rule configuration
     • ADIF log messages cannot be written in the Microsoft Windows event log.
  3. Optionally change the value of the following variable to alter the name that is used as Source in the Windows Event Log.
     • <variable name="alfabet-event-source" value="Alfabet" />
  4. An event ID will be written into all entries in the Windows Event Log. The event ID is calculated from the event base ID defined in the following variable plus the logging level number. The logging level number is 2 for Error , 4 for Warning , 8 for Information and 16 for Debug .The event base ID must be an integer between 30000 and 65535. You can change the value of the alfabet-event-id variable to set it:
     • <variable name="alfabet-event-id" value="5000" />
  5. Optionally re-define the log message content in the line:
     • <variable name="var-logLayout" value="${logger:shortName=true}|${level}|${date:format=MM-dd-yy HH\:mm\:ss.fffffff zzz}|${scope-property:alfabet-traceid:whenEmpty=${scope-property:RequestId}}|${event-properties:loggerclass}|${message} ${exception:format=tostring}" />

     The layout definition is defined in a variable that is also used for logging to file.

     The format of the messages in the variable includes standard NLog layout renderers:

     • ${logger:shortName=true}: The name of the logger in the rule for which the message is written. The logger name consists of a prefix and a name part separated with a dot. Only the name part is included in the log message. The name part informs about the Alfabet functionality that is logged.
     • ${level}: The log level of the log message.
     • ${date:format=MM-dd-yy HH\:mm\:ss.fffffff zzz} The date and time at which the log message is written. The format is defined in the layout specification. You can change the layout using .NET date and time formats.
     • ${scope-property:alfabet-traceid:whenEmpty=${scope-property:RequestId}}: The trace ID of the request, if provided by the system.
     • ${event-properties:loggerclass}: More detailed information about which functionality has been logged.
     • ${message}: The log message.
     • ${exception:format=tostring}: Includes the inner exception of errors to the log output.

     You can change the format of the log message by re-ordering the information or providing other layout renderers. Consult the NLog documentation for an overview of layout rendering options..

  Register Alfabet with the Microsoft Windows Event Log.

  1. Start theAlfabetWeb6.exe executable from the root directory of the Alfabet Web Application with administrator permissions.
  2. Open the Windows Event Log and check whether the registration is logged for the specified Event Source Name.

  The registration of the Event Logger must be re-executed after each change to the configuration described above.

  The registration of the Event Logger can alternatively be done via the command line tool AlfaAdministratorConsole.exe run as administrator with the command

  • AlfaAdministratorConsole.exe -msalias AliasName -enablewindowseventlog
• Target: Splunk

  Splunk Enterprise® is installed in your cloud environment and an HTTP event collector is set up for Splunk.

  In the example configuration file provided for cloud installations with the Alfabet installation, writing to Splunk is specified in the Splunk log target:

  • <target name="Splunk"
  • xsi:type="SplunkHttpEventCollector"
  • serverUrl="${environment:ALFABET_SPLUNK_ENDPOINT:cached=true}"
  • token="${environment:ALFABET_SPLUNK_TOKEN:cached=true}"
  • channel="${environment:ALFABET_SPLUNK_CHANNEL:cached=true}"
  • source="${logger}"
  • sourceType="_json"
  • index=""
  • retriesOnError="0"
  • batchSizeBytes="0"
  • batchSizeCount="0"
  • includeEventProperties="true"
  • includePositionalParameters="false"
  • includeMdlc="false"
  • maxConnectionsPerServer="10"
  • ignoreSslErrors="false"
  • useProxy="false"
  • proxyUrl="http://proxy:8888"
  • proxyUser="username"
  • proxyPassword="secret" >

  Access to Splunk is defined via environment variables. How to set environment variables depend on your cloud provider. The following environment variables must be defined:

  • ALFABET_SPLUNK_ENDPOINT: The server URL of the Splunk HTTP event collector.
  • ALFABET_SPLUNK_TOKEN: The access token for authentication to the Splunk HTTP event collector.
  • ALFABET_SPLUNK_CHANNEL: The data channel of the Splunk HTTP event collector.

  Optionally send data over a proxy server.

  to send data via a proxy, set the XML attribute useProxy to true and define the proxy URL and access parameters in the XML attributes ProxyUrl , proxyUser , and proxyPassword.

  Optionally change the parameters for sending the data.

  The connection parameters are already set in the example configuration. If you encounter issues or want to adapt the default behavior to your demands, consult the NLog documentation for sending data to Splunk for a complete overview of available options.