Trace support must be enabled during compilation of the SDK. Ensure that the CMake switch TRACE_ENABLED is ON, which is the SDK's default setting.
Check what TRACE_BACKEND is selected:
- stderr: This is the default backend and will print all trace infos to console using fprintf(stderr, ...).
- file: This will write the traces to the configured file.
- syslog: This will write trace to the system log using the syslog command (see man(3) syslog). This backend is for Linux and other UNIX like systems.
Check that trace is enabled at runtime. The UA application needs to enable the trace by calling trace_openlog(), which allows filtering by facility and trace level.

Our example applications offer command line switches to change the trace settings.

Listing available trace levels:

$> ./uaserverhp -l
trace levels:
  TRACE_LEVEL_DEBUG          1 (0x1)
  TRACE_LEVEL_DATA           2 (0x2)
  TRACE_LEVEL_INFO           4 (0x4)
  TRACE_LEVEL_FUNC_ENTER     8 (0x8)
  TRACE_LEVEL_FUNC_LEAVE    16 (0x10)
  TRACE_LEVEL_FUNC          24 (0x18)
  TRACE_LEVEL_NOTICE        32 (0x20)
  TRACE_LEVEL_WARNING       64 (0x40)
  TRACE_LEVEL_ERROR        128 (0x80)
  TRACE_LEVEL_INSANE       256 (0x100)
  TRACE_LEVEL_ALL          511 (0x1ff)
trace facilities:
  TRACE_FAC_PLATFORM                1 (0x1)
  TRACE_FAC_NETWORK                 2 (0x2)
  TRACE_FAC_CRYPTO                  4 (0x4)
  TRACE_FAC_IPC                     8 (0x8)
  TRACE_FAC_BASE                   16 (0x10)
  TRACE_FAC_MEMORY                 32 (0x20)
  TRACE_FAC_UATCP                  64 (0x40)
  TRACE_FAC_ENCODER               128 (0x80)
  TRACE_FAC_SESSION               256 (0x100)
  TRACE_FAC_PROVIDER              512 (0x200)
  TRACE_FAC_APPLICATION          1024 (0x400)
  TRACE_FAC_ADDRSPACE            2048 (0x800)
  TRACE_FAC_TIMER                4096 (0x1000)
  TRACE_FAC_PKI                  8192 (0x2000)
  TRACE_FAC_SUBSCRIPTION        16384 (0x4000)
  TRACE_FAC_CLIENT              32768 (0x8000)
  TRACE_FAC_USERAPPLICATION     65536 (0x10000)
  TRACE_FAC_FILEFORMAT         131072 (0x20000)
  TRACE_FAC_FILETRANSFER       262144 (0x40000)
  TRACE_FAC_PUBSUB             524288 (0x80000)
  TRACE_FAC_ALL               1048575 (0xfffff)
usage example: ../bin/uaserverhp -d info,debug -f network,encoder

By default, the applications only enable TRACE_LEVEL_ERROR and TRACE_LEVEL_WARNING. If you want to enable more trace levels, you can use the command line switch -d.

$> ./uaserverhp -d all

By using the switch -f you can filter the output for the specific component e.g. TRACE_FAC_MEMORY.

$> ./uaserverhp -d info -f memory

Note that traces TRACE_LEVEL_ERROR ignore the facility filter and will always be shown.

Trace Security

By default the SDK does not trace sensitive data like usernames and passwords. It uses special trace macros like TRACE_USERNAME, TRACE_PASSWORD, TRACE_IPv4 and TRACE_IPv6 to trace sensitive data. It is recommended that you use these macros too when you need to trace sensitive information in your own code. This avoids leaking information when a trace file is e.g. sent by mail.

Instead of tracing the content these macros output 'XXX' or <hidden> by default, no matter what trace level you have configured. You must explicitly enable this content by calling trace_change_security_level(). This avoids accidentally leaking sensitive information by using TRACE_LEVEL_DEBUG, ALL or similar.

File Trace

When using the file trace backend, this backend reads in its own configuration file trace.conf. This configures the trace file name, directory, and trace file rotation.

The parameters are described in the file itself.

Example trace.conf:

# The following trace settings only apply for the file-backend.
# Other trace backends will ignore these settings.
[file-trace]
# directory: Directory where the traces should be saved.
# Default is ".", which logs into the current working directory.
directory = "."
# basename: the trace file basename.
# Default is "log", which will create a name like "log.1234.1",
# by appending the process id and the sequential log file no.
basename = "log"
# log file extension
extension = ".txt"
# include the PID into the filename
include_pid = false
# Maximum number of files to create. Older files will be deleted.
max_files = 5
# Maximum number of lines per file. When this limit is reached a new file gets created.
max_lines = 1000000
# force flush after every trace line. This avoids data loss in case of a crash,
# but is much much slower.
force_flush = false
# append to existing file, overwrite when false
append = false

Adding/Removing Color from Trace Output

On Linux the stderr trace backend uses color output by default to make the trace better readable. On Windows this is disabled by default because Windows is lacking a proper terminal with color support. If you want to disable color support from the backend you can disable the CMake option ENABLE_COLOR, then the trace backend will be built without color support.

Removing Colors

When opening redirected output in primitive editors these colors might not get displayed correctly. In this case you can strip the color information (ANSI escape sequences) from the text files.

Using this Perl script you can remove the ANSI escape sequences from a file.

colorstrip.pl:

#!/usr/bin/env perl
use Term::ANSIColor qw(colorstrip);
print colorstrip(<>);

Usage:

$> cat trace.log | colorstrip.pl > trace_plain.log

Adding Colors

When you have a trace file without colors and you want to add those nice colors afterwards you can use the following little Perl script.

#!/usr/bin/env perl
use Term::ANSIColor qw(:constants);
foreach (<>) {
    local $Term::ANSIColor::AUTORESET = 1;
    if (/^E/) {
        print(BOLD RED, $_, RESET);
    } elsif (/^W/) {
        print(BOLD MAGENTA $_);
    } elsif (/^N/) {
        print(BOLD CYAN $_);
    } elsif (/^I/) {
        print(BOLD BLUE $_);
    } elsif (/^D/) {
        print(WHITE $_);
    } elsif (/^[0-9A-f]{2} [0-9A-f]{2}/) { # hexdumps
        print(BOLD YELLOW $_);
    } else {
        print;
    }
}

This script can also easily be extended to perform filtering operations or highlighting other useful information like e.g. NodeIds.

Opening Trace Files in Vim

For the Vim Editor there is a simple script which enables support for ANSI escape sequences. This makes the colors show up correctly in Vim.

Download: https://github.com/powerman/vim-plugin-AnsiEsc

Using a plugin manager like e.g. Vundle you need to add this line to your plugin config

Plugin 'powerman/vim-plugin-AnsiEsc'

and install using :VundleInstall.

After opening a file you can type :AnsiEsc to enable processing of the ANSI escape sequences. You can also automate this by adding the following snippet to your ~/.vimrc.

augroup VimAutoAnsiEsc
    autocmd!
    autocmd BufRead *.log AnsiEsc
augroup END