Diagnosing complex SIP problems often requires looking at the SIP message flow between the components of sipXcom, as well as to and from phones and external gateways. This page tells the adventurous how to use the tools that are available for sipXcom to display SIP message flows. Sipviewer is a very powerful tool used to diagnose problems.

Installation

Before you can display the messages, you'll need to run sipx-trace to generate XML files of a SIP call you're interested in and you'll need to install sipviewer on a computer that has a GUI. You can do that either on the sipXcom system itself (which requires a few prerequisites not installed by the ISO image, but most of us don't want to run a GUI on the communications server), or standalone on your regular system (Windows, Mac, or Linux). Once you've gotten one of these done, you're ready to collect trace data for viewing.

You'll want sipxtools installed on your sipXcom server and sipviewer installed on some computer with a GUI and Java (works on Linux, Mac and Windows).

yum install sipxtools

SIPViewer Installation

The installer for the sipviewer tool is available here: Download the sipviewer installer

The above installer is a java .jar file - execute it on the command line of your system as follows:

The installer should work on any system (Linux, Windows, Mac) that has java installed.

Getting SIP Messages to display

The SIP messages are logged by sipXcom services when their logging is at the INFO or DEBUG logging level; this is a more verbose level than the default NOTICE level. The log level can be changed in the Web UI by going to each service needed in  the System menu (Proxy, Registrar, etc.). Logging level changes do not require service restarts (they used to in older versions of code).

To get trace information, at least the proxy and registrar must be set at INFO or DEBUG (INFO is sufficient for traces, and makes for much smaller log files). You should also have detailed logging for any other component you suspect to be involved in the problem.

If you can get the time a problem call is made, a good way to find it is to look in the proxy log file by searching the list of dialogs with the sipx-dialog-count command:

it will print a list like this:

search that list for the call that starts at the right time (log times are in UTC), and then use the call-id from that call as the <token> argument to sipx-trace - you'll get just the one call you're after.

Alternatively, if you download CDR's from Diagnostic -> Call Detail Records -> Historic (download is on the right, just above the call table). The CSV's include the call id of each call.

Next, use 'sipx-trace' to create an xml file that contains trace data for messages on your system:

where <filename> is the output file and <token> is some token that will be in the call (call-id values are best for this, but even the calling number followed by '@' will find it; it will just find lots of other stuff too).

You can copy that xml file to any system where you have installed the sipviewer tool to display the trace, and you can post that file to a mailing list to ask for help interpreting it (be sure to also post a description of your configuration, including the IP addresses for all the components that show in the trace).

Using Sipviewer over an ssh connection

If you have an account on the sipXecs system that you can log into using ssh, and your workstation is a Linux (or compatible) system you can set up remote use of sipx-trace from another system:

• Install your ssh public key in your account on the sipXcom system. You should then be able to execute a command remotely on that system without entering a password:

• Configure that account so that it can read the sipXecs log files.

Now you can execute sipx-trace remotely by adding the --system (-s) argument:

If you have an HA sipXecs, you must query all the systems at the same time to get the trace data:

The sipviewer display

sipviewer-install.jar