Next: GstIterator, Previous: GstIndex, Up: Top
Debugging and logging facilities
GStreamer's debugging subsystem is an easy way to get information about what the application is doing. It is not meant for programming errors. Use GLib methods (g_warning and friends) for that.
The debugging subsystem works only after GStreamer has been initialized - for
example by calling gst-init.
The debugging subsystem is used to log informational messages while the
application runs. Each messages has some properties attached to it. Among these
properties are the debugging category, the severity (called "level" here) and an
optional <gobject> it belongs to. Each of these messages is sent to all
registered debugging handlers, which then handle the messages. GStreamer
attaches a default handler on startup, which outputs requested messages to
stderr.
Messages are output by using shortcut macros like <gst-debug>,
<gst-cat-error-object> or similar. These all expand to calling
gst-debug-log with the right parameters. The only thing a developer will
probably want to do is define his own categories. This is easily done with 3
lines. At the top of your code, declare the variables and set the default
category. After that you only need to initialize the category. Initialization
must be done before the category is used first. Plugins do this in their
plugin_init function, libraries and applications should do that during their
initialization.
GST_DEBUG_CATEGORY_STATIC (my_category); // define category (statically)
#define GST_CAT_DEFAULT my_category // set as default
GST_DEBUG_CATEGORY_INIT (my_category, "my category",
0, "This is my very own");
The whole debugging subsystem can be disabled at build time with passing the
–disable-gst-debug switch to configure. If this is done, every function, macro
and even structs described in this file evaluate to default values or nothing at
all. So don't take addresses of these functions or use other tricks. If you must
do that for some reason, there is still an option. If the debugging subsystem
was compiled out, <gst-disable-gst-debug> is defined in <gst/gst.h>, so
you can check that before doing your trick. Disabling the debugging subsystem
will give you a slight (read: unnoticeable) speed increase and will reduce the
size of your compiled code. The GStreamer library itself becomes around 10%
smaller.
Please note that there are naming conventions for the names of debugging
categories. These are explained at gst-debug-category-init.
<gst-debug-message*>) (ret mchars)Gets the string representation of a
<gst-debug-message>. This function is used in debug handlers to extract the message.
- message
- a debug message
- ret
- the string representation of a
<gst-debug-message>.
<gst-debug-category*>) (level <gst-debug-level>) (file mchars) (function mchars) (line int) (object <gobject>) (message <gst-debug-message*>) (unused <gpointer>)The default logging handler used by GStreamer. Logging functions get called whenever a macro like GST_DEBUG or similar is used. This function outputs the message and additional info using the glib error handler. You can add other handlers by using
gst-debug-add-log-function. And you can remove this handler by calling gst_debug_remove_log_function(gst_debug_log_default);
- category
- category to log
- level
- level of the message
- file
- the file that emitted the message, usually the __FILE__ identifier
- function
- the function that emitted the message
- line
- the line from that the message was emitted, usually __LINE__
- object
- the object this message relates to or NULL if none
- message
- the actual message
- unused
- an unused variable, reserved for some user_data.
<gst-debug-level>) (ret mchars)Get the string representation of a debugging level
- level
- the level to get the name for
- ret
- the name
bool)If activated, debugging messages are sent to the debugging handlers. It makes sense to deactivate it for speed issues.
This function is not threadsafe. It makes sense to only call it during initialization.
- active
- Whether to use debugging output or not
bool)Checks if debugging output is activated.
- ret
- TRUE, if debugging is activated
bool)Sets or unsets the use of coloured debugging output.
- colored
- Whether to use colored output or not
bool)Checks if the debugging output should be colored.
- ret
- TRUE, if the debug output should be colored.
<gst-debug-level>)Sets the default threshold to the given level and updates all categories to use this threshold.
- level
- level to set
<gst-debug-level>)Returns the default threshold that is used for new categories.
- ret
- the default threshold level
mchars) (level <gst-debug-level>)Sets all categories which match the given glob style pattern to the given level.
- name
- name of the categories to set
- level
- level to set them to
mchars)Resets all categories with the given name back to the default level.
- name
- name of the categories to set
<gst-debug-category*>) (level <gst-debug-level>)Sets the threshold of the category to the given level. Debug information will only be output if the threshold is lower or equal to the level of the debugging message.
Do not use this function in production code, because other functions may change the threshold of categories as side effect. It is however a nice function to use when debugging (even from gdb).
- category
- a
<gst-debug-category>to set threshold of.- level
- the
<gst-debug-level>threshold to set.
<gst-debug-category*>)Resets the threshold of the category to the default level. Debug information will only be output if the threshold is lower or equal to the level of the debugging message. Use this function to set the threshold back to where it was after using
gst-debug-category-set-threshold.
- category
- a
<gst-debug-category>to reset threshold of.
<gst-debug-category*>) (ret <gst-debug-level>)Returns the threshold of a
<gst-debug-category>.
- category
- a
<gst-debug-category>to get threshold of.- ret
- the
<gst-debug-level>that is used as threshold.
<gst-debug-category*>) (ret mchars)Returns the name of a debug category.
- category
- a
<gst-debug-category>to get name of.- ret
- the name of the category.
<gst-debug-category*>) (ret unsigned-int)Returns the color of a debug category used when printing output in this category.
- category
- a
<gst-debug-category>to get the color of.- ret
- the color of the category.
<gst-debug-category*>) (ret mchars)Returns the description of a debug category.
- category
- a
<gst-debug-category>to get the description of.- ret
- the description of the category.