gstreamer基础教程11-Debugging tools

索引：https://blog.youkuaiyun.com/knowledgebao/article/details/84621238

Goal

有事我们会出现一些错误，GSteam会给我们提供一些调试信息帮助我们来定位问题。主要包括：如何获取更多调试信息，如何将调试信息打印到日志里，如何获取pipeline图。

Sometimes things won’t go as expected and the error messages retrieved from the bus (if any) just don’t provide enough information. Luckily, GStreamer ships with附带 massive amounts of大量的 debug information, which usually hint暗示 what the problem might be. This tutorial shows:

• How to get more debug information from GStreamer.

• How to print your own debug information into the GStreamer log.

• How to get pipeline graphs

Printing debug information

The debug log

GStreamer的调试信息包括：时间，代码所在文件名，代码行号，函数名等信息。下边是一条日志信息。

GStreamer and its plugins插件 are full of debug traces, this is, places in the code where a particularly interesting piece of information is printed to the console, along with time stamping, process, category, source code file, function and element information.

The debug output is controlled with the GST_DEBUG environment variable. Here’s an example with GST_DEBUG=2:

0:00:00.868050000  1592   09F62420 WARN                 filesrc gstfilesrc.c:1044:gst_file_src_start:<filesrc0> error: No such file "non-existing-file.webm"

GStream的日志信息非常全面，如果全部开启，可能会使控制栏卡死或者文件卡死。可以通过日志等级来定义显示哪些信息。

日志分类通过设置环境变量GST_DEBUG来实现：0：无错误。1：致命错误。2，警告。3：需要修复的。4，信息(流程性的)。5：调试信息。6：所有message。7：跟踪信息。8：堆栈信息。其中等级是包含关系，比如设置level为4的话，1,2,3,4类型的信息都会打印。

可以针对指定的element进行日志等级设置，可以通过通配符*设置包含指定内容的element的日志等级。GStream日志可以写到文件里边，通过对日志文件的检索，定位问题原因。

As you can see, this is quite a bit of information. In fact, the GStreamer debug log is so verbose冗余, that when fully enabled it can render致使 applications unresponsive (due to the console scrolling) or fill up megabytes百万字节 of text files (when redirected to a file). For this reason, the logs are categorized分类, and you seldom很少 need to enable all categories at once.

The first category is the Debug Level, which is a number specifying the amount of desired output:

| # | Name    | Description                                                    |
|---|---------|----------------------------------------------------------------|
| 0 | none    | No debug information is output.                                |
| 1 | ERROR   | Logs all fatal errors. These are errors that do not allow the  |
|   |         | core or elements to perform the requested action. The          |
|   |         | application can still recover if programmed to handle the      |
|   |         | conditions that triggered the error.                           |
| 2 | WARNING | Logs all warnings. Typically these are non-fatal, but          |
|   |         | user-visible problems are expected to happen.                  |
| 3 | FIXME   | Logs all "fixme" messages. Those typically that a codepath that|
|   |         | is known to be incomplete has been triggered. It may work in   |
|   |         | most cases, but mauy cause problems in specific instances.     |
| 4 | INFO    | Logs all informational messages. These are typically used for  |
|   |         | events in the system that only happen once, or are important   |
|   |         | and rare enough to be logged at this level.                    |
| 5 | DEBUG   | Logs all debug messages. These are general debug messages for  |
|   |         | events that happen only a limited number of times during an    |
|   |         | object's lifetime; these include setup, teardown, change of    |
|   |         | parameters, etc.                                               |
| 6 | LOG     | Logs all log messages. These are messages for events that      |
|   |         | happen repeatedly during an object's lifetime; these include   |
|   |         | streaming and steady-state conditions. This is used for log    |
|   |         | messages that happen on every buffer in an element for example.|
| 7 | TRACE   | Logs all trace messages. Those are message that happen very    |
|   |         | very often. This is for example is each each time the reference|
|   |         | count of a GstMiniObject, such as a GstBuffer or GstEvent, is  |
|   |         | modified.                                                      |
| 8 | MEMDUMP | Logs all memory dump messages. This is the heaviest logging and|
|   |         | may include dumping the content of blocks of memory.           |
+------------------------------------------------------------------------------+

To enable debug output, set the GST_DEBUG environment variable to the desired debug level. All levels below that will also be shown (i.e., if you set GST_DEBUG=2, you will get both ERROR and WARNING messages).

Furthermore, each plugin or part of the GStreamer defines its own category, so you can specify a debug level for each individual category. For example, GST_DEBUG=2,audiotestsrc:6, will use Debug Level 6 for the audiotestsrc element, and 2 for all the others.

The GST_DEBUG environment variable, then, is a comma-separated list of category:level pairs, with an optional levelat the beginning, representing the default debug level for all categories.

The '*' wildcard通配符 is also available. For example GST_DEBUG=2,audio*:6 will use Debug Level 5 for all categories starting with the word audio. GST_DEBUG=*:2 is equivalent to GST_DEBUG=2.

Use gst-launch-1.0 --gst-debug-help to obtain the list of all registered categories. Bear in mind that each plugin registers its own categories, so, when installing or removing plugins, this list can change.

Use GST_DEBUG when the error information posted on the GStreamer bus does not help you nail down确定 a problem. It is common practice to redirect the output log to a file, and then examine it later, searching for specific messages.

GStreamer allows for custom debugging information handlers but when using the default one, the content of each line in the debug output looks like:

0:00:00.868050000  1592   09F62420 WARN                 filesrc gstfilesrc.c:1044:gst_file_src_start:<filesrc0> error: No such file "non-existing-file.webm"

And this is how the information formatted:

| Example          | Explained                                                 |
|------------------|-----------------------------------------------------------|
|0:00:00.868050000 | Time stamp in HH:MM:SS.sssssssss format since the start of|
|                  | the program.                                              |
|1592              | Process ID from which the message was issued. Useful when |
|                  | your problem involves multiple processes.                 |
|09F62420          | Thread ID from which the message was issued. Useful when  |
|                  | your problem involves multiple threads.                   |
|WARN              | Debug level of the message.                               |
|filesrc           | Debug Category of the message.                            |
|gstfilesrc.c:1044 | Source file and line in the GStreamer source code where   |
|                  | this message was issued.                                  |
|gst_file_src_start| Function that issued the message.                         |
|<filesrc0>        | Name of the object that issued the message. It can be an  |
|                  | element, a pad, or something else. Useful when you have   |
|                  | multiple elements of the same kind and need to distinguish|
|                  | among them. Naming your elements with the name property   |
|                  | makes this debug output more readable but GStreamer       |
|                  | assigns each new element a unique name by default.        |
| error: No such   |                                                           |
| file ....        | The actual message.                                       |
+------------------------------------------------------------------------------+

Adding your own debug information

通过宏GST_DEBUG_CATEGORY_INIT以及GST_ERROR(), GST_WARNING(), GST_INFO(), GST_LOG() and GST_DEBUG()可以利用GStream的日志系统添加自己的调试信息。GST_DEBUG_CATEGORY_INIT需要在gst_init()之后调用。

In the parts of your code that interact with相互作用 GStreamer, it is interesting to use GStreamer’s debugging facilities. In this way, you have all debug output in the same file and the temporal relationship between different messages is preserved.

To do so, use the GST_ERROR(), GST_WARNING(), GST_INFO(), GST_LOG() and GST_DEBUG() macros. They accept the same parameters as printf, and they use the default category (default will be shown as the Debug category in the output log).

To change the category to something more meaningful, add these two lines at the top of your code:

GST_DEBUG_CATEGORY_STATIC (my_category);
#define GST_CAT_DEFAULT my_category

And then this one after you have initialized GStreamer with gst_init():

GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");

This registers a new category (this is, for the duration of your application: it is not stored in any file), and sets it as the default category for your code. See the documentation for GST_DEBUG_CATEGORY_INIT().

Getting pipeline graphs

获取通道构件图。.dot图片文件可以自动生成。(.dot是一种类似于visio的图片文件，使用开源工具GraphViz可以打开，会显示控件之间的关联)

通过设置环境变量GST_DEBUG_DUMP_DOT_DIR，设置图片.dot的存储目录后，gst-launch-1.0在每次状态变化的时候，自动创建.dot文件。g_setenv("GST_DEBUG_DUMP_DOT_DIR", "/home/test", TRUE);切记：此函数必须在gst_init (&argc, &argv)之前调用。包括一些其他环境变量应该也一样需要放在init之前。

开发人员也可以通过宏GST_DEBUG_BIN_TO_DOT_FILE()、GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS()实时生成.dot文件。

For those cases where your pipeline starts to grow too large and you lose track of what is connected with what, GStreamer has the capability to output graph files. These are .dot files, readable with free programs like GraphViz, that describe the topology of your pipeline, along with the caps negotiated in each link.

This is also very handy when using all-in-one elements like playbin or uridecodebin, which instantiate several elements inside them. Use the .dot files to learn what pipeline they have created inside (and learn a bit of GStreamer along the way).

To obtain获取 .dot files, simply set the GST_DEBUG_DUMP_DOT_DIR environment variable to point to the folder where you want the files to be placed. gst-launch-1.0 will create a .dot file at each state change, so you can see the evolution of the caps negotiation. Unset the variable to disable this facility. From within your application, you can use the GST_DEBUG_BIN_TO_DOT_FILE() and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS() macros to generate .dot files at your convenience.

Here you have an example of the kind of pipelines that playbin generates. It is very complex because playbin can handle many different cases: Your manual pipelines normally do not need to be this long. If your manual pipeline is starting to get very big, consider using playbin.

To download the full-size picture, use the attachments link at the top of this page (It's the paperclip icon).

Conclusion

This tutorial has shown:

• How to get more debug information from GStreamer using the GST_DEBUG environment variable.
• How to print your own debug information into the GStreamer log with the GST_ERROR() macro and relatives.
• How to get pipeline graphs with the GST_DEBUG_DUMP_DOT_DIR environment variable.

It has been a pleasure having you here, and see you soon!

---