GstShark Examples

From RidgeRun Developer Connection
Jump to: navigation, search

RR Eval SDK download button.png RR Pre built demo image download.png RR Contact Us.png

Overview

GstShark is an application developed with the purpose of helping the user to profile and measure the performance of a given GStreamer pipeline in certain parameters by means of the tracers available; besides that, the information provided by the execution of the pipeline together with the GstShark application can be very helpful at the time of debugging an error since it is an alternative that provides accurate measurements to the user without having to go through a heavy process, therefore it improves the time needed to fix a determine issue or for devising an improvement to the design without so much effort.

In the page GstShark you can find the User's Guide of the GstShark application in which you will find detailed information about how the tracers work and how to implement them to improve the performance of your pipeline.

In this page are presented several examples of usage of the GstShark application with their respective pipelines and also, there will be included graphical representations of the results obtained through Octave scripts (which are included with the application of GstShark); this plots have the purpose of helping the user to get a better understanding of the results gathered since it is much easier to understand what is happening with a visual representation than reading the log files with all the information.

Octave Scripts

The Octave scripts developed are included with the GstShark application and are inside the package on the path "scripts/graphics/"; there is no needed to create or modify any folder or file in order to correctly obtain the plots of the results of the tracer run at any path, actually there is no even the need of specify the name of the tracer used since the application is totally capable of determining which tracers were executed and filter the results based on this information. The only requirement to correctly obtain the plots of the tracers results is the folder with the CTF output, by default GstShark will generate an output folder, with a log file in CTF format, containing all the information provided by every tracer and this path is the only parameter required by the Octave scripts in order to get the graphic representation of the results.

As it was mentioned above in order to properly get the plot for the results of the tests made with the Octave Graphic it is needed to obtain the CTF output folder at the time of running the test pipeline and to do this the environment variable named "GST_SHARK_CTF_DISABLE" have to be undefined (more information about this is provided on GstShark), the following command can be used to enable the generation of the GstShark CTF output files:

unset GST_SHARK_CTF_DISABLE

The scripts have the capability of filter the CTF log file by each tracer run and thanks to this it will generate a plot for every tracer run and depending of the tracer selected the plot might include additional information as the average of the measurements taken. The command to run the Octave scripts and obtaining the results plots is the following one:

./gstshark-plot <path to the CTF output folder>

Note: this command has to be run inside the path "scripts/graphics/" of the GstShark package.

If the user is familiar with Octave environment it is possible to leave the application running and have access to the structure with all data from the CTF log files analyzed, the name of the structure is "tracer" and with this option it is available to be manipulated as the user wants. The command to access this option is the following one:

./gstshark-plot <path to the CTF output folder> -p

Note: this command has to be run inside the path "scripts/graphics/" of the GstShark package.

There could be the case in which the user wants to save the plots for future reference, GstShark provides the option of exporting the images to a PDF file named "tracer.pdf" or exporting every image to a PNG file separately, in both cases the files are stored in the same path where the command for plotting the results was run. The command to access this option is the following one:

./gstshark-plot <path to the CTF output folder> -s <pdf|png>

Note: this command has to be run inside the path "scripts/graphics/" of the GstShark package.

Every plot has to have a legend with the details of the meaning of every line on the graph and the plot generated by GstShark's scripts are not the exception, by default every plot obtained with the scripts of GstShark will include a legend for a better understanding of what is being plotted; however, there are cases in which the position of the legend can block important information on the plot, that is why the scripts has the option for selecting the position of the legend, between inside and outside of the graph area. The command to access this option is the following one, if this option is not set the legend will be placed inside the graph area by default:

./gstshark-plot <path to the CTF output folder> -l <inside|outside>

Note: this command has to be run inside the path "scripts/graphics/" of the GstShark package.

Finally, similar to every command the GstShark plotting script has a Help menu that you can access with the following command, as it own name says the Help menu will provide useful information about how to use the command and the options available for it, including the ones listed and explained on this document:

./gstshark-plot --help

Note: this command has to be run inside the path "scripts/graphics/" of the GstShark package.

Examples

In order to demonstrate what can be achieved with the tracers and the scripts that GstShark provides, at following there are several examples of escenarios in which GstShark was used and how the results turn out in a presentation that is easy to understand thanks to the scripts.

It is important to mention that for the following examples the syntax used corresponds to the latest stable release made by GStreamer, which is version 1.8.1; the environment in which the test was made had, among others, the following properties:

  • Linux Ubuntu 14.04.4 LTS
  • GStreamer 1.8.1
  • GNU Octave 3.8.1
  • BabelTrace Log Converter 1.3.2

For versions above 1.8.1 the syntax of the pipeline for using the GstShark's tracers should remain unchanged, but GstShark is also compatible with GStreamer version 1.7.1. If the version 1.7.1 match the version available for the user please refer to GstShark, in that page are detailed the differences in the syntax for using GStreamer 1.7.1 or GStreamer 1.8.1; and also there are examples with the modifications needed to run a pipeline with GstShark on GStreamer 1.7.1. Besides the syntax at the time of running the pipeline there should be no difference on the performance of GstShark application.

CPU Usage

The CPU usage tracer was developed with the purpose of measuring the load on the CPU at the time of running a determined pipeline; this tracer has the capability of measuring every core of the system, which means that in a multiprocessor system the tracer is capable of measuring the load on every core, giving an idea of the effort that running the pipeline means for the CPU and the effect on the total CPU consumption. Refer to the GstShark User's Guide GstShark for more detailed information.

The following pipeline is an example used for showing the load on the CPU introduced by running an encoding pipeline. The caps of the pipeline set a frame rate value of 30 FPS and the fakesink element is configured to not synchronize with the clock of the pipeline (normally it is the system clock), therefore the pipeline tries to produce the maximum frame rate using the 100% of the resources of the cores available in the processor as it can be seem on the plot of the results obtained right after the test pipeline.

Pipeline:

GST_DEBUG="GST_TRACER:7" GST_TRACERS="cpuusage" gst-launch-1.0 videotestsrc num-buffers=10000 ! 'video/x-raw, format=(string)YUY2, width=(int)640, height=(int)480, framerate=(fraction)30/1' ! videorate max-rate=30 ! videoconvert ! queue ! avenc_h263p ! queue ! avimux ! fakesink 

Result:

CPU usage of the pipeline with a fakesink not synchronized with the clock

With the purpose of making a comparison and checking the behavior of the CPU usage tracer to different circumstances, the element fakesink was configured to be synchronized with the clock of pipeline, which means that each element is executed 30 times per second, according to the caps of the pipeline; and therefore the CPU usage will decrease as it is shown on the plot at following.

Pipeline:

GST_DEBUG="GST_TRACER:7" GST_TRACERS="cpuusage" gst-launch-1.0 videotestsrc num-buffers=900 ! 'video/x-raw, format=(string)YUY2, width=(int)640, height=(int)480, framerate=(fraction)30/1' ! videorate max-rate=30 ! videoconvert ! queue ! avenc_h263p ! queue ! avimux ! fakesink sync=true

Result:

CPU usage of the pipeline with a fakesink synchronized with the clock

In addition to the results obtained through the CPU usage tracer and the plots through the scripts from the GstShark application, is possible to get a comparison graph between CPU Usage and frame rate depending only to the tracers selected at the time of running the pipeline. This is a feature limited only to the CPU usage and frame rate tracers, and the only extra step needed is add the frame rate tracer to the previous pipeline as it is shown on the following box, the resulting plot is presented after the pipeline run:

GST_DEBUG="GST_TRACER:7" GST_TRACERS="cpuusage;framerate" gst-launch-1.0 videotestsrc num-buffers=900 ! 'video/x-raw, format=(string)YUY2, width=(int)640, height=(int)480, framerate=(fraction)30/1' ! videorate max-rate=30 ! videoconvert ! queue ! avenc_h263p ! queue ! avimux ! fakesink sync=true


CPU usage and frame rate of the pipeline with a fakesink synchronized with the clock

Frame rate

As it was exemplified in the previous section with the latest demonstration of the CPU usage tracer; what the frame rate tracer does is displaying the amount of frames that goes through every element of the pipeline per second. More detailed information of this trace is given on the GstShark User's Guide (GstShark).

The measurements of the frame rate normally tend to remain constant and equal among each other for every element of the pipeline, since the more frequent case of analysis are the single threaded pipeline but this is not for sure and there could escenarios in which the pipeline has different frame rates for different elements. The following pipeline is a demonstration of a case in which different sections of the pipeline have different values of frame rate set. This example is also a test of the capabilities of the GstShark frame rate tracer and for the graph scripts since it is much easier to observe the different frame rate values generated by the pipeline in a plot than in the output log.

The following plot shows three groups of elements categorized by the value of frame rate measured on each one of them, producing three defined lines on the graph in which the different elements gather; specifically speaking to 15, 30 and 60 fps.

GST_DEBUG="GST_TRACER:7" GST_TRACERS="framerate" gst-launch-1.0 videotestsrc num-buffers=1800 ! tee name=tee0 ! queue ! videorate  ! video/x-raw,framerate=60/1 ! fakesink sync=true tee0. ! queue ! videorate  ! video/x-raw,framerate=30/1 ! fakesink sync=true tee0. ! queue ! videorate  ! video/x-raw,framerate=15/1 ! fakesink sync=true
Multiple frame rate of the pipeline

Processing time

The GstShark processing time tracer ("proctime") have the purpose of providing information to the user about the amount of time that each element of the pipeline is taking for processing each data buffer that goes through it; in other words, it measures the time of every element needs to process a buffer giving an idea of which element is taking too much time completing its tasks, causing a slow performance, among others issues.

The processing time tracer was designed for work with filters and filters-like elements that process the inputs and outputs in the same thread, more information about this limitation and the performance of the tracer is provided on the GstShark User's Guide (GstShark).

The following example is a pipeline that has different delay on every branch of it (the tee element used was with the purpose of dividing the pipeline), in order to show different processing times for each element and demonstrate how the GstShark processing time tracer does the measurements. The delay on every branch of the pipeline is being done by the identity elements with a sleep time that simulates a constant processing time.

In the plot available next there will be lines of the plot longer than the others, this is because each identity element has to process 60 frames and therefore an element with longer processing time also needs a longer time to process all the input buffers.

GST_DEBUG="GST_TRACER:7" GST_TRACERS="proctime" gst-launch-1.0 videotestsrc num-buffers=60 ! tee name=tee0 tee0. ! queue ! identity sleep-time=10000 ! fakesink tee0. ! queue ! identity sleep-time=30000 ! fakesink tee0. ! queue ! identity sleep-time=50000 ! fakesink
Processing time for each element of the pipeline

Scheduling Time

The purpose of the GstShark scheduling time tracer is to measure the elapsed time from the moment when a buffer reaches the sink pad of a element and the moment which it reaches the immediate consecutive element sink pad, it is important to mention that the measurements of this tracer does not take in consideration the time needed for the element to compute the arrived data buffer. Similar to processing time tracer, the schedule time tracer provides information about the amount of time needed by the pipeline to process a given data buffer completely and with this giving an idea of the performance of the pipeline.

In difference with the processing time tracer, this tracer does not have any limitation with category of the element that is being measured, and because of that the schedule time tracer is specially useful for detecting bottle necks on the pipeline, buffer drops, inter-clock differences, among others. Information more detailed about this tracer and its behavior is available in the Guide User's Guide documentation (GstShark).

The following pipeline is an encoding example and it is the type of pipeline in which the GstShark scheduling time tracer can be very helpful; as it was mentioned before this tracer provides information about the time that takes for a buffer to go from sink pad to sink pad of two continuos elements and since the example pipeline has a video source then issues as detecting bottle necks or frame drops have might high concern for the user, specially if the user recording to a video file, giving a demonstration of the case of usage and the capabilities of one of the GstShark features.

In the same way than previous examples it is easier to analyze and understand the results obtained in a plot than in the output log file, therefore the graph of the output obtained is presented after the example pipeline.

GST_DEBUG="GST_TRACER:7" GST_TRACERS="scheduletime" gst-launch-1.0 videotestsrc is-live=true do-timestamp=true num-buffers=50 ! 'video/x-raw, format=(string)YUY2, width=(int)1280, height=(int)720, framerate=(fraction)10/1' ! videoconvert ! queue ! avenc_h263p ! fakesink sync=true
Scheduling time for each element of the pipeline

Interlatency

GstShark includes the inter latency tracer, which was developed with the purpose of measuring the time that a buffer takes to travel from one point to another inside the pipeline; specifically speaking the GstShark inter latency tracer gives the time needed by a buffer for travel from the source pad of the source element to the source pad of the remaining elements of the pipeline. Therefore the measure given for the sink element at the end of the downstream will correspond to the general latency of the pipeline, in other words, that measurement is the total time needed by a buffer to go through the entire pipeline.

Based of the kind of measurements that the GstShark inter latency tracer does, it is possible to know what route of the pipeline is increasing the overall latency by displaying the exact amount of time that the buffer took to go through every element on the pipeline.

It is important to mention that given the nature of the GstShark inter latency tracer; it has the limitation that, currently, it only supports source elements, sink elements and filter elements. For the rest of categories of elements available in GStreamer the GstShark inter latency tracer will not crash but it will not be accurate in its measurements. On the GstShark User's Guide documentation there is more detailed information this tracer GstShark.

The following pipeline is the same used as an example for GstShark scheduling time tracer but given the amount of element and the nature of them it can also works as a good demonstration of the functionality and the method to implement the GstShark inter latency tracer. Also the graphical representation of the results is shown, obtained with the GstShark graph scripts, with the purpose of making easier the read and the interpretation of the results by means of the plot than with the output log.

Note: The interpretation of the plot with the given results for the inter latency tracer has to be vertically, this means that as an element is lower in the downstream the time needed to get form the source element to it will be higher; and that is why in the plot it seems like the line of the rightmost element in the pipeline is in an upper level than the previous one. It can be seem as an accumulated time for every element to the right of the pipeline until the sink element, which will have the highest value.

GST_DEBUG="GST_TRACER:7" GST_TRACERS="interlatency" gst-launch-1.0 videotestsrc is-live=true do-timestamp=true num-buffers=50 ! 'video/x-raw, format=(string)YUY2, width=(int)1280, height=(int)720, framerate=(fraction)10/1' ! videoconvert ! queue ! avenc_h263p ! fakesink sync=true
Latency between the src pad of the source element and the src pad of each one of the remaining elements of the pipeline