Toolpack Debug Application:Tbdebug

Revision as of 15:15, 23 November 2011

What is tbdebug

Tbdebug is a debugging tool of Toolpack that is used to gather essential information about the system when reporting bugs to the TelcoBridges support team. The application will capture the following information:

• Logs of the Toolpack applications
• Configuration and status of the Toolpack system
• Configuration and status of all TMedia units of the system
• Configuration database

It can also capture the following information:

• IP capture from IP interfaces of the TMedia units (except RTP packets)
• Recording of calls

All that information is gathered and archived in a .tgz file that can be downloaded and sent to the TelcoBridges support team.

Why is the procedure to use the tbdebug tool so complicated?

The procedure listed below is relatively long. We are working on integrating this tool in Toolpack's Web Portal so that it is easier to use. Unfortunately, we have not yet completed the integration process, and for the meantime the application must be run from an SSH connection to the server, through the tbx_cli_tools_remote application.

How to launch tbdebug tool

1. Launch tbx_cli_tools_remote application (/lib/tb/toolpack/pkg/2.X.X/bin/release/[distribution]/tbx_cli_tools_remote)
2. Select the tboamapp application
3. Press TAB until the Application launch manager page is selected
4. Press key l (lower-case L)
5. Choose acquisition time for logs (*** see note below about acquisition time and acquisition modes)
6. Press Enter to launch the tbdebug application

If you have selected an acquisition time of 0 or -1, complete the following steps:

1. Press the Escape key two times to exit the tboamapp application
2. Select the tbdebug application
3. Press a to start or stop acquisition

Download resulting capture

Once the tbdebug application has finished the acquisition, it will archive all captured files into a .tgz archive. You can download this archive from

/lib/tb/toolpack/setup/12358/2.X/apps/tbdebug/tbdebug_logs/results/tbdebug[date-time].tar.gz

Using acquisition period greater than 0

In this mode, the tbdebug application will download only the log files of Toolpack applications for that period of acquisition, and will optionally capture IP packets from TMedia, and record calls using tbstreamserver. Use this mode when you can reproduce the problem: Start tbdebug with a long enough period and then reproduce the problem. This ensures that only a short and appropriate portion of the application logs aregathered, simplifying the analysis of the log files by focusing on the period where the actual problem was reproduced.

Using acquisition period of -1 (infinite)

This mode will also capture logs for a period of acquisition. The duration of the period is infinite, and the user must manually stop the acquisition by pressing the letter a key in the tbdebug applications' window (through tbx_cli_tools_remote application)

Using acquisition period of 0 (snapshot mode)

In this mode, the tbdebug application will not use an acquisition period, but will instantly gather logs of all applications for the current day, as well as other logs that are not related to an acquisition period (there will thus be no IP capture or recording in that mode). Use this mode when the bug has already occurred, and cannot be reproduced again.

Using tbdebug to perform Ethernet capture (tcpdump) on the adapter

1. Launch tbx_cli_tools_remote application (/lib/tb/toolpack/pkg/2.X.X/bin/release/[distribution]/tbx_cli_tools_remote)
2. Select the tboamapp application
3. Press TAB until the Application launch manager page is selected
4. Press key l (lower-case L)
5. Choose -1 for execution time
6. Press Enter to launch the tbdebug application
7. Press the Escape key two times to exit the tboamapp application
8. Select the tbdebug application
9. Press t to start or stop the tcpdump capture (on one, or all adapters)

After stopping the capture, a wireshark-compatible ".cap" file will be available here, for each adapter: /lib/tb/toolpack/setup/12358/2.X/apps/tbdebug/tbdebug_logs/tcpdump/

Using shell commands to perform Ethernet capture (tcpdump) on the adapter

Another way to perform a tcpdump capture on the adapter is from it's shell:

1. Start the capture (with circular buffer of 1MB),
2. stop the capture,
3. then upload the capture (there must be a FTP server accepting anonymous connections, here on example IP 10.11.12.13):

tcpdump start 1000000
tcpdump stop
tcpdump upload 10.11.12.13

Optional capture options

Additional capture parameters can be configured from the tbdebug configuration file:

/lib/tb/toolpack/setup/12358/2.X/apps/tbdebug/tbdebug.xml

We recommend changing only the following parameters:

record_new_calls:     Enable/disable recording of new calls established during the acquisition period
record_current_calls: Enable/disable recording of calls already present at the time the acquisition period starts
trace_level:          Allows automatically changing trace level (value from 0 to 4) of all applications during the acquisition period.
                      Using "disabled" will cause trace level to remain unchanged.
                      A trace level of 4 will gather almost no traces (less verbose)
                      A trace level of 0 will gather the most information (may create big log files)
                      A trace level of 1 is generally appropriate for debugging most call-flow related bugs