The SDK has built-in trace support which is helpful for analyzing problems.
Trace Checklist:
- 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
debug levels:
TRACE_LEVEL_DEBUG 1
TRACE_LEVEL_DATA 2
TRACE_LEVEL_INFO 4
TRACE_LEVEL_FUNC_ENTER 8
TRACE_LEVEL_FUNC_LEAVE 16
TRACE_LEVEL_FUNC 24
TRACE_LEVEL_NOTICE 32
TRACE_LEVEL_WARNING 64
TRACE_LEVEL_ERROR 128
TRACE_LEVEL_INSANE 256
TRACE_LEVEL_ALL 511
debug facilities:
TRACE_FAC_PLATFORM 1
TRACE_FAC_NETWORK 2
TRACE_FAC_CRYPTO 4
TRACE_FAC_IPC 8
TRACE_FAC_BASE 16
TRACE_FAC_MEMORY 32
TRACE_FAC_UATCP 64
TRACE_FAC_ENCODER 128
TRACE_FAC_SESSION 256
TRACE_FAC_PROVIDER 512
TRACE_FAC_APPLICATION 1024
TRACE_FAC_ADDRSPACE 2048
TRACE_FAC_TIMER 4096
TRACE_FAC_PKI 8192
TRACE_FAC_SUBSCRIPTION 16384
TRACE_FAC_CLIENT 32768
TRACE_FAC_USERAPPLICATION 65536
TRACE_FAC_FILEFORMAT 131072
TRACE_FAC_ALL 262143
usage example: ./uaserverhp -d $((128+64+32)) -f $((1024+2048+131072))
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
.
By using the switch -f
you can filter the output for the specific component e.g. TRACE_FAC_MEMORY
.
$> ./uaserverhp -d 255 -f 32
Note that traces TRACE_LEVEL_ERROR
ignore the facility filter and will always be shown.
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