DXSpider Tracing Debug Entries

General Information

DXSpider has the ability to log information at various levels, and those levels are set using the debug tool in conjunction with the debug levels. Whilst this information is captured in the data files of ../spider/local_data/debug/ it can also be seen in realtime from the command line prompt. Once the debug levels are set the 'watchdbg' tool can be used from ../spider/perl/ to watch the cluster's full data stream. This can be a very busy stream but it can be filtered for easier scrutiny.

This guide assumes that 'watchdbg' has been linked to /usr/local/bin. If not, you can run this command in Linux:

 sudo ln -s /spider/perl/*dbg /usr/local/bin

This command will link all dbg subroutines in /spider/perl to /usr/local/bin so they can be accessed from the user prompt like any other built in command.

watchdbg

• watchdbg [-nnn lines before] [!<regexp>|<regexp>]...

You can have more than one <regexp> with an implicit 'and' between them. All <regexes> are caseless. It's recommended to put 'not' (!<regex>) first in any list. Don't forget that you are doing this in a shell and you may need to quote your <regex>s.

grepdbg

• grepdbg [nn days before] [-nnn lines before] [<perl filter module>] [<regexp>|!<regexp>]...

You can have more than one <regexp> with an implicit 'and' between them. All <regexes> are caseless. It's recommended to put 'not' (!<regex>) first in any list. Don't forget that you are doing this in a shell and you may need to quote your <regex>s. 'grepdbg' with no arguments will simply list the current debug log with the timestamp for each line decoded into a human readable form.

grepdbg | less

is a handy way of scrolling through the debug log.

grepdbg -2 progress

will display any line containing 'progress' and also the two lines before that. You can install your own content and display arrangement (useful for filtering data in some complicated way). You call it like this (assuming it is called 'filter.pm').

This is what is meant by <perl filter module>.

grepdbg filter.pm

All the other arguments to grepdbg are available to limit the input to your filter. If you want them. The filter module MUST contain at least:

package main;
  sub handle
  {
    your code goes here
  }
  1;

It can also have a 'sub begin {...}' and / or 'sub end {...}' which are executed immediately after opening a logfile and then just before closing it, respectively. You can also add a 'sub total {...}' which executes after the last line is printed and grepdbg exits. Read the code of this program and copy'n'paste the 'sub process' code into a new file. Then change 'sub process' to 'sub handle'. Add the line 'package main;' at the beginning of the file and a line '1;' at the end and then modify it to your requirements...

Filtering

Regexes can be debug levels, nodes, or even a strings of text. See Wikipedia for a basic regex explanation. Regex101 is a good place to practice. Just be aware that DXSpider and it's associated programs use the Perl flavor of regex.

To trace incoming messages the I is used, and for outbound the D is used:

'<- I' or ' I '

'-> D' or ' D '

Protocols can be traced by using the PC number:

'PC9[23]'

In this example we're using '[23]' to express a range of possibilities. This results in PC92 and PC93 being hits for the filter.

Debug levels can be traced using the level name:

"chan|progress"

This regex will hit on any debug entry with the level label of "chan" or "progress".

A more complex example using Perl regex AND ( .* ) and OR ( | ):

"wi3w\-3.*ea2cw\-4|ea2cw\-4.*wi3w\-3"

This regex will hit on any match of wi3w-3 and ea2cw-4 in that order OR any match of ea2cw-4 and wi3w-3 in that order.

Trace examples

To watch all outbound spots from this node:

watchdbg ' D ' 'PC[16]1'

or to watch everything outbound:

watchdbg '\-> D' or watchdbg ' D '

The same can be done for inbound traffic:

watchdbg '<\- I' or watchdbg ' I '

or to watch all inbound PC92 frames:

watchdbg ' I ' 'PC92'

Note: the hyphen needs to be escaped with the " \ " character. The spaces between ' D ' are important, make sure they are included.

grepdbg '<\- I GB7TLH' or grepdbg ' I ' 'gb7tlh'

This command will grep from the current day's debug file and filter on all incoming traffic from the node GB7TLH. Again, the spaces are important as they mimic the format of the debug log entries.

grepdbg 2 -5 gb7tlh

This command will hit on anything with 'gb7tlh' in it from 2 days ago and will show the 5 entries before the hit.

grepdbg "connect.*(gb7tlh|wi3w\-3)"

This command will hit on any debug entry with the 'connect' AND either GB7TLH OR WI3W-3 in that order.

Note: these filters are being used in the shell, certain characters will need to be escaped and certain regex strings will need to be quoted.

Saving to a file

It is possible to save the output of these commands to a specific file by using the redirection operator " > " or " >> "in Linux. The " > " will overwrite a file and " >> " will append to a file. Both operators will create a file if it does not exist. Ex:

watchdbg ' D ' 'PC[16]1' >> trace.txt

This command will create the file 'trace.txt' and redirect the output of the command to the file. This will need to be stopped with the key combination of Ctrl + C. If we run the same command again:

watchdbg ' D ' 'PC[16]1' >> trace.txt

it will append the output to the existing file, but if we run:

watchdbg ' D ' 'PC[16]1' > trace.txt

it will clobber (wipe out the contents of) the existing file and then start to output data to the file.

If you want to view the output of these commands while simultaneously sending the output to a file you can use the 'tee' command:

grepdbg connect | tee trace.txt

or you can use 'tee -a' to append to the file:

grepdbg 1 gb7tlh | tee -a trace.txt