When you write a plugin for the Media Server, one of your first tasks is to print out debug information. Because a plugin is a dynamic library that runs directly within the server process, you can choose between several logging methods.

This guide explains your logging options, how to use the built-in nx_kit library, and how to capture output streams.

Choose a logging option

You can log data from a plugin in two ways:

• Print to stdout or stderr: This is the recommended approach. You can use standard C++ streams like std::cout and printf(), or use the nx_kit helper library included with the SDK. The nx_kit library automatically adds logging levels and context prefixes to your messages.

• Use a custom logging subsystem: You can integrate your own library or a third-party logging framework. This approach is only recommended if you already have an existing logging infrastructure.

Log with nx_kit

The nx_kit library (nx/kit/debug.h) provides a simple way to log messages to stderr. It uses two primary macros to define log levels:

• NX_PRINT: Prints the message unconditionally. Use this for regular log messages.

• NX_OUTPUT: Prints the message only if your configuration allows it. Use this for verbose log messages.

Compared to std::cerr, these macros offer the following advantages:

• Automatic newlines: You do not need to add \n at the end of your messages.

• Context prefixes: The macro automatically prefixes the message with the filename that calls it. To customize this prefix, define NX_PRINT_PREFIX before including the header.

nx_kit defaults to stderr because it is unbuffered, which reduces the risk of message collision when multiple threads write simultaneously. To change the target stream, see the Doxygen documentation for nx/kit/debug.h.

Code example

// my_module.cpp
#define NX_DEBUG_ENABLE_OUTPUT true
#include <nx/kit/debug.h>

void func()
{
    // Automatically appends a newline character
    NX_PRINT << "Printed unconditionally.";

    NX_OUTPUT << "Printed only if NX_DEBUG_ENABLE_OUTPUT is true.";
}

Output:

[my_module.cpp] Printed unconditionally.
[my_module.cpp] Printed only if NX_DEBUG_ENABLE_OUTPUT is true.

Switch log levels at runtime with an INI file

To dynamically change your log levels without recompiling your code, use the IniConfig mechanism in nx_kit.

1. Add an enableOutput boolean flag to your .ini options structure:
    

   // my_module_ini.h
   #include <nx/kit/ini_config.h>
   
   struct Ini: nx::kit::IniConfig
   {
       Ini(): IniConfig("my_module.ini") { reload(); }
   
       NX_INI_FLAG(0, enableOutput, "Whether to produce verbose log on stderr.");
   };
   
   inline Ini& ini()
   {
       static Ini ini;
       return ini;
   }

2. Include your INI header in your source file. The NX_OUTPUT macro automatically detects the ini().enableOutput expression:
    

   // my_module.cpp
   #include "my_module_ini.h"
   #include <nx/kit/debug.h>
   
   void func()
   {
       NX_OUTPUT << "Printed only if my_module.ini contains the line: enableOutput=1";
   }

For more details, see the article about configuring via .ini files.

Redirect streams to files with OutputRedirector

The nx_kit library includes an OutputRedirector feature that automatically captures stdout and stderr streams into log files. This feature works on both Windows and Linux, and is especially useful on Windows when the server runs as a background service.

Configure file redirection

1. Navigate to the .ini files folder for your process. To find this path, see the [Configuring via .ini files – IniConfig] documentation.

2. Create one or both of the following empty files in that directory:

   • <executable-name-without-extension>_stdout.log

   • <executable-name-without-extension>_stderr.log

When the process starts, OutputRedirector detects these files and begins redirecting the respective streams. The application overwrites these files and clears previous data every time the process restarts.

For details on integrating this into your own apps, see the Doxygen documentation for nx/kit/output_redirector.h.

Example: Redirect server output on Linux

To capture the output of an Nx Witness Server running as a service on Ubuntu Linux, complete the following steps:

1. Create the empty log files in your configuration directory:

   sudo touch /home/networkoptix/.config/nx_ini/mediaserver_stdout.log
   sudo touch /home/networkoptix/.config/nx_ini/mediaserver_stderr.log

2. Restart the server:

   sudo systemctl restart networkoptix-mediaserver.service

3. Monitor the standard error log in real time:

   tail -F /home/networkoptix/.config/nx_ini/mediaserver_stderr.log

View console output without redirection

If you do not want to redirect output to files, you can view the streams directly through your operating system's tools.

For Linux

If you run the default server installation as a system service, run the following command to view the live log stream:

journalctl -u networkoptix-mediaserver.service

Alternatively, you can run the server directly in your terminal console:

1. Navigate to the directory that contains your server executables.

2. Launch the executable with the -e option:

   ./networkoptix-mediaserver/bin/mediaserver -e

For Windows

Launching the Nx Witness Server from the Windows Command Prompt does not display standard output streams. To view stdout and stderr logs on Windows, you must use the Configure file redirection method with OutputRedirector.