Difference between revisions of "Core file"

From collectd Wiki
Jump to: navigation, search
m (Inspecting the core file: Markup fix.)
Line 1: Line 1:
 +
=[http://ehyloxame.co.cc Under Construction! Please Visit Reserve Page. Page Will Be Available Shortly]=
 
A '''core file''' or '''core dump''' is a dump of the application state, including all memory contents, to the disk for further inspection. If ''collectd'' crashes due to a bug, the best way to debug this is via such a file. Using a ''debugger'' it is possible to find out where exactly the problem occurred and under which circumstances.
 
A '''core file''' or '''core dump''' is a dump of the application state, including all memory contents, to the disk for further inspection. If ''collectd'' crashes due to a bug, the best way to debug this is via such a file. Using a ''debugger'' it is possible to find out where exactly the problem occurred and under which circumstances.
  
Line 23: Line 24:
 
If you installed collectd from source or your distribution doesn't provide a debugging package, you can recompile with the appropriate compiler flags.
 
If you installed collectd from source or your distribution doesn't provide a debugging package, you can recompile with the appropriate compiler flags.
  
The exact flags required depend on the compiler used. If you use the C compiler from the ''GNU Compiler Collection'' (GCC), the flag <code>-g</code> enables the inclusion of debugging symbols. While you're at it, disable optimization using <code>-O0</code>. This makes it easier to interpret the output of the debugger.
+
The exact flags required depend on the compiler used. If you use the C compiler from the ''GNU Compiler Collection'' (GCC), the flag &lt;code&gt;-g&lt;/code&gt; enables the inclusion of debugging symbols. While you're at it, disable optimization using &lt;code&gt;-O0&lt;/code&gt;. This makes it easier to interpret the output of the debugger.
  
 
Pass the flags to the ''configure'' script using:
 
Pass the flags to the ''configure'' script using:
  $ ./configure ''$OTHER_FLAGS'' CFLAGS="-g -O0"
+
  $ ./configure ''$OTHER_FLAGS'' CFLAGS=&quot;-g -O0&quot;
  
 
Other compilers may differ. If you know how, please add the information here.
 
Other compilers may differ. If you know how, please add the information here.
Line 34: Line 35:
 
Many distributions disable the creation of ''core files'' by default, so that the disk isn't filled with useless files if the user doesn't know how to use them.
 
Many distributions disable the creation of ''core files'' by default, so that the disk isn't filled with useless files if the user doesn't know how to use them.
  
The size of the biggest core file allowed to be written to disk is controlled via <code>ulimit&nbsp;-c</code>. If creation of ''core files'' is disabled, you will get the following output:
+
The size of the biggest core file allowed to be written to disk is controlled via &lt;code&gt;ulimit&amp;nbsp;-c&lt;/code&gt;. If creation of ''core files'' is disabled, you will get the following output:
  
 
  $ ulimit -c
 
  $ ulimit -c
 
  0
 
  0
  
This means that ''core dumps'' are only written if their size is smaller than ''0&nbsp;blocks'', i.e. never. You can increase this limit to a reasonable size or use ''unlimited'' to force the creation of a ''core file'' regardless of its size:
+
This means that ''core dumps'' are only written if their size is smaller than ''0&amp;nbsp;blocks'', i.e. never. You can increase this limit to a reasonable size or use ''unlimited'' to force the creation of a ''core file'' regardless of its size:
  
 
  $ ulimit -c unlimited
 
  $ ulimit -c unlimited
Line 49: Line 50:
 
=== Debian/Ubuntu ===
 
=== Debian/Ubuntu ===
  
Under ''Debian GNU/Linux'' and ''Ubuntu'', creation of ''core files'' is controlled via the file <code>/etc/default/collectd</code>. You can enable the creation of ''core dumps'' by setting:
+
Under ''Debian GNU/Linux'' and ''Ubuntu'', creation of ''core files'' is controlled via the file &lt;code&gt;/etc/default/collectd&lt;/code&gt;. You can enable the creation of ''core dumps'' by setting:
  
 
  ENABLE_COREFILES=1
 
  ENABLE_COREFILES=1
Line 55: Line 56:
 
== Waiting for a crash ==
 
== Waiting for a crash ==
  
After restarting the daemon with ''core files'' enabled, all you have to do is wait for the daemon to crash again. Until this happens, the core file creation doesn't effect the performance of the daemon. (If you recompiled with <code>-O0</code> the daemon may use a bit more CPU time due to inferior code efficiency, but this has nothing to do with the ''ulimit'' setting.)
+
After restarting the daemon with ''core files'' enabled, all you have to do is wait for the daemon to crash again. Until this happens, the core file creation doesn't effect the performance of the daemon. (If you recompiled with &lt;code&gt;-O0&lt;/code&gt; the daemon may use a bit more CPU time due to inferior code efficiency, but this has nothing to do with the ''ulimit'' setting.)
  
 
=== Locating the core file ===
 
=== Locating the core file ===
  
Once the daemon crashed, a file called <code>core</code> or <code>core.''$PID''</code> will be created in its ''current working directory''. This directory can be set using the [[BaseDir]] setting. By default, this is <code>''$pkglocalstatedir''</code>, i.e. <code>''$prefix''/var/lib/collectd</code>. If you installed a package, this directory is most likely <code>/var/lib/collectd</code>.
+
Once the daemon crashed, a file called &lt;code&gt;core&lt;/code&gt; or &lt;code&gt;core.''$PID''&lt;/code&gt; will be created in its ''current working directory''. This directory can be set using the [[BaseDir]] setting. By default, this is &lt;code&gt;''$pkglocalstatedir''&lt;/code&gt;, i.e. &lt;code&gt;''$prefix''/var/lib/collectd&lt;/code&gt;. If you installed a package, this directory is most likely &lt;code&gt;/var/lib/collectd&lt;/code&gt;.
  
 
== Inspecting the core file ==
 
== Inspecting the core file ==
Line 69: Line 70:
 
  $ gdb ''$path_to''/collectd ''$path_to''/core
 
  $ gdb ''$path_to''/collectd ''$path_to''/core
  
This will tell the debugger that we want to inspect the ''collectd'' executable and that the state should be read from the ''core file'' that was created. Please make sure to use the ''collectd'' executable that actually created the ''core file'' &ndash; else, the information provided by the debugger will be bogus. I.&nbsp;e., after recompiling collectd, you'll have to recreate the core file.
+
This will tell the debugger that we want to inspect the ''collectd'' executable and that the state should be read from the ''core file'' that was created. Please make sure to use the ''collectd'' executable that actually created the ''core file'' &amp;ndash; else, the information provided by the debugger will be bogus. I.&amp;nbsp;e., after recompiling collectd, you'll have to recreate the core file.
  
If you know how to work with a debugger, knock yourself out and [[Submitting patches|submit a patch]]. If not, just create the most useful information for a start and send it to the [[mailing list]]. The most useful information is, at first, a ''stack backtrace''.  When using ''gdb'', a ''stack backtrace'' is printed with <code>backtrace full</code>:
+
If you know how to work with a debugger, knock yourself out and [[Submitting patches|submit a patch]]. If not, just create the most useful information for a start and send it to the [[mailing list]]. The most useful information is, at first, a ''stack backtrace''.  When using ''gdb'', a ''stack backtrace'' is printed with &lt;code&gt;backtrace full&lt;/code&gt;:
  
 
  (gdb) backtrace full
 
  (gdb) backtrace full

Revision as of 02:07, 24 November 2010

Under Construction! Please Visit Reserve Page. Page Will Be Available Shortly

A core file or core dump is a dump of the application state, including all memory contents, to the disk for further inspection. If collectd crashes due to a bug, the best way to debug this is via such a file. Using a debugger it is possible to find out where exactly the problem occurred and under which circumstances.

In order to create and use a core file, you need to take the following steps:

  • Create an executable with debugging symbols. You can either re-compile with special flags or install a debugging package if one is available.
  • Enable creation of core files.
  • Wait until the daemon crashes again.
  • Inspect the core file to find the source of the problem.

Debugging symbols

In order to get meaningful information from a core file, the executable must be built with debugging symbols.

From a package

The easiest way to obtain debugging symbols is by installing an appropriate debugging package. If you're using Debian or Ubuntu, you can install such a debugging package using:

$ apt-get install collectd-dbg

Other distributions may provide debugging packages, too. If you know of such a distribution, please add the information here.

Compiler flags

If you installed collectd from source or your distribution doesn't provide a debugging package, you can recompile with the appropriate compiler flags.

The exact flags required depend on the compiler used. If you use the C compiler from the GNU Compiler Collection (GCC), the flag <code>-g</code> enables the inclusion of debugging symbols. While you're at it, disable optimization using <code>-O0</code>. This makes it easier to interpret the output of the debugger.

Pass the flags to the configure script using:

$ ./configure $OTHER_FLAGS CFLAGS="-g -O0"

Other compilers may differ. If you know how, please add the information here.

Enabling core files

Many distributions disable the creation of core files by default, so that the disk isn't filled with useless files if the user doesn't know how to use them.

The size of the biggest core file allowed to be written to disk is controlled via <code>ulimit&nbsp;-c</code>. If creation of core files is disabled, you will get the following output:

$ ulimit -c
0

This means that core dumps are only written if their size is smaller than 0&nbsp;blocks, i.e. never. You can increase this limit to a reasonable size or use unlimited to force the creation of a core file regardless of its size:

$ ulimit -c unlimited
$ ulimit -c
unlimited

Please note that this change only effects the shell it was issues from and the programs started from it. The setting it not global. You need to restart the daemon from this shell or add the ulimit-line to the init-script for the changes to take effect.

Debian/Ubuntu

Under Debian GNU/Linux and Ubuntu, creation of core files is controlled via the file <code>/etc/default/collectd</code>. You can enable the creation of core dumps by setting:

ENABLE_COREFILES=1

Waiting for a crash

After restarting the daemon with core files enabled, all you have to do is wait for the daemon to crash again. Until this happens, the core file creation doesn't effect the performance of the daemon. (If you recompiled with <code>-O0</code> the daemon may use a bit more CPU time due to inferior code efficiency, but this has nothing to do with the ulimit setting.)

Locating the core file

Once the daemon crashed, a file called <code>core</code> or <code>core.$PID</code> will be created in its current working directory. This directory can be set using the BaseDir setting. By default, this is <code>$pkglocalstatedir</code>, i.e. <code>$prefix/var/lib/collectd</code>. If you installed a package, this directory is most likely <code>/var/lib/collectd</code>.

Inspecting the core file

Once the core file has been created, a debugger is used to examine the file in order to find the problem. We'll talk about the standard debugger under GNU/Linux, the GNU Debugger (gdb) here. On other systems, you may use a different debugger, such as dbx under Solaris.

Start the debugger with:

$ gdb $path_to/collectd $path_to/core

This will tell the debugger that we want to inspect the collectd executable and that the state should be read from the core file that was created. Please make sure to use the collectd executable that actually created the core file &ndash; else, the information provided by the debugger will be bogus. I.&nbsp;e., after recompiling collectd, you'll have to recreate the core file.

If you know how to work with a debugger, knock yourself out and submit a patch. If not, just create the most useful information for a start and send it to the mailing list. The most useful information is, at first, a stack backtrace. When using gdb, a stack backtrace is printed with <code>backtrace full</code>:

(gdb) backtrace full

Just copy that output to a file and send us an email.