Logging

Reference Documentation

Platform
Intel® PAC
Napatech SmartNIC
Content Type
Reference Information
Capture Software Version
Link™ Capture Software 12.10
Napatech Software Suite: Logging

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.

CommandDescription
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).