GstShark - Getting Started
 | Open-source project from Ridgerun. |
| GstShark |
|---|
 |
| Getting Started |
| Generating trace files |
| Tracer Parameters |
| Available Tracers |
| Results |
| Visualization Tools |
| Examples |
| Contact Us |
Contents
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 package. 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 gtk-doc-tools
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 and Installing GstShark Tracers
GstShark project supports both meson and autotools build systems
Meson
NOTE: If you are on RedHat8/CentOS8 use ninja-build instead of ninja
Install meson to at least v0.58:
sudo apt install python3 python3-pip ninja-build
pip3 install --user meson
sudo cp ~/.local/bin/meson /usr/bin/meson
Configure and build:
meson builddir --prefix /usr/
ninja -C builddir
To install:
ninja install -C builddir
To run tests:
ninja test -C builddir
The following configurations are available beside the normal meson ones:
| Option | Description | Default |
|---|---|---|
| enable-tests | Enable building and running the unit tests | true |
| enable-check | Enable building and running unit tests using gst-check (requires enable-tests) | true |
| enable-plotting | Enable pipeline plotting capabilities | enabled |
| enable-docs | Enable generation of documentation | true |
Autotools
$ ./autogen.sh $OPTIONS # CHOOSE THE APPROPRIATE CONFIGURATION FROM THE TABLE BELOW
$ make
For the most common build targets, the recommended options are listed below.
| 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.
To install the tracers, use the install rules of the Makefile.
$ sudo make install
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 PATH="/usr/local/opt/bison/bin:$PATH" make sudo make install
Build and install GstShark tracers
With all the dependencies in place, you can now build GstShark.
brew install gtk-doc mkdir -p ~/projects cd ~/projects git clone https://github.com/RidgeRun/gst-shark cd gst-shark ./autogen.sh make
Installing GstShark on Yocto
Meta-RidgeRun
In order to use gst-shark easily, we recommend using the meta-ridgerun layer (https://github.com/RidgeRun/meta-ridgerun)
This already has the gst-shark recipe integrated.
The meta-ridgerun layer has to be added to the bblayers.conf. A full example is shown (note the last line):
LCONF_VERSION = "7"
BBPATH = "${TOPDIR}"
BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"
BBFILES ?= ""
BBLAYERS = " \
${BSPDIR}/sources/poky/meta \
${BSPDIR}/sources/poky/meta-poky \
\
${BSPDIR}/sources/meta-openembedded/meta-oe \
${BSPDIR}/sources/meta-openembedded/meta-multimedia \
\
${BSPDIR}/sources/meta-freescale \
${BSPDIR}/sources/meta-freescale-3rdparty \
${BSPDIR}/sources/meta-freescale-distro \
"
# i.MX Yocto Project Release layers
BBLAYERS += " ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-bsp "
BBLAYERS += " ${BSPDIR}/sources/meta-fsl-bsp-release/imx/meta-sdk "
BBLAYERS += " ${BSPDIR}/sources/meta-browser "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-gnome "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-networking "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-python "
BBLAYERS += " ${BSPDIR}/sources/meta-openembedded/meta-filesystems "
BBLAYERS += " ${BSPDIR}/sources/meta-qt5 "
BBLAYERS += " ${BSPDIR}/sources/meta-ridgerun "
local.conf configuration
Once the meta-ridgerun is added, then the local.conf must be modified to include gst-shark as follows:
IMAGE_INSTALL_append = " gst-shark "
Gst-Shark uses gst-tracers in order to retrieve information and provide it to the user. By default, GStreamer doesn't have some hooks enabled in Yocto builds, so it is required to enable them. This is accomplished by adding on the local.conf of the project, the next line:
PACKAGECONFIG_append_pn-gstreamer1.0 = "gst-tracer-hooks"
For Yocto Dunfell and newer the required configuration changed:
PACKAGECONFIG_append_pn-gstreamer1.0 = " tracer-hooks"
An example of local.conf would be:
MACHINE ??= 'imx8mmevk'
DISTRO ?= 'fsl-imx-wayland'
PACKAGE_CLASSES ?= "package_rpm"
EXTRA_IMAGE_FEATURES ?= "tools-debug debug-tweaks"
INHIBIT_PACKAGE_STRIP = "1"
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
PATCHRESOLVE = "noop"
BB_DISKMON_DIRS ??= "\
STOPTASKS,${TMPDIR},1G,100K \
STOPTASKS,${DL_DIR},1G,100K \
STOPTASKS,${SSTATE_DIR},1G,100K \
STOPTASKS,/tmp,100M,100K \
ABORT,${TMPDIR},100M,1K \
ABORT,${DL_DIR},100M,1K \
ABORT,${SSTATE_DIR},100M,1K \
ABORT,/tmp,10M,1K"
PACKAGECONFIG_append_pn-qemu-native = " sdl"
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
CONF_VERSION = "1"
IMAGE_INSTALL_append = " gst-shark "
PACKAGECONFIG_append_pn-gstreamer1.0 = "gst-tracer-hooks"
