GstShark - Getting Started

From RidgeRun Developer Wiki





  Index Next: Install Eclipse plugin


GstShark
GstShark
Getting Started
Generating trace files
Tracer Parameters
Available Tracers
Results
Visualization Tools
Examples
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 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/
Table 1. Platform configuration options

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"


  Index Next: Install Eclipse plugin


Retrieved from "https://developer.ridgerun.com/wiki/index.php?title=GstShark_-_Getting_Started&oldid=49805"