GstShark - Generating trace files

This page describes how to enable the tracers for a pipeline. To debug a pipeline, the trace data files need to be generated. The trace data files will then be used to create the graphics or debug the pipeline.

Enable GstShark on the Debugging Log

One of the possible outputs for the measurements of GstShark is the debugging log of GStreamer. Since GstShark is built and installed as a plugin of GStreamer, it can use the debugging log to print the results of every tracer on the terminal when the pipeline is still running and therefore displaying the results instantaneously. In order to enable this option, there is no step needed on the GstShark side, it is only a matter of enabling the GStreamer debugging log with the corresponding level.

The GStreamer debugging levels are the following ones:

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. Fixme messages are messages that indicate that something in the executed code path is not fully implemented or handled yet. The purpose of this message is to make it easier to spot incomplete/unfinished pieces of code when reading the debug log.
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.
7	TRACE	Logs all trace messages. These messages for events that happen repeatedly during an object's lifetime such as the ref/unref cycles.
9	MEMDUMP	Log all memory dump messages. 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 GstShark is a tool for profiling/debugging the performance of a pipeline using the tracer developed, it will use the category number 7 to print the results on the debug output for every tracer enabled. However, since this category will include all the other levels of debugging the log can get a lot of noise and be very difficult to read and to get the tracer information desired. So, it is strongly recommended to specify the debugging levels by name and for the purpose of the GstShark case the information wanted is related to "GST_TRACER".

The following pipeline is an example of how to enable the GstShark tracer's output on the debugging log of GStreamer:

GStreamer 1.7.1

$ GST_DEBUG="GST_TRACER:7" GST_TRACER_PLUGINS="cpuusage"\
     gst-launch-1.0 videotestsrc ! videorate max-rate=15 ! fakesink

GStreamer 1.8.1 and later

$ GST_DEBUG="GST_TRACER:7" GST_TRACERS="cpuusage"\
     gst-launch-1.0 videotestsrc ! videorate max-rate=15 ! fakesink

Select Tracer

GstShark has several tracers at the provision of the user depending on his/her own needs and even when there is the possibility of using all the tracer at the same time for having a complete profile of one pipeline, there is also the chance of being interested in a specific kind of information that can be provided by only one, or a few, of the tracers and therefore the other ones would only introduce noise to the debugging log; because of that and with the purpose of taking advantage of the tracer logic of GStreamer, the user has the capability of selecting the tracers that will be run with the pipeline by listing them (separated by the character ";") using the option "GST_TRACER_PLUGINS" or "GST_TRACERS", depending on the GStreamer version, at the time of running the pipeline in a very similar way than the "GST_DEBUG" option.

The following pipeline is an example of how to select various tracers for analyzing a given pipeline and obtaining the results on the debugging log of GStreamer:

GStreamer 1.7.1

$ GST_DEBUG="GST_TRACER:7" GST_TRACER_PLUGINS="cpuusage;proctime;framerate"\
     gst-launch-1.0 videotestsrc ! videorate max-rate=15 ! fakesink

GStreamer 1.8.1 and later

$ GST_DEBUG="GST_TRACER:7" GST_TRACERS="cpuusage;proctime;framerate"\
     gst-launch-1.0 videotestsrc ! videorate max-rate=15 ! fakesink

Define Output Location

GstShark has the feature of generating several output files in which the log, with all the results, of every tracer enabled, is store together with the graph of the pipeline run (if the respective tracer was set), these files can be used later on Eclipse to obtain information about the performance of the pipeline in a more user-friendly way (explained later on Eclipse Plugin). The location of the output files can be set by the user by modifying the environment variable "GST_SHARK_LOCATION", by setting this option no matter the path in which the pipeline is run the tool will place the output files on the correspondent folder.

It is important to mention that if the environment variable is not set at the time of running the pipeline the default output is a new folder in the current path with the name "gstshark_YY-MM-DD_hh:mm:ss", where YY-MM-DD_hh:mm:ss corresponds to the time stamp when the pipeline started running.

The following command is an example of how to define the environment variable for setting the desired location of the GstShark output files:

$ export GST_SHARK_LOCATION=/tmp/profile

If the user wants to use the default location of the GstShark output files is only needed to unset the environment variable by using the following command:

$ unset GST_SHARK_LOCATION

Enable/Disable Output Files

One of the main features of GstShark is the ability to generate several output files, as it was commented previously, those files can be used together with the Eclipse plugin (explained later on Eclipse Plugin) for analyzing the performance of the pipeline offline at any time that the user might want; saving the user for having to run again the pipeline to get the same results, since they are already stored in a defined location. However, there could be the scenario in which no output file is needed or wanted, that is why GstShark has the capability of disabling the generation of these files by setting the environment variable "GST_SHARK_CTF_DISABLE" previous of running the pipeline; the content of the variable will not affect the result obtained since the tool only checks that it is set but not its content, but by standard, it is recommended to set it with the values "TRUE" or "1".

The following command is an example of how to define the environment variable that will disable the generation of the output files on GstShark:

$ export GST_SHARK_CTF_DISABLE=TRUE

Note: If the GST_SHARK_CTF_DISABLE is defined, with any content, it will disable the generation of the output files but not the store of the DOT file if the graphic tracer is set.

If the user wants to enable the generation of the GstShark output files, it is only needed to unset the environment variable by using the following command:

$ unset GST_SHARK_CTF_DISABLE

Modify Buffering Mode and Size

As was mentioned before GstShark generates several output files, and these files can be used later on Eclipse to obtain information about the performance of the pipeline in a more user-friendly way that is explained on Eclipse Plugin section. With GstShark you can change the mode and the buffer size for the buffering of the files by modifying the environment variable "GST_SHARK_FILE_BUFFERING" previous of running the pipeline.

The following command is an example of how to define the environment variable that will change the buffering mode to no buffering:

$ export GST_SHARK_FILE_BUFFERING=0

With the no buffering mode every I/O operation is written as soon as possible.

The following command is an example of how to define the environment variable that will change the buffering mode to full buffering and the buffering size, this command uses a positive integer value for the size: