GstShark - Using the Eclipse Plugin
As it was mentioned in previous sections the main idea of developing an Eclipse plugin was to facilitate the task of analyzing the data obtained through the GstShark tracers explained above, in this same line the Eclipse plugin is really helpful for processing and providing a more understandable and intuitive representation of the data so it can be easier to the to interpret than the console output log or the output file written in CTF format.
An important step for using the Eclipse plugin is that is needed to have the output log saved in a CTF format, this is done by the tracer itself by default no matter which one of the tracers is run with the pipeline as it was explained and detailed in the previous section together with the environment variables that let you choose the path of the output folder and the possibility of generating or not the output log files in CTF format (GStreamer Tracers).
The GstShark Eclipse plugin is a feature of the application for simplifying the operation of reviewing the results obtained by means of a more friendly interface than the console output log and the possibility of generating plots of the measurements as it is going to be explained later on this site; therefore the best way to explain how the plugin works and how to get the best of it is by an example, since a demonstration of the capabilities of the plugin will be better for its comprehension than only describing its performance (the supposition here is that the GstShark Eclipse plugin is already installed and running according to the section Installation from RidgeRun's Eclipse Repository). The pipeline used for this purpose is the one presented at following:
GST_DEBUG="GST_TRACER:7" GST_TRACERS="graphic;cpuusage;framerate" gst-launch-1.0 videotestsrc num-buffers=500 ! '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
Note: The GstShark Eclipse plugin has the limitation that it can only plot the results of the tracers CPU usage and frame rate; the team is working on developing more functions in order to add support for the remaining tracers but so far the performance is limited to these two. However, in the GstShark package are included Octave scripts with the purpose of generating visual representations of the results obtained by any tracer, the instructions and details for using these scripts are in GstShark Examples.
After running the previous pipeline and having the output files correctly saved in a known path the following step is opening the Eclipse application, if the installation of the GstShark plugin finished as it is expected then the following image shows the interface that should appear at the time of opening Eclipse.
The next step will be opening the output file and loading results obtained at the time of running the pipeline, in order to do this the user will have to navigate through the menu bar until we get the option "GstShark->Open Trace" as it shown in the following image.
A new window will appear giving the option to the user of exploring through the file system of the host PC to find the path in which the output files are stored, when that folder is accessed the user should see what is presented in the following image and should select the "datastream" file so the plugin can successfully load the results gathered.
Once the "datastream" file was successfully loaded the user should expect to see something similar to the following image, in which the results of every tracer run with the pipeline are shown by category; for the purpose of the current example the tracer present on the image will be limited to "cpuusage" and "framerate", since those are the tracers that were selected at the time of running the demonstration pipeline mentioned above.
One of the features that the GstShark Eclipse plugin has is the capability of showing the graphical diagram of the pipeline run; as it was explained in previous section, adding the "graphic" tracer to the execution of the pipeline will export the diagram of it to an additional folder inside the selected path, the one in which the output files are being saved, in DOT format. By means of the menu "GstShark->Show Pipeline Diagram" in the Eclipse plugin window, it is possible to check the output of this tracer without doing any additional effort for converting the format of the diagram to a regular image file type; the following image shows the menu used for this purpose on the GstShark Eclipse plugin.
After accessing the previous menu a new window will appear giving the option to the user of going through the file system of the host PC in order to find the path in which the DOT file is stored, the following image is a demonstration of what the user can see when that folder is accessed.
When the file "pipeline.dot" (default name for the pipeline diagram) is opened by the process described above, the GstShark Eclipse plugin will convert the format of the file to a regular image format, e.g. PNG, JPEG, among others; then it will show the output image diagram to the user on a new window. It is important to mention that the GstShark plugin has a known issue related to this feature and it is specifically related to the size of the window opened; if the pipeline diagram is too big the window will cut it on the edges showing only what fits the size of the window, extending the size of the window will allow the user to see more of the pipeline diagram but there is no way to make it smaller (zoom in and zoom out functions are not supported yet) and therefore the pipeline diagram will always appear cut as the following image shows.
Another feature available through the GstShark Eclipse plugin is the capability of searching and filtering the results obtained by the tracers that generated them, this is useful when the user has interests on checking the behavior of a specific parameter but because of time or resources the pipeline was run with several tracers at the same time. This feature can be accessed by typing the search parameter on the top of the column "Event type" as it is shown on the following image.
As a demonstration of a the search capability of the GstShark Eclipse plugin, the following image shows the output obtained by searching the value "cpuusage" with the instructions explained before.
Note: It is important mention that in order to clean the searching results there is only needed to erase the searching parameter and this will undo the search done.
Filtering the output results is also a feature available on the GstShark Eclipse plugin and it is a very simple process very similar to one used for searching a specific "Event type". However in order to access the filtered results the user first needs to change mode of operation and this is done by toggling the icon marked on the following image; this icon has no legend but it is pretty simple to distinguish, when the icon is similar to a lantern with the light on is because the GstShark Eclipse plugin is on searching mode and when the icon are three rows pointing to the right is because the GstShark Eclipse plugin is on filtering mode.
The method used to introduce the filter parameter is similar to one used to insert the search parameter, since it is only needed to type the specific parameter that is going to be use for filtering in the "Event type" field as it is marked on the following image.
In order to demonstrate the filtering feature that GstShark Eclipse plugin has, the following image shows the output obtained by filtering the value "cpuusage" with the instructions explained before.
Note: As an important mention, in order to clean the filtering results it is needed to click the right button of the mouse and select the option "Clear filters", otherwise the data will remain filtered even when the filter parameter has been removed.
The main feature and the reason for what the GstShark Eclipse plugin was developed is to generate an alternative to interpret the results obtained at the time of running the pipeline by providing to the user the option of plotting the information gathered, depending on the tracer to which the data belong, versus the time elapsed during the execution of the pipeline. The information used to make this plots is filtered automatically by the GstShark Eclipse plugin which means that the only step that the user has to do is to open a new window in which the plot can be shown. Thus, in order to open the correspondent plots of the tracers run with the pipeline is needed to open a new view on the GstShark Eclipse plugin and the method to do this is by accessing the menu "Window->Show view->Other..." as it is shown in the following image.
After accessing the menu "Window->Show view->Other..." a small list of option should appear, showing the many options of type of windows available to be opened on the GstShark Eclipse plugin; however, for matters of plotting the results obtained with the GstShark tracers, the views of interest are categorized under the name "Other" as it is shown on the following image where the two kinds of plots available appear on the top of the list.
The pipeline mentioned previously on this section was run in order to exemplify the features of the GstShark Eclipse plugin and the plots of the results obtained are not the exception; that is why following the steps described before and selecting either "Window->Show view->Other...-->GstSharkCpuUsage" or "Window->Show view->Other...-->GstSharkFrameRate", for the CPU usage and frame rate plot, respectively; the user can access the plots of the results obtained with the tracers supported by the GstShark Eclipse plugin. At following there are the plots of the results of the CPU usage and frame rate tracers for the demonstration pipeline detailed above.
- CPU Usage plot:
- Frame rate plot:
Note: In some cases an odd behavior appears on the plots of the results obtained and it is that the graph appears to be empty but really there is only an issue with the time scale of the X axis, therefore it is only needed to do a zoom out and the plot will appear eventually.