mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-11-27 20:21:24 +00:00
Code Issues 1 Projects Releases Wiki Activity

tutorials: debugging-tools: improve formatting & content

Browse source 
Reformat tables & fix markup. Additionally, add note on some
information referring only to the default hadler.
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2017-07-28 14:38:10 -07:00
parent 6513190384
commit f1a79c576b
1 changed files with 61 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
markdown/tutorials/basic/debugging-tools.md
View file

@ -23,8 +23,7 @@ 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`:
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"
@ -40,17 +39,38 @@ 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, ... |
| 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. |
| 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
@ -81,25 +101,40 @@ 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.
The content of each line in the debug output
is:
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 is printed |
| `gst_file_src_start`| Function from which the message was issued |
| `&lt;filesrc0&gt;` | 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 will make this debug output more readable (otherwise, GStreamer assigns each new element a unique name). |
| `error: No such file &quot;non-existing-file.webm&quot;` | The actual message.|
|------------------|-----------------------------------------------------------|
|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