Logging Methods

The driver runs partly in kernel mode and partly in user mode. The kernel mode part
uses one way to log messages and the user mode part uses another way to log messages.
Logging is done in five different ways:

Note

The log read tool ntlog can only be used when ntservice is loaded.

Kernel Mode Part

1. Log buffer
   All messages are logged to the kernel mode log buffer
   and can be read using the ntlog tool.
   

   Note

   This is not the same log buffer as the user mode log buffer.

   
   

2. DMESG (Linux/FreeBSD only)
   All messages are logged to the kernel log and can read using dmesg.
   

User Mode Part

1. Log buffer
   All messages are logged to the user mode log buffer
   and can be read using the ntlog tool.
   

   Note

   This is not the same log buffer as the kernel mode log buffer.

   
   

2. File log
   Log messages can be written to a file. This must be enabled in the ntservice.ini file.
   The file log does not contain the kernel mode log messages and the initial startup
   log messages.
   
   
3. Syslog (Linux/FreeBSD) - Event log (Windows)
   Error, warning and information log messages are written to the syslog and can be read from here. How to read
   the syslog depends of the platform and setup for the OS.

   Note

   Logging to the syslog/Event log can be turned off in the ini-file.

   
   Log Comparison

   Method	Context	Read	Content	Persistent	Can be Disabled
   DMESG (Linux/FreeBSD)	Kernel mode	dmesg	Kernel mode messages together with other OS messages	Yes	No
   Kernel mode log buffer	Kernel mode	ntlog tool	Both kernel mode messages and user mode messages are listed when using the ntlog tool	No - disappears when the driver is unloaded	No
   User mode log buffer	User mode	ntlog tool	Both kernel mode messages and user mode messages are listed when using the ntlog tool	No - disappears when the service is unloaded	No
   File	User mode	Text editor	Does not contain kernel mode messages and initial user mode messages	Yes	Yes
   Syslog/Event log	User mode	System dependent	Does not contain kernel mode messages. Only contains error, warning and information user mode messages	Yes	Yes

   Log Buffer Size

The user mode log buffer is a circular buffer with a size of 4 MBytes.
When the amount of log information exceeds the buffer size, the buffer either wraps around or
discards further messages. The behavior of the buffer must be set in the ntservice.ini file.

File Logging

File logging must be enabled in the ntservice.ini file and does not contain any kernel mode messages
or early user mode messages. From the line "<<<<<<<<<< Logging to file "/tmp/test.log" >>>>>>>>>>"
in the ntlog, the content of the file log and the output from the ntlog tool (log buffer) are identical.

Example (goes into your ntservice.ini file):

 [logging]
 LogToFile = 1
 LogFileName = /var/log/ntservice.log

Log rotation

NTService does not monitor the size of the log file, so it will grow forever. To prevent this, you need to set up log rotation. There are different ways to do this. Only on posix systems though.

ntservice will reopen the log file if it receives a SIGUSR2 signal. You can send this signal from a command line:

killall -USR2 ntservice

There are two ways to utilize this mechanism:

1. Use an "%s" in the log file name (LogFileName parameter in ntservice.ini).

   Then set up a cron job to send the USR2 signal at desired intervals.

   Each time ntservice receives the USR2 signal, it reevaluates the "%s", so it opens a log file with a new name based on current timestamp.

2. Use a static log file name, fx /var/log/ntservice.log.

   Then use the standard linux logrotate tool with a configuration like this (fx. in /etc/logrotate.d/ntservice.conf):

   /var/log/ntservice.log
   {
     missingok
     rotate 20
     notifempty
     postrotate
       /usr/bin/killall -USR2 ntservice
     endscript
   }
   

   When the logrotate tool determines it is time to rotate the log, it will rename the log file, then send the USR2 signal, which makes ntservice close the old log file, then create a new log file with the configured name.

syslog/Event log Logging

Logging to the system log is enabled from startup. It can be disabled in the ini-file by setting the key LogToSystem.
Doing this will stop the system logging after the ini-file has been read.
Only Errors, Warinings and Information is logged to the system log.

Log Message Format

There is no strict format for the log messages and the log messages can change or disappear
between releases.

The log output format is described here: ntlog

Initial Setup - ntservice.ini

The logging function is set up in the ntservice.ini file in the [logging] section.

Command	Description
LogMask	Bitmask that specifies the level of log information to record. Corresponds to the -s parameter of the log command. 0x01 : ERROR Cannot be disabled - will always be recorded 0x02 : WARNING Cannot be disabled - will always be recorded 0x04 : INFO Cannot be disabled - will always be recorded 0x08 : DEBUG Records debug information 0x10 : DIAG Records diagnostic information 0x20 : EVENT Records information about events 0x40 : COMMAND Records information about commands 0x80 : API Records information about API calls
LogToFile	Enables logging to file. All log information is saved to a file. 0 Disables log to file 1 Enables log to file Note The log file is not wrapped and will grow in size. Enabling the LogToFile will cause the hard disk to be filled with a large log file.
LogFileName	The file name for the log file. If the file name contains a %s, this will be expanded with the current date and time for when the service was started. For example: /tmp/test.log will not be expanded /tmp/test_%s.log will be expanded to /tmp/test_11_10_28_11_23_21.log The %s can be placed anywhere in the file name string.
LogBufferWrap	Sets whether or not the buffer should wrap around when full. wrap Log buffer wraps when full. Oldest messages are overwritten nowrap Log does not wrap. Logging stops when buffer is full and discards all new messages.
LogToSystem	Enable or disable log the system log syslog/Event log 0 Disable system logging 1 Enable system logging

ntservice.ini example

[logging]
LogMask=0x0F
LogToFile=1
LogToSystem=1
LogFileName=/tmp/test.log
LogBufferWrap=wrap

Reading the Log After a Crash of ntservice

In most cases the shared memory containing the log will survive after ntservice crashes.
The log can be read using the supportinfo tool or the ntlog tool. Restarting the ntservice
will delete the log.

In case of a ntservice crash, it is important to run the supportinfo tool immediately after the
crash in order to record important information for conveying to the Napatech Support Center.

Requirements

For both Linux and FreeBSD it is required that the procfs pseudo-filesystem is mounted under mountpoint /proc
For more info see - Linux: "man proc" FreeBSD: "man procfs"
If procfs is not mounted under /proc - the ntlog subsystem and the profiling tool will be unable to translate process ids (PIDs) into process names (both tools will still be functional).