summaryrefslogtreecommitdiff
path: root/DeveloperNotes/Debugging.mdwn
blob: f50d02e083a7517b58c44e123912af6b3df83800 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
## If you are using Empathy...

Empathy has a debug console which shows you the debug output from components of your choice. See [[the Empathy wiki|http://live.gnome.org/Empathy/Debugging]] for more details. 

If you're not using Empathy, or you're debugging a crash, or you're just feeling old-school, read on! 


## Connection managers

Many Telepathy problems are not directly the fault of the user interface (such as Empathy), but of the connection managers (Gabble, Idle, Salut, Haze, Butterfly, Telepathy-SofiaSIP, ...), which are the services responsible for actually connecting to your IM accounts. CMs generally run in the background, with no visible output; in order to get debugging output from them, you'll need to run them manually. 

Connection manager executables don't generally live in your `$PATH`, so you'll need to provide the full path in the following commands (rather than just `telepathy-foo`) to invoke them. 

* on Fedora-like systems, connection managers live in `/usr/libexec/` 
* on recent Debian-like systems connection managers live in `/usr/lib/telepathy/` 
* if you have installed from source, the default location is `/usr/local/libexec/` 

### Obtaining logs

First, quit your IM client (such as Empathy), and wait a few seconds for the connection managers to quit of their own accord. Then, in a terminal, run: 

    G_MESSAGES_DEBUG=all FOO_PERSIST=1 FOO_DEBUG=all /path/to/telepathy-foo 2>&1 | tee foo.log

(where `foo` should be `gabble` for Jabber, and the name of the relevant CM for the protocol you're having trouble with, as listed on [[Components|Components]]). Now, start your IM client again, and reproduce the problem; debugging output should appear in your terminal, and be written to `foo.log`. (You can set the `_DEBUG` variable to values other than `all` if you only want the debugging output from a certain part of the CM, but usually this is unnecessary.) 

If the connection manager complains about "name already or use" and quits immediately, you should `kill` any existing instances of it and try again. 


### Gabble

When debugging Gabble, it's usually a good idea to set `WOCKY_DEBUG=xmpp` (Gabble 0.9) or `LM_DEBUG=net` (Gabble 0.8) so that the XML stanzas are also captured in the logfile. 


### SRV records (Gabble, SIP)

If you're having difficulty connecting to a SIP or Jabber/XMPP server, and you're using Linux, you can check whether SRV DNS lookups are broken on your network using the `host` command-line tool. Collabora's XMPP server has a SRV record, which you can use to try this out, by running: `host -t SRV _xmpp-client._tcp.collabora.co.uk` 

If it works correctly, you'll see something like this: 

`_xmpp-client._tcp.collabora.co.uk has SRV record 0 0 5222 jalfrezi.collabora.co.uk.` 

If SRV lookups don't work on your network you might see an error like this, for instance: 

`Host _xmpp-client._tcp.collabora.co.uk not found: 3(NXDOMAIN)` 


### Mission Control 5

In versions of MC older than 5.3.1 (notably, on Maemo 5), due to [[Bug #22705|https://bugs.freedesktop.org/show_bug.cgi?id=22705]] it is necessary to set `MC_DEBUG=1` to get Mission Control to output debug messages for itself, and something like `MC_TP_DEBUG=all` to output debug messages for telepathy-glib. See the mission-control-5 man page for more details. 


## Debugging crashes


### General

If you are experiencing crashes, it's a good idea to install any Telepathy debug packages provided by your distribution. 

On Debian-like systems, debugging packages include: 

* libtelepathy-glib0-dbg 
* libtelepathy-dbg 
* telepathy-gabble-dbg 

### GDB

You might be able to obtain debug information using gdb (for connection managers, you probably also want to use the X_PERSIST variable for this): 

    $ GABBLE_PERSIST=1 gdb telepathy-gabble
    GNU gdb 6.7.1-debian
    Copyright (C) 2007 Free Software Foundation, Inc.
    License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
    and "show warranty" for details.
    This GDB was configured as "i486-linux-gnu"...
    Using host libthread_db library "/lib/i686/cmov/libthread_db.so.1".
    (gdb) r
    Starting program: /usr/bin/telepathy-gabble 
    ** (telepathy-gabble:17666): DEBUG: started version 0.6.0 (telepathy-glib version 0.7.0)

If the program crashes while running under gdb, use the "bt" command to obtain a backtrace. 

If you can't make it crash while running under gdb (this is not an uncommon state of affairs, for reasons I won't go into here): 

* make sure core dumps are enabled 
   * `ulimit -c unlimited` 
* launch the telepathy component in question (as above) 
   * `FOO_PERSIST=1 FOO_DEBUG=all /path/to/telepathy-foo 2>&1 | tee foo.log` 
* do whatever it is you do to produce a crash 
* inspect the core file (it's normally called "core") 
   * `gdb /path/to/telepathy-foo core` 
   * at the gdb prompt: `bt full` 
NOTE: If you are running more than one component to debug, either tun them in different directories so their core files don't overwrite one another in the event of a crash,  or `sudo sysctl -w kernel.core_uses_pid=1` to make the core file name contain the PID 


### Valgrind

Valgrind can find many bugs. 

* [[Valgrind home page|http://valgrind.org/]] 
* [[suppression file|http://projects.collabora.co.uk/~robtaylor/glib+glibc.supp]] to stop it complaining about glibc and glib oddities. 

### Electric Fence

Electric Fence can find some memory allocation bugs. 

To use it, run Programs with LD_PRELOAD=/usr/lib/libefence.so.0.0. 

* [[Electric Fence home page|http://perens.com/FreeSoftware/]].