GstShark - Getting Started

GstShark
Getting Started
Getting the code Dependencies Building tracers Eclipse Plugin
Generating trace files
Tracer Parameters
Available Tracers
InterLatency Processing time Frame rate Schedule time CPU usage Graphic Bitrate Queue Level Buffer
Results
Common Trace Format Pipeline Diagram
Visualization Tools
gstshark-plot Eclipse plugin
Examples
CPU usage analysis Frame rate example Processing time example Scheduling time example Interlatency example
Contact Us

Getting the code

GstShark is an open-source source project by Ridgerun Engineering. It is publicly available here[1].

You can download the source using git:

$ git clone git@github.com:RidgeRun/gst-shark.git

OR

$ git clone https://github.com/RidgeRun/gst-shark/

Dependencies

GStreamer 1.7.1+

GstShark leverages GStreamer's tracing subsystem, which was added in GStreamer 1.7.1.

Most modern Linux distributions include GStreamer 1.7.1 (or newer) in their official package repositories. If this is not your case, refer to the this guide to manually install the latest GStreamer version alongside the one installed by your system.

To check your current GStreamer version run the following command:

$ gst-launch-1.0 --version
gst-launch-1.0 version 1.7.1
GStreamer 1.7.1
Unknown package origin

If you do not have GStreamer installed at all, check the version available using the regular package tools for your distribution. For example, in Ubuntu run the following commands:

$ apt-cache showpkg libgstreamer1.0-0
Package: libgstreamer1.0-0
Versions:
1.6.3-1ubuntu1 (/var/lib/apt/lists/cr.archive.ubuntu.com_ubuntu_dists_wily-proposed_main_binary-amd64_Packages) 
 ...

And, if the version is above 1.7.1, install it with your distribution's tools. For example, in Ubuntu use:

$ sudo apt install libgstreamer1.0-dev

Graphviz

Graphviz is used to display the pipeline diagrams as obtained by the graphic tracer. According to your distribution and version of your distribution, the Graphviz library might be called graphviz-dev or libgraphviz-dev. To read the graphics resulting from the tracer later, the package graphviz is required. Check your distribution's package lists for a suitable packages. For recent Ubuntu versions:

$ sudo apt install graphviz libgraphviz-dev

octave, epstool and babeltrace

Octave scripts are provided to generate charts of the traces. Octave scripts use babeltrace to parse the trace files to be used by Octave and epstool to generate the PDF outputs. Octave, epstool and babeltrace are not required for compiling GstShark, but are required to run the scripts. To install octave, epstool and babeltrace on Ubuntu:

$ sudo apt install octave epstool babeltrace

Eclipse Mars.2

GstShark includes optional experimental support to generate charts using Eclipse. Currently, only Eclipse Mars.2 (4.5.2) is supported. Eclipse Mars.2 can be downloaded from: https://www.eclipse.org/downloads/packages/release/Mars/2

Building GstShark Tracers

The GstShark project comes packed as a typical GNU open source project. Use autogen/make to build the project:

$ ./autogen.sh $OPTIONS # CHOOSE THE APPROPRIATE CONFIGURATION FROM THE TABLE BELOW
$ make

For the most common build targets, the recommended options are listed below.

Table 1. Platform configuration options

System	Configure Option
Ubuntu 64 bits	--prefix /usr/ --libdir /usr/lib/x86_64-linux-gnu/
RidgeRun's Embedded FS	--prefix /usr/
Raspbian/Raspberry Pi	--prefix /usr/lib/ --libdir /usr/lib/arm-linux-gnueabihf/
NVIDIA Jetson SoCs TX1 TX2 Nano Xavier NX	--prefix /usr/ --libdir /usr/lib/aarch64-linux-gnu/

For other distributions and platforms, the commands may need to be adjusted. Please contact us for details on how to compile for your platform.

Installing GstShark Tracers

To install the tracers, use the install rules of the Makefile.

$ sudo make install

For other distributions and platforms, the command may need to be adjusted. Please contact us for details on how to install for your platform.

Installing GstShark Eclipse Plugins

The Eclipse plugin is included in the repository, but it is also available from a Ridgerun repository. For details on how to install the Eclipse plugin, visit the Install Eclipse plugin page.

Installing GstShark on macOS using homebrew

Homebrew supports the packages used by GstShark to create the plot files. Install Homebrew if you feel comfortable installing software outside of the Apple Store.

Update installed packages

If you have homebrew installed, consider updating homebrew and upgrading your packages.

brew update
brew upgrade

Install GStreamer

GstShark leverages GStreamer's tracing subsystem, which was added in GStreamer 1.7.1. To check your current GStreamer version run the following command:

$ gst-launch-1.0 --version
gst-launch-1.0 version 1.7.1
GStreamer 1.7.1
Unknown package origin

If you do not have GStreamer installed at all, run the following commands:

brew install gstreamer
brew link gstreamer

Install graphing tools

A set of graphing packages are used to GstShark.

brew install octave graphviz octave epstool

Build and install babeltrace

Babeltrace isn't available as part of homebrew at the time of this writing.

brew install autoconf automake bison 

mkdir -p ~/projects
cd ~/projects
git clone https://github.com/efficios/babeltrace.git -b v1.5.8
cd babeltrace
./bootstrap
PATH="/usr/local/opt/bison/bin:$PATH" ./configure
make
sudo make install