mariadb/README.debug

Debugging mysqld crashes
========================
Author: Michal Marek <mmarek@suse.cz>
Last modified: 2014-11-21

Contents
--------
1) Query log
2) Coredumps and Backtraces
3) Trace files

In case your MySQL server crashes, here are some hints on what to
include in a bugreport at https://bugzilla.novell.com/ . Please report
there only bugs in the MySQL packages packaged by Novell/SUSE, bugs in
binaries / source provided by MySQL AB should be reported at
http://bugs.mysql.com/ .

1) Query log
------------
  Note: Skip this chapter if you already have an exact query that
  crashes the server

To find out which query possibly crashed the server, add the following
line to your /etc/my.cnf into section [mysqld]:

    log=/var/lib/mysql/mysqld-query.log

Mysqld then will, at some performance cost, log all queries into this
file. After a server crash, you can examine the queries from the time it
crashed and try to reproduce the crash with single queries (this might
not allways work, eg. if the crash is caused by some race condition).

Note that this log file may become extremly large, so if you decide to
attach it whole to the bugzilla, don't forget to

    xz -k9 /var/lib/mysql/mysqld-query.log

and attach the xzipped file instead.

2) Coredumps and Backtraces
---------------------------
Another valuable information for the developers is the backtrace. The
easies way to get one is to let mysqld produce a coredump. Add the
following line to your /etc/my.cnf into section [mysqld]:

    core-file

The core file will be written to the /var/lib/mysql/ directory. I
suggest setting the kernel variable kernel.core_uses_pid to 1

    sysctl -w kernel.core_uses_pid=1

so that the coredumps don't overwrite each other if you experience
multiple crashes.

After you got the core file, install the gdb and mysql-debuginfo
packages and run

    gdb /usr/sbin/mysqld /var/lib/mysql/<core>
    (gdb) bt

Replace the <core> with the actual name of the coredump.

3) Trace files
--------------
The trace file will contain various debug information and function
calls/returns and will become _extremly_ huge after a while, so don't
attach it to bugzilla unless requested.

Add the following line to your /etc/my.cnf into section [mysqld]:

    stack-trace

The trace file will be then written to /var/lib/mysql directory.