~~NOTOC~~
====== Debugging Xfce4-panel ======

The Xfce Panel has a number of tools to create good [[https://bugzilla.xfce.org|bug reports]]. It can also provide some valuable insight for users into how the panel works, in case you have problems.

=== See Also ===

  * **[[:contribute:bugs:start]]** -- Information about reporting bugs and generating backtraces.

  * **[[:xfce:building]]** -- How to compile Xfce from source to provide better debug information.

----

===== Debug Logs =====

On startup, the panel checks the environment variable ''PANEL_DEBUG''. If you want to test this, you can open a terminal, run ''xfce4-panel -q'' to exit the running instance. Then run ''PANEL_DEBUG=1 xfce4-panel'' and you will see the panel starts to output to //stderr//.

The messages look like ''xfce4-panel (<module>): <some message>''. It will print all sorts of information about panel positioning, plugins that are started, etc.

The value ''1'' enabled //default// logging, but some modules and plugins have more detailed logging that will normally clutter the log output. To show this you can specify the module name like ''PANEL_DEBUG=display-layout''.\\
Other valid debug //domains// are: //application, applicationsmenu, base-window, display-layout, external46, external, main, module-factory, module, positioning, struts, systray, tasklist//. You can also use //all// or combine options by creating a comma-separated list to show multiple domains in detail at the same time.

----

===== Debugging Plugins =====

If an external plugin has crashed, the panel will attempt to automatically restart the plugin, or ask the user what to do if the plugin has crashed more then once within 60 seconds. Nonetheless, we all know this should never happen, so the panel provides tools to help with debugging any issues that may occur with the plugins.

==== GDB ====

If you start the panel with ''PANEL_DEBUG=gdb'' and [[http://www.gnu.org/software/gdb/|gdb]] is installed on your computer, all external plugins will be started in ''gdb''. The output of //gdb// is written to ''/tmp/<stamp>_gdb_<plugin-name>_<plugin-id>.log''. If the plugin segfaults, it will automatically create a //backtrace full// and dump //info registers//.

This does not mean that the output contains valuable information. For good backtraces, it is still recommended to create a debug-build of the plugin.

==== Valgrind ====

To detect memory leaks and corruptions, it is also possible to run plugins in [[http://valgrind.org/|valgrind]]. For this, start the panel with ''PANEL_DEBUG=valgrind''. Logs will be written to the same location as the //gdb// logs.

==== Running the plugin as internal ====

When you don't just want to collect a backtrace after a crash, it can sometimes be more convenient to use the above debugging tools directly on the panel, running the plugin as internal (i.e. in the same process as the panel). It's also more convenient in this case to run only the plugin to be debugged on a single panel, which requires you to make a backup of your configuration beforehand.

The procedure is as follows:
  * Save the panel configuration via [[apps:xfce4-panel-profiles:start|xfce4-panel-profiles]].
  * Edit the plugin desktop file (normally located in ''/usr/share/xfce4/panel/plugins/'') to have ''X-XFCE-Internal=true'' (add line if necessary).
  * Create a new blank panel and delete all others.
  * Add the plugin to be debugged to the new panel.
  * Run ''xfce4-panel -q''.
  * Run ''gdb xfce4-panel'' or ''valgrind xfce4-panel'', with any appropriate options and/or environment variables.
  * When debugging is complete, restore configuration via xfce4-panel-profiles.

Note that some bugs may only appear when the plugin is run as internal or external. This is typically the case for bugs related to the way external plugins are embedded in the panel (XEmbed protocol on X11, embedded compositor or layer-shell window stacking on Wayland). However, the essential behavior of the plugin remains the same in both execution modes.

[[|Back to Top]]
----
[[:xfce:xfce4-panel:start:|Back to xfce4-panel main page]]