# Debugging

GStreamer has an extensive set of debugging tools for plugin developers.

## Command line options

Applications using the GStreamer libraries accept the following set of command line argruments that help in debugging.

- `--gst-debug-help` Print available debug categories and exit

- `--gst-debug-level=LEVEL` Sets the default debug level from 0 (no output) to 5 (everything)

- `--gst-debug=LIST` Comma-separated list of category_name:level pairs to set specific levels for the individual categories. Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3

- `--gst-debug-no-color` Disable color debugging output

- `--gst-debug-disable` Disable debugging

- `--gst-plugin-spew` Enable printout of errors while loading GStreamer plugins.

## Adding debugging to a plugin

Plugins can define their own categories for the debugging system. Three things need to happen:

- 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.

  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.

- 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 `plugin_init`. If the debug category is only used for one of the elements, you can call it from the element's `_class_init` function.

- 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.

Elements can then log debugging information using the set of macros. There are five levels of debugging information:

1. ERROR for fatal errors (for example, internal errors)

2. WARNING for warnings

3. INFO for normal information

4. DEBUG for debug information (for example, device parameters)

5. LOG for regular operation information (for example, chain handlers)

For each of these levels, there are four macros to log debugging information. Taking the LOG level as an example, there is

- GST_CAT_LOG_OBJECT logs debug information in the given GstCategory and for the given GstObject

- GST_CAT_LOG logs debug information in the given GstCategory but without a GstObject (this is useful for libraries, for example)

- GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT category (as defined somewhere in the source), for the given GstObject

- GST_LOG logs debug information in the default GST_CAT_DEFAULT category, without a GstObject