Child pages
  • Display SIP Message flow using Sipviewer
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Current »

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


Before you can display the messages, you need to install the viewer. You can do that either on the sipXecs system itself (which requires a few prerequisites not installed by the ISO image), 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 also want sipxtools installed for sipx-trace (yum install sipxtools).


There is a standalone installer for the sipviewer tool in the temp area on the sipxecs project server:

Download the sipviewer installer

The above installer is a java .jar file - execute it on your system to run the installer, eg:

java -jar sipviewer-install.jar

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

On your sipXcom system

On RPM-based distributions sipviewer is installed with the sipxtools RPM. Sipviewer is written in Java and requires an X server to be running to display results graphically.

Getting SIP Messages to display

The SIP messages are logged by sipXecs components at the INFO 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 "System/General/Logging". You must restart the components for the change in logging level to take effect.

To get useful 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:

sipx-dialog-count /var/log/sipxpbx/sipXproxy.log

it will print a list like this:

Messages Method Time Call-Id
-------------- ---------- ------------------- ------------------------------------------------
50 INVITE 2009-12-11T22:22:20
36 INVITE 2009-12-11T22:17:19

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.

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

sipx-trace --all-components --output <filename> <token>...

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 sipXecs system. You should then be able to execute a command remotely on that system without entering a password:

> ssh echo ok

  • Configure that account so that it can read the sipXecs log files (making the account a member of the 'sipxchange' group should do this).

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

sipx-trace --system --all-components --output <filename> <token>...

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

sipx-trace -s -s --all-components --output <filename> <token>...

The sipviewer display


  • No labels