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.

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.

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

The level defines the importance of a debugging message. The more important a
message is, the greater the probability that the debugging system outputs it.

GST_LEVEL_NONE

No debugging level specified or desired. Used to deactivate
debugging output.

GST_LEVEL_ERROR

Error messages are to be used only when an error occured
that stops the application from keeping working correctly.
An examples is gst_element_error, which outputs a message with this priority.
It does not mean that the application is terminating as with g_errror.

GST_LEVEL_WARNING

Warning messages are to inform about abnormal behaviour
that could lead to problems or weird behaviour later on. An example of this
would be clocking issues ("your computer is pretty slow") or broken input
data ("Can't synchronize to stream.")

GST_LEVEL_INFO

Informational messages should be used to keep the developer
updated about what is happening.
Examples where this should be used are when a typefind function has
successfully determined the type of the stream or when an mp3 plugin detects
the format to be used. ("This file has mono sound.")

GST_LEVEL_DEBUG

Debugging messages should be used when something common
happens that is not the expected default behavior, or something that's
useful to know but doesn't happen all the time (ie. per loop iteration or
buffer processed or event handled).
An example would be notifications about state changes or receiving/sending
of events.

GST_LEVEL_LOG

Log messages are messages that are very common but might be
useful to know. As a rule of thumb a pipeline that is iterating as expected
should never output anything else but LOG messages. Use this log level to
log recurring information in chain functions and loop functions, for
example.

GST_LEVEL_FIXME

Fixme messages are messages that indicate that something
in the executed code path is not fully implemented or handled yet. Note
that this does not replace proper error handling in any way, the purpose
of this message is to make it easier to spot incomplete/unfinished pieces
of code when reading the debug log. (Since: 0.10.23)

GST_LEVEL_TRACE

Tracing-related messages (Since: 0.10.30)
Examples for this are referencing/dereferencing of objects.

GST_LEVEL_MEMDUMP

memory dump messages are used to log (small) chunks of
data as memory dumps in the log. They will be displayed as hexdump with
ASCII characters. (Since: 0.10.23)

GST_LEVEL_COUNT

The number of defined debugging levels.

GST_LEVEL_DEFAULT

#define GST_LEVEL_DEFAULT GST_LEVEL_NONE

Defines the default debugging level to be used with GStreamer. It is normally
set to GST_LEVEL_NONE so nothing get printed.
As it can be configured at compile time, developer builds may chose to
override that though.
You can use this as an argument to gst_debug_set_default_threshold() to
reset the debugging output to default behaviour.

GST_STR_NULL()

#define GST_STR_NULL(str) ((str) ? (str) : "(NULL)")

Macro to use when a string must not be NULL, but may be NULL. If the string
is NULL, "(NULL)" is printed instead.
In GStreamer printf string arguments may not be NULL, because on some
platforms (ie Solaris) the libc crashes in that case. This includes debugging
strings.

str :

The string to check.

GST_DEBUG_PAD_NAME()

#define GST_DEBUG_PAD_NAME(pad)

Evaluates to 2 strings, that describe the pad. Often used in debugging
statements.

pad :

The pad to debug.

GST_FUNCTION

# define GST_FUNCTION ((const char*) (__FUNCTION__))

This macro should evaluate to the name of the current function and be should
be defined when configuring your project, as it is compiler dependant. If it
is not defined, some default value is used. It is used to provide debugging
output with the function name of the message.

Note that this is different from G_STRFUNC as we do not want the full
function signature in C++ code.

gst_debug_log_default ()

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 to stderr (or the log file specified via the
GST_DEBUG_FILE environment variable).

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__

message :

the actual message

object :

the object this message relates to,
or NULL if none. [transfer none][allow-none]

GST_DEBUG_CATEGORY_STATIC()

Defines a static GstDebugCategory variable.
This macro expands to nothing if debugging is disabled.

cat :

the category

GST_DEBUG_CATEGORY_INIT()

#define GST_DEBUG_CATEGORY_INIT(cat,name,color,description)

Initializes a new GstDebugCategory with the given properties and set to
the default threshold.

Note

This macro expands to nothing if debugging is disabled.

When naming your category, please follow the following conventions to ensure
that the pattern matching for categories works as expected. It is not
earth-shattering if you don't follow these conventions, but it would be nice
for everyone.

If you define a category for a plugin or a feature of it, name the category
like the feature. So if you wanted to write a "filesrc" element, you would
name the category "filesrc". Use lowercase letters only.
If you define more than one category for the same element, append an
underscore and an identifier to your categories, like this: "filesrc_cache"

If you create a library or an application using debugging categories, use a
common prefix followed by an underscore for all your categories. GStreamer
uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure
to include uppercase letters.

cat :

the category to initialize.

name :

the name of the category.

color :

the colors to use for a color representation or 0 for no color.

description :

optional description of the category.

GST_DEBUG_CATEGORY_GET()

#define GST_DEBUG_CATEGORY_GET(cat,name)

Looks up an existing GstDebugCategory by its name and sets cat. If the
category is not found, but GST_CAT_DEFAULT is defined, that is assigned to
cat. Otherwise cat will be NULL.

gst_debug_category_reset_threshold ()

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

GST_DEBUG_BIN_TO_DOT_FILE()

To aid debugging applications one can use this method to write out the whole
network of gstreamer elements that form the pipeline into an dot file.
This file can be processed with graphviz to get an image.

1

dot -Tpng -oimage.png graph_lowlevel.dot

The macro is only active if gstreamer is configured with
"--gst-enable-gst-debug" and the environment variable
GST_DEBUG_DUMP_DOT_DIR is set to a basepath (e.g. /tmp).