View source for GstShark - Tracer Parameters

{{GstShark/Head |previous=Generating trace files|next=Tracers|metakeywords=}}

This page describes how to pass parameters to the tracers. There are general parameters and tracer specific parameters. This page focuses on general tracer parameters. Tracer specific ones will be documented in the respective page.

__TOC__

== General Syntax ==

The syntax to pass a parameter to a tracer is:

<syntaxhighlight lang=bash>
GST_TRACERS="tracer(parameter=value)" gst-launch-1.0 ...
</syntaxhighlight>

Where:
;tracer
:The tracer to activate, i.e.: framerate, cpuusage, scheduletime, etc... See the [[GstShark_-_Tracers|list of available tracers]]
;parameter
:The name of the parameter to set for the tracer
;value
:The value to set to the tracer's parameter

Several parameters may be set for a single tracer using the following syntax:
<syntaxhighlight lang=bash>
GST_TRACERS="tracer(parameter1=value1,parameter2=value2)" gst-launch-1.0 ...
</syntaxhighlight>

Similarly, some tracers allow several values to be set for the same parameter using the following syntax:
<syntaxhighlight lang=bash>
GST_TRACERS="tracer(parameter=value1,parameter=value2)" gst-launch-1.0 ...
</syntaxhighlight>

Finally, different tracers may be activated with different parameters each, as in the following syntax:
<syntaxhighlight lang=bash>
GST_TRACERS="tracer1(parameter1=value1);tracer2(parameter2=value2)" gst-launch-1.0 ...
</syntaxhighlight>

== General Tracers ==

The following section describes the general tracers that apply almost all tracers. In case a tracer is not supported, it will be indicated respectively.

=== Individual Element Tracing (filter) ===

The individual element tracing, or '''filter''' parameter, allows the user to choose which elements get included in the tracing. The value to be set in the '''filter''' is a [https://developer.gnome.org/glib/stable/glib-regex-syntax.html Glib Compatible Regular Expression], meaning that elements to be traced can be grouped by using a regex that matches with their name.

<!-----
<pre style=background-color:yellow>
NOTE: The filtering applies to the element name, NOT the factory. This is, if your element is specified as "identity name=myelem", you should refer to "myelem" and not to "identity"
</pre>
--->
{{Ambox
|type=notice
|small=left
|issue='''The filtering applies to the element name, NOT the factory. This is, if your element is specified as "identity name=myelem", you should refer to "myelem" and not to "identity"'''
}}

=== Periodic Tracers (period) ===

The periodic tracing, or '''period''' parameter, allows the user to choose the rate at which periodic tracers dump info. The value for '''period''' is an integer describing the number of seconds between each record. Floating-point values are truncated and invalid values are ignored and the default is used instead.

==== Examples ====

For the given pipeline:
<syntaxhighlight lang=bash>
gst-launch-1.0 videotestsrc ! identity ! fakesink
</syntaxhighlight>

;Print the amount of frames that flow every 5 seconds through the different src pads in the pipe:
:GST_TRACERS="framerate(period=5)" GST_DEBUG=GST_TRACER:7
;Print the amount of bits that flow every 3 seconds through the different src pads in the pipe:
:GST_TRACERS="bitrate(period=3)" GST_DEBUG=GST_TRACER:7
;Print the amount of frames that flow every 5 seconds and bits that flow every 3 seconds through the different src pads in the pipe:
:GST_TRACERS="framerate(period=5);bitrate(period=3)" GST_DEBUG=GST_TRACER:7
;Print the amount of frames that flow every 5 through the '''identity''':
:GST_TRACERS="framerate(period=5,filter=identity);bitrate(period=3)" GST_DEBUG=GST_TRACER:7


<!-- test edit -->
{{GstShark/Foot |previous=Generating trace files|next=Tracers}}