QA/BugReport/Debug Information

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

Other languages:

This page describes Debug Information that you may wish to provide to the developers when submitting a BugReport.

This is ADVANCED Stuff

Please don't feel obligated to provide any of this information, unless

You're a developer/programmer and know what this stuff means
A developer or someone in QA has explicitly asked you to provide this information
You're on the QA Team

Debugging Information by OS

These instructions are all pretty OS-specific, so we'll split up the rest of this page by OS.

GNU/Linux

In order to produce these various debugging logs, you should first install the debugging packages. Please consult the debugging guide of your Linux distribution:

Another option is to roll your own debug build using --enable-debug or --enable-symbols. The latter doesn't change program logic, disable optimizations, and doesn't enable additional assertions/checks that the --enable-debug switch does.

A third option is to download a daily built debug build and run it. They can be found here, in folders that ends with -dbg. Please be aware that the download will be 1.6GB+ and when extracted it takes up ~5GB.

GNU/Linux: How to get a backtrace

The backtrace is useful for analysing the reasons why an application crashes or freezes. The backtrace can be run without the debugging packages, but it wont be as useful, but still could potentially provide at least some information. You might use the following steps:

NOTE: Before you launch LibreOffice in debug mode, make sure gdbtrace.log doesn't exist in the folder where you are launching LibreOffice from, otherwise, delete it!

start a terminal / shell (in some distros you can press Ctrl + Alt + T to do this)
run `$ soffice --backtrace`
if you see the cursor blink on a line that starts with `(gdb)`, then type 'run' and then enter (this happens when a user profile isn't present)
reproduce the crash or hang. If its a hang, you will need to force a crash, so open another console and type `$ pkill -15 soffice.bin` or alternatively type `$ xkill` and click on the hung libreoffice window.
if you are not returned back to the default prompt and are on a line with a blinking cursor, if it displays a line ending with '?? ()' type 'c', if not type 'bt' and then enter. If instead you are at a line that starts with `(gdb)`, type 'quit' to return to the prompt.
a gdbtrace.log file will be created in the same folder.
attach gdbtrace.log to the bug report.

You can ignore the warnings about declined auto-loading of .py files. These pretty printers are only useful in interactive debug sessions. The --backtrace option of the soffice script runs gdb with the -nx option, which will ignore any .gdbinit files and the auto-load commands they might contain.

Alternatively, you can attach gdb to the soffice.bin process after starting LibreOffice. If you have only one LibreOffice process running, you can attach to it quickly like this: gdb --pid `pgrep soffice`

GNU/Linux: How to get an strace log

strace traces the system calls that a process makes. If there is some problem around file-I/O this can be a great way of detecting exactly what is going on at an operating-system level. It's also a fast way to see whether the program continues executing and/or has hung, and finding information about the system LibreOffice is run on.

start a terminal
soffice --strace
reproduce your problem
compress the log: bzip2 strace.log
now attach the strace.log.bz2 file that is produced to the bug report.

GNU/Linux: How to get an ld.so log

For problems caused by shared libraries failing to be found, failing to load, wrong libraries being loaded, or crashing due to exported symbol collisions in the global ELF namespace, it's often useful to have a log from ld.so. The most useful option is LD_DEBUG=libs but LD_DEBUG=files is also helpful in rarer cases.

rm lddebug* # delete any stale logs from last time
LD_DEBUG=libs LD_DEBUG_OUTPUT=lddebug soffice
reproduce your problem
ls -l lddebug*
there will be one file per process; the interesting one is the one for the main soffice.bin process, which is typically by far the largest in size
attach the largest lddebug.N file to the bug report

GNU/Linux: How to get a Valgrind log

The valgrind log is invaluable for tracing obscure memory corruption errors that can be extremely difficult to find otherwise. It achieves this by emulating a CPU. The slight downside of that is that the code runs around eighty (80x) slower, which will seem slow to you. The plus side is that it shows us problems that are un-findable in any other way, and that the traces produced very often pinpoint the issue in such a way that it is rather easy for a developer to fix: your patience is much appreciated. Valgrind can also produce a number of false-positives.

install the valgrind package
start a terminal
soffice --valgrind >& /tmp/valgrind.log
be patient ... 80x is a lot slower ... reproduce the problem.
attach /tmp/valgrind.log to the bug report.

If you want to specify some additional options for valgrind, you can use VALGRIND_OPTS environment variable.

GNU/Linux: How to get a callgrind trace

A callgrind trace will immediately point the finger at poorly performing pieces of code and uses valgrind to model a CPU, so requires the installation of the valgrind package. This type of trace provides a hierarchical, navigable histogram view of where the time is spent in the code, which can be viewed in apps like kcachegrind. Callgrind traces are a CPU intensive process and LibreOffice will run many times slower than it normally does, so it shouldnt be undertaken by a user with a slow PC. In addition to a fast PC, LibreOffice will need to be built with --enable-symbols and not --enable-dbgutil or --enable-debug, as debug builds behave very abnormally with respect to performance.

start a terminal in the LibreOffice program folder (e.g. ~/core/instdir/program)
`$ VALGRIND=callgrind ./soffice`

If the problem you are tracing is the slow opening time of a document, you might want to set this environment variable to immediately exit after opening:

`$ export OOO_EXIT_POST_STARTUP=1`

After running the trace and exiting cleanly (in extremes press ctrl + c only once! in the terminal), you will find a large file called: callgrind.out.12345 where 12345 is the PID. Compress this file and attach it to the bug report or upload it somewhere for a developer to access.

A --enable-symbols build of LibreOffice will add an extra ~10GB to an existing build system as the symbols will be added to .so files in the instdir folder and .o files in the workdir. The symbols can be removed these files by running strip on the files or by removing the instdir and workdir folders and rebuilding.

There is a way to speed up the tracing and make it only include relevant data:

Launch with VALGRIND="callgrind --instr-atstart=no" ./soffice
Prepare to do the thing that you want to trace in LibreOffice
In another terminal, give the command callgrind_control -i on
Do the thing you want to trace
In the other terminal, give the command callgrind_control -d
Stop the tracing and kill LibreOffice by callgrind_control -k

An alternative to callgrind is perf. Its output is not as detailed as callgrind's, but as it runs much faster, you might prefer it over callgrind in many cases.

Windows

Windows: How to get a backtrace

If you have LibreOffice 4.2.0 or higher installed and your version includes debugging functionality, there is a test symbol server containing the corresponding debugging symbols. Read How to get a backtrace with WinDbg to set up the debugging environment and you can also watch this video to help understand the process.

Windows: how to get OpenGL debug output

Download and install a build with debugging features, eg.: https://dev-builds.libreoffice.org/daily/master/Win-x86@39/current/
Download and install cygwin (only the minimum default base): https://cygwin.com/setup-x86_64.exe
In the cygwin command line, give this command to set a logging environment variable: set SAL_LOG=+INFO.vcl.opengl+WARN
You might want to change directory to the LibreOffice program folder like so: cd "/cygdrive/c/Program Files (x86)/LibreOfficeDev 6/program"
From the same command line window, launch LibreOffice with this command (add the full path, if launching outside the program folder): ./soffice.exe --calc 2> soffice.log

Now try to reproduce your OpenGL problem. Debug output will be written to the soffice.log file, which you can then attach to a bug report.

Windows: how to get OpenCL debug output

See above, except use set SAL_LOG=+INFO.opencl+INFO.sc.opencl+WARN as the environment variable.

You can also use this program to print OpenCL information to a file: http://dev-www.libreoffice.org/opencl/Windows/Opencl%20Info.exe

Windows: Debugging a GDI Resource Leak ( vcl::Window::dispose() )

By default, the limit of unique GDI objects in memory at the same time is 10.000 and if LibreOffice reaches it we might experience a vcl::Window::dispose() crash. It might be specially problematic at save time, when LibreOffice might create thousands of VirtualDevices. In order to check whether we have reach the limit of GDI object in memory we can follow step 1 in this page or use an application called GDI handles.

In case we confirm the limit has been reached, we can follow steps 2, 3 and 4 from this page to provide further debugging information.

Example: Bug 102688

Windows: how to trace a memory corruption with DrMemory

Read the section in the development debugging article.

Windows: how to get an ETW performance trace

Event Tracing for Windows (ETW) is a powerful tool for investigating performance issues. UIforETW makes it easy to use. Read more about it on Bruce Dawson's blog.

For performance profiling, you should either use a release build or your own build done with --enable-symbols. Builds done with --enable-debug or --enable-dbgutil should NOT be used. Therefore, do not use the daily builds produced by Tinderbox 39.

Instructions for setting up UIforETW:

Download the latest release of UIforETW
Unzip the release somewhere
Run bin/UIforETW.exe or UIforETW32.exe depending on the bitness of your LibreOffice build
Click Start Tracing
Run LibreOffice and do whatever it is you want to investigate
Save Trace Buffers in UIforETW at some point
Right-click the trace shown in the Traces section at the bottom and select Open Trace in WPA 10
In WPA, open the menu item Trace - Configure symbol paths

Click + and input this when using a release build:

CACHE*C:\symbols;SRV*http://dev-downloads.libreoffice.org/symstore/symbols;SRV*http://msdl.microsoft.com/download/symbols

or this, if using a home-baked build:

CACHE*C:\symbols;SRV*http://msdl.microsoft.com/download/symbols

Trace - Load symbols. Note that this will take time and several gigabytes of storage space.
In the bottom panel, click next to CPU Usage (Sampled). Default is "Randomascii inclusive (stack)". Set it to Flame by Process, Stack*
Search for the soffice.bin process: Right click -> Filter to Selection
Press Ctrl+Shift+G (Display Graph only)
Click the maximize icon
From the "Select chart type" icon (between "Select view preset" and "Quick search"), you can change the type to Flame

The traces can be very thorough, note this functionality in UIforETW: Input tracing: If this is set to Private or Full then all mouse move and mouse-click events will be recorded in the trace and will show up in the Generic Events graph. If set to Full then all key presses will be fully recorded, whereas if set to Private all letters will be recorded as ‘A’ and all numbers will be recorded as ‘0’.

The saved trace buffers appear as .etl files in the directory C:\Users\username\Documents\etwtraces The files can be shared in Bugzilla for others to examine in Windows Performance Analyzer.

macOS

macOS: How to get debug information

The debug information is useful for analyzing the reasons why an application crashes or freezes. On macOS, you can receive the standard debug information very simply, without installing any additional software. (This information even includes a simple stack trace, which misses full symbols, but can nevertheless be very useful.)

The exact steps vary depending on your macOS version and setup, but in general you get the debug information as follows:

When an application crashes, macOS prompts you with a dialog window saying “LibreOffice quit unexpectedly.” and asks you if you want to send a report to Apple. Click on the button labelled “Report…”. Now a larger window with the title “Problem Report for LibreOffice” opens; under “Problem Details and System Configuration”, you find an edit field with a long text containing much technical details. You can just click into this long text, press ⌘ Cmd + a to select all the text, then press ⌘ Cmd + c to copy it and then switch to any text editor (e.g. Apple's TextEdit) and press ⌘ Cmd + v to insert the text. Then you can save the text as a new file; the best would be to use a plain text (.txt) format. Please attach that file to your bug report. (You do not need to send the report to Apple, so click on the “Don't Send” in the “Problem Report” window.)

When an application hangs or freezes, you can force quit it by pressing ⌘ Cmd + Alt + Esc. macOS prompts you with a dialog window entitled “Force Quit Applications”, asking which application(s) you want to quit; in that list, you can recognize the application which hangs or freezes often by the hint “(not responding)”. Select it and click the button “Force quit”. Depending on your system configuration, you will be asked if you want to send a report about that to Apple; if you confirm this, you will get the same “Problem Report” window as described above, and can copy and save the debug information text in the same way.

NB: Depending on your system configuration and user setup, you may or may not be asked about sending a report to Apple; you may need to be logged in as an admin user to see these dialogs.

If the report dialog has shown before, one may find prior crash reports in:

~/Library/Logs/DiagnosticReports/

The file would look something like:

soffice-YYYY-MM-DD-155234.ips

An alternative way is using the Activity Monitor application.

Regarding the linked instructions, the one change in newer versions of macOS is that the Sample Process toolbar button has moved. Now there is a … toolbar button. Click on that button and select Sample Process in the popup dialog that appears.

Paste and clipboard issues

If there's a paste problem from external, not easily obtainable app, like a huge commercial program, QA and devs will hardly obtain specific app to test. Solution is to use clipboard manager to save info when copied from that program, so that paste can be tested any time without original program. Recommended is clipboard manager that works on multiple operating systems, specifically CopyQ. Result of .cpq should be attached to bug report.