Logging and tracing

In addition to traces for diagnostic purpose for which more information is available in the Troubleshooting book, PcVue also supports logging and tracing for the purpose of activity monitoring.
Activity monitoring is an important facet of deployment in production as it permits collecting events relevant to alerting and incident management, forensic investigations and post mortem analysis. Logging is typically used in conjunction with the SNMP Agent Add-on. It also plays a major role in auditing and regulatory compliance activities.

Logging and tracing features support the following type of targets:

• Storage of events in local log files and display with the Log monitor

• Windows event logs and display with the Windows event viewer

• Event sending for collection by external log aggregators, including Syslog servers

This topic describes how to customize the logging and tracing default settings and how to configure a Syslog target.

Default NLog settings

NLog is configured using an Xml file called NLog.Common.config found in the PcVue Bin folder. The configuration file provided by default as part of the installation defines two local targets, a file output called sv.log and the Windows event log. Show file

<?xml version="1.0" encoding="utf-8" ?>
<nlog
    xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- go to https://github.com/nlog/NLog/wiki/Configuration-file for more information -->

    <extensions>
        <add assemblyFile="NLogAI.dll"/>
    </extensions>

    <variable name="logFilesDir" value="${binDir}\Log Files" />
    <!--<variable name="logFilesDir" value="${binDir}\..\Logs" />-->
    <variable name="localDateTime" value="${date:format=yyyy/MM/ddTHH\:mm\:ss.fffzzz}" />
    <variable name="universalDateTime" value="${date:universalTime=true:
    format=yyyy/MM/ddTHH\:mm\:ss.fffZ}" />
    <variable name="sessionId" value="${processinfo:property=SessionId}" />
    <variable name="userName" value="${windows-identity:userName=true:domain=false}" />
    <variable name="userNameWithDomain" value="${windows-identity:userName=true:domain=true}" />
    <variable name="shortProcessName" value="${processname:fullName=false}" />
    <variable name="fullProcessName" value="${processname:fullName=true}" />

    <targets>
        <default-target-parameters xsi:type="File" encoding="utf-8" />
        <target
            name="sv.aiXml"
            xsi:type="File"
            fileName="${logFilesDir}\sv.log"
            archiveFileName="${logFilesDir}\sv-{#}.log"
            archiveAboveSize="52428800"
            archiveNumbering="Rolling"
            maxArchiveFiles="3"
            layout="${aiXmlEvent:indent=true:newLineOnAttributes=false:
            includeSourceInfo=false:includeCallSite=false:includeStackTrace=false}">
        </target>
    </targets>

    <targets>
        <target
            name="sv.EventLog"
            xsi:type="EventLog"
            log="Application"
            source="SV Applications"
            layout="[${logger}]${newline}${message}${newline}${newline}
            UserAccount: ${userNameWithDomain}${newline}SessionId: 
            ${sessionId}${newline}ProcessName: ${shortProcessName}
            ${newline}ProcessId: ${processid}${newline}ThreadId: ${threadid}">
        </target>
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="sv.aiXml" />
        <logger name="*" minlevel="Info" writeTo="sv.EventLog" />
    </rules>

    <include file="NLog.Syslog.config" ignoreErrors="true" />
    <include file="NLog.Custom.config" ignoreErrors="true" />

</nlog>

It is outside the scope of this help to provide a full description of every element, but the basic structure is as follows. The following are top level element with targets and rules mandatory in any configuration:

• targets - Defines the log targets / outputs

• rules - Defines which logger objects and log levels are active, and their output targets

• extensions – loads NLog extensions from a *.dll file

• include - Include external configuration file

• variable - Defines configuration variables and their values. For example
  <variable name="logFilesDir" value="${binDir}\Log Files" /> defines the location of PcVue's log files folder

Each target is represented by a target element. There are two mandatory attributes for each target:

• name - The name by which the target is known in the configuration file

• xsi:type - The type of target - for example File or Database
  

In addition to these attributes, targets accept other attributes dependent on the target type. For example, for the file target:

• fileName defines the name of the actual target file

• archiveFileName, archiveAboveSize, archiveNumbering and maxArchiveFiles control the size of the target file and how it is archived once that size is reached

• layout - The contents and structure of the output

And for the Windows event log target.

• source - The source of the messages which will appear in the Windows Event Viewer

• layout - The contents and structure of the output

Log levels

Each log entry has a level. And each logger is configured to include or ignore certain levels. A common configuration is to specify the minimum level where that level and higher levels are included. For example, if the minimum level is Info, then Info, Warn, Error and Fatal are logged, but Debug and Trace are ignored.

The sv.log target and the Log Monitor

The default settings in the NLog configuration file includes a local log file target that generates a file called sv.log in the <InstallDir>\Bin\Log Files folder. The generated file has a maximum size of 50 Mb, after which it is automatically archived, and recording starts again. The archive files are named sv-n.log, where n is a number from 0 to 2 (sv-0.log is the most recent).

The contents of the sv.log file can be viewed in real-time using the Log Monitor. Show picture

The Windows event log target and the Windows event viewer

The default settings in the NLog configuration file includes a target that sends events to the Windows event log.
The Windows event log can be viewed using the Windows event viewer. Show picture

Settings for the Syslog target

 PcVue's implementation of NLog includes a Syslog target which allows sending events to a Syslog aggregator. Syslog is defined by several RFCs and the default configuration requires tuning to accommodate the specific requirements of the tools in use in your system. Briefly, the RFCs are as follow and available on the IETF web site:

• RFC 3164 - The original specification for the message format

• RFC 5424 - Later specification originating from when Syslog became a recognized standard

• RFC 5425 - Support for Syslog over TLS (transport layer security)

• RFC 5426 - Support for Syslog over UDP

• RFC 6587 - Transmission of Syslog Messages over TCP

The Syslog target is configured by adding a file named NLog.Targets.Syslog.config in the Bin folder. To see an example of this file click here. Show file

<?xml version="1.0" encoding="utf-8" ?>
<nlog
  xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
  xmlns:sl="http://www.nlog-project.org/schemas/NLog.Targets.Syslog.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <!-- go to https://github.com/luigiberrettini/NLog.Targets.Syslog for more information -->

  <extensions>
    <add assemblyFile="NLog.Targets.Syslog.dll"/>
  </extensions>

  <targets>
    <target name="sv.Syslog" xsi:type="sl:Syslog">
      <sl:layout xsi:type="SimpleLayout" text="${message}${exception:format=ToString,StackTrace}" />
      <sl:enforcement>
        <sl:splitOnNewLine>false</sl:splitOnNewLine>
        <sl:transliterate>false</sl:transliterate>
        <sl:replaceInvalidCharacters>false</sl:replaceInvalidCharacters>
        <sl:truncateFieldsToMaxLength>true</sl:truncateFieldsToMaxLength>
        <sl:truncateMessageTo>1024</sl:truncateMessageTo>
      </sl:enforcement>
      <sl:messageCreation>
        <!-- facility name: Local0, Local1, Local2, Local3, Local4, Local5, Local6 or Local7 -->
        <sl:facility>Local4</sl:facility>
        <sl:perLogLevelSeverity>
          <sl:fatal>Critical</sl:fatal>
          <sl:error>Error</sl:error>
          <sl:warn>Warning</sl:warn>
          <sl:info>Notice</sl:info>
          <sl:debug>Informational</sl:debug>
          <sl:trace>Debug</sl:trace>
        </sl:perLogLevelSeverity>
        <!-- rfc: Rfc3164 or Rfc5424 -->
        <sl:rfc>Rfc5424</sl:rfc>
        <!-- settings related to RFC 3164 -->
        <sl:rfc3164 hostname="${machinename}" tag="${logger}: ">
          <sl:outputPri>true</sl:outputPri>
          <sl:outputHeader>true</sl:outputHeader>
        </sl:rfc3164>
        <!-- settings related to RFC 5424 -->
        <sl:rfc5424 hostname="${machinename}" appName="${logger}" procId="${processid}" msgId="-">
          <sl:disableBom>false</sl:disableBom>
        </sl:rfc5424>
      </sl:messageCreation>
      <sl:messageSend>
        <!-- protocol: UDP or TCP -->
        <sl:protocol>UDP</sl:protocol>
        <!-- settings related to UDP -->
        <sl:udp>
          <sl:server>127.0.0.1</sl:server>
          <sl:port>514</sl:port>
        </sl:udp>
        <!-- settings related to TCP -->
        <sl:tcp>
          <sl:server>127.0.0.1</sl:server>
          <sl:port>1468</sl:port>
          <!-- framing: nonTransparent or octetCounting -->
          <sl:framing>octetCounting</sl:framing>
          <!-- settings related to TLS -->
          <sl:tls>
            <sl:enabled>false</sl:enabled>
            <sl:useClientCertificates>false</sl:useClientCertificates>
            <sl:certificateStoreLocation></sl:certificateStoreLocation>
            <sl:certificateStoreName></sl:certificateStoreName>
            <sl:certificateFilterType></sl:certificateFilterType>
            <sl:certificateFilterValue></sl:certificateFilterValue>
          </sl:tls>
        </sl:tcp>
      </sl:messageSend>
    </target>
  </targets>

  <rules>
    <logger name="*" minlevel="Info" writeTo="sv.Syslog" />
  </rules>

</nlog>

This sample file includes setting for both RFC 3164 or RFC 5424, both the TCP and UDP protocols, and TLS. If using this example as a basis for your configuration, make sure you set the rfc setting properly.

It is outside the scope of this help to provide a full description of every element, but the basic structure of the Syslog target element is as follows:

• enforcement - Settings related to enforcing message rules. The maximum length of a message is defined by the supported RFC's and the setting TruncateMessageTo must be set accordingly.

• messageCreation - Settings related to message creation in the format defined by either RFC 3164 or RFC 5424.

• messageSend - Settings related to how the message is sent. This includes the protocol used, either TCP or UDP, the server and port address and transport layer security parameters.