gstreamer/docs/manual/appendix-debugging.xml

<chapter id="chapter-debugging">
  <title>Debugging</title>
  <para> 
    GStreamer has an extensive set of debugging tools for
    plugin developers.
  </para>
 
  <sect1 id="section-debugging-command-line">
    <title>Command line options</title>
    <para> 
      Applications using the GStreamer libraries accept the following set
      of command line argruments that help in debugging.
    </para>
      
    <para> 
     <itemizedlist>
       <listitem>
         <para>
          <option>--gst-debug-help</option> 
	  Print available debug categories and exit
         </para>
       </listitem>
       <listitem>
         <para>
          <option>--gst-debug-level=<replaceable>LEVEL</replaceable></option> 
	  Sets the default debug level from 0 (no output) to 5 (everything)
         </para>
       </listitem>
       <listitem>
         <para>
          <option>--gst-debug=<replaceable>LIST</replaceable></option> 
	  Comma-separated list of category_name:level pairs to set specific
          levels for the individual categories. 
          Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3
         </para>
       </listitem>
       <listitem>
         <para>
          <option>--gst-debug-no-color</option> 
	  Disable color debugging output
         </para>
       </listitem>
       <listitem>
         <para>
          <option>--gst-debug-disable</option> 
	  Disable debugging
         </para>
       </listitem>
       <listitem>
         <para>
          <option>--gst-plugin-spew</option> 
	  Enable printout of errors while loading GStreamer plugins.
         </para>
       </listitem>
     </itemizedlist>
    </para>
  </sect1>

  <sect1 id="section-debugging-adding">
    <title>Adding debugging to a plugin</title>
    <para> 
Plugins can define their own categories for the debugging system.
Three things need to happen:
      <itemizedlist>
        <listitem>
          <para>
The debugging variable needs to be defined somewhere.
If you only have one source file, you can Use GST_DEBUG_CATEGORY_STATIC to
define a static debug category variable.
          </para>
          <para>
If you have multiple source files, you should define the variable using
GST_DEBUG_CATEGORY in the source file where you're initializing the debug
category.  The other source files should use GST_DEBUG_CATEGORY_EXTERN to
declare the debug category variable, possibly by including a common header
that has this statement.
          </para>
        </listitem>
        <listitem>
          <para>
The debugging category needs to be initialized.  This is done through
GST_DEBUG_CATEGORY_INIT.
If you're using a global debugging category for the complete plugin,
you can call this in the
plugin's <function>plugin_init</function>.
If the debug category is only used for one of the elements, you can call it
from the element's <function>_class_init</function> function.
          </para>
        </listitem>
        <listitem>
          <para>
You should also define a default category to be used for debugging.  This is
done by defining GST_CAT_DEFAULT for the source files where you're using
debug macros.
          </para>
        </listitem>
      </itemizedlist>
    </para> 
    <para> 
Elements can then log debugging information using the set of macros.  There
are five levels of debugging information:
      <orderedlist>
        <listitem>
<para>ERROR for fatal errors (for example, internal errors)</para>
        </listitem>
        <listitem>
<para>WARNING for warnings</para>
        </listitem>
        <listitem>
<para>INFO for normal information</para>
        </listitem>
        <listitem>
<para>DEBUG for debug information (for example, device parameters)</para>
        </listitem>
        <listitem>
<para>LOG for regular operation information (for example, chain handlers)</para>
        </listitem>
      </orderedlist>
    </para> 
    <para>
For each of these levels, there are four macros to log debugging information.
Taking the LOG level as an example, there is
      <itemizedlist>
        <listitem>
          <para>
          GST_CAT_LOG_OBJECT logs debug information in the given GstCategory
          and for the given GstObject
          </para>
        </listitem>
        <listitem>
          <para>
          GST_CAT_LOG logs debug information in the given GstCategory
          but without a GstObject (this is useful for libraries, for example)
          </para>
        </listitem>
        <listitem>
          <para>
          GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT
          category (as defined somewhere in the source), for the given GstObject
          </para>
        </listitem>
        <listitem>
          <para>
          GST_LOG logs debug information in the default GST_CAT_DEFAULT
          category, without a GstObject
          </para>
        </listitem>
      </itemizedlist>
    </para> 
  </sect1>

</chapter>