GstTracer

GstTraceField

Since : 1.30

gst_trace_field_free

gst_trace_field_free (GstTraceField * field)

Frees a field that has not been added to a builder.

Since : 1.30

gst_trace_field_set_description

GstTraceField *
gst_trace_field_set_description (GstTraceField * field,
                                 const gchar * description)

Sets the description metadata on field. Tracers and documentation generators surface this string when describing the field.

Since : 1.30

gst_trace_field_set_flags

GstTraceField *
gst_trace_field_set_flags (GstTraceField * field,
                           GstTracerValueFlags flags)

Sets metadata flags on field. GST_TRACER_VALUE_FLAGS_OPTIONAL marks the field as optional: when emitting an event, the field's value must be preceded by a gboolean value telling whether it is present.

Since : 1.30

gst_trace_field_set_scope

GstTraceField *
gst_trace_field_set_scope (GstTraceField * field,
                           GstTracerValueScope scope)

Declares which entity (process, thread, element or pad) the field's value relates to. Post-processing tools such as gst-stats use this to group measurements.

Since : 1.30

gst_trace_field_new

GstTraceField *
gst_trace_field_new (const gchar * name,
                     GstTracerFieldType type)

Creates a transient field descriptor that can be configured with chainable setters and then consumed by gst_trace_format_builder_add_field_full.

Since : 1.30

GstTraceFormat

Since : 1.30

gst_trace_format_get_description

const gchar *
gst_trace_format_get_description (GstTraceFormat * format)

Since : 1.30

gst_trace_format_get_field_description

const gchar *
gst_trace_format_get_field_description (GstTraceFormat * format,
                                        guint index)

Since : 1.30

gst_trace_format_get_field_name

const gchar *
gst_trace_format_get_field_name (GstTraceFormat * format,
                                 guint index)

Since : 1.30

gst_trace_format_get_field_structure

const GstStructure *
gst_trace_format_get_field_structure (GstTraceFormat * format,
                                      guint index)

Returns the raw GstStructure describing the field at index. The structure carries the field's type ("type", a GstTracerFieldType stored as gint) and any optional metadata declared via gst_trace_format_builder_add_field_full (e.g. "description").

Since : 1.30

gst_trace_format_get_field_type

GstTracerFieldType
gst_trace_format_get_field_type (GstTraceFormat * format,
                                 guint index)

Since : 1.30

gst_trace_format_get_n_fields

guint
gst_trace_format_get_n_fields (GstTraceFormat * format)

Since : 1.30

gst_trace_format_get_name

const gchar *
gst_trace_format_get_name (GstTraceFormat * format)

Since : 1.30

gst_trace_format_is_enabled

gboolean
gst_trace_format_is_enabled (GstTraceFormat * format)

Cheap check that lets callers skip preparing span values when no tracer is active. Returns TRUE whenever any tracer is registered, regardless of which hooks it listens for.

Since : 1.30

gst_trace_format_register

GstTraceFormat *
gst_trace_format_register (const gchar * name,
                           ... ...)

Convenience wrapper around GstTraceFormatBuilder for the common case where only the field names and types are declared. Equivalent to creating a builder, calling gst_trace_format_builder_add_field for each pair and then gst_trace_format_builder_register.

Since : 1.30

GstTraceFormatBuilder

Since : 1.30

gst_trace_format_builder_add_field

GstTraceFormatBuilder *
gst_trace_format_builder_add_field (GstTraceFormatBuilder * builder,
                                    const gchar * name,
                                    GstTracerFieldType type)

Adds a positional field to the format. type must be one of G_TYPE_BOOLEAN, G_TYPE_INT, G_TYPE_UINT, G_TYPE_INT64, G_TYPE_UINT64, G_TYPE_DOUBLE, G_TYPE_STRING or G_TYPE_POINTER, matching the GstTraceValue union member callers will pass to gst_trace_span_begin. Duplicate field names are rejected.

Since : 1.30

gst_trace_format_builder_add_field_full

GstTraceFormatBuilder *
gst_trace_format_builder_add_field_full (GstTraceFormatBuilder * builder,
                                         GstTraceField * field)

Adds a positional field with optional metadata to the format. The field is consumed and freed by this call; do not use field afterwards.

Since : 1.30

gst_trace_format_builder_free

gst_trace_format_builder_free (GstTraceFormatBuilder * builder)

Frees an unregistered builder.

Since : 1.30

gst_trace_format_builder_register

GstTraceFormat *
gst_trace_format_builder_register (GstTraceFormatBuilder * builder)

Registers the format declared by builder and consumes the builder. The returned format is valid until gst_deinit.

Since : 1.30

gst_trace_format_builder_set_description

GstTraceFormatBuilder *
gst_trace_format_builder_set_description (GstTraceFormatBuilder * builder,
                                          const gchar * description)

Sets a human-readable description on the format being built. Replaces any previous description.

Since : 1.30

gst_trace_format_builder_new

GstTraceFormatBuilder *
gst_trace_format_builder_new (const gchar * name)

Creates a new builder for a span format. The builder is used to declare the span's field schema before registering it with gst_trace_format_builder_register.

Since : 1.30

GstTracer

GObject
    ╰──GInitiallyUnowned
        ╰──GstObject
            ╰──GstTracer

Class structure

gst_tracer_class_set_use_structure_params

gst_tracer_class_set_use_structure_params (GstTracerClass * tracer_class,
                                           gboolean use_structure_params)

Sets whether the tracer should use structure parameters for configuration. This function configures how parameters should be passed when instantiating the tracer.

This is typically called in the tracer's class initialization function to indicate its parameter handling preference.

Since : 1.26

gst_tracer_class_uses_structure_params

gboolean
gst_tracer_class_uses_structure_params (GstTracerClass * tracer_class)

If set, the tracer subsystem will consider parameters passed to the GST_TRACERS environment variable as a GstStructure and use its fields as properties to instanciate the tracer.

Since : 1.26

gst_tracer_register

gboolean
gst_tracer_register (GstPlugin * plugin,
                     const gchar * name,
                     GType type)

Create a new tracer-factory capable of instantiating objects of the type and add the factory to plugin.

params

“params” gchar *

Flags : Read / Write / Construct

GST_DEFINE_TRACE_FORMAT

#define GST_DEFINE_TRACE_FORMAT(getter, ...)                             \
  static GstTraceFormat *                                                 \
  getter (void)                                                               \
  {                                                                           \
    static gsize __once = 0;                                                  \
    static GstTraceFormat *__format = NULL;                               \
    if (g_once_init_enter (&__once)) {                                        \
      __format = gst_trace_format_register (#getter,            \
          _GST_TRACE_MAP_FIELDS (__VA_ARGS__), NULL);                                   \
      g_once_init_leave (&__once, 1);                                         \
    }                                                                         \
    return __format;                                                          \
  }

Defines a static getter that lazily registers the format on first call and caches it for the lifetime of the process. Subsequent calls return the cached GstTraceFormat.

Pass the getter to the scope macros to time a block.

GST_DEFINE_TRACE_FORMAT (decode_frame_span,
    "codec", STRING,
    "frame", UINT64)

static void
decode_frame (MyDecoder * self, guint64 frame)
{
  GST_TRACE_SCOPE_BEGIN (decode_frame_span,
      STRING (self->codec),
      UINT64 (frame));

  // ... decode the frame ...

  GST_TRACE_SCOPE_END (decode_frame_span);
}

When the span does not match a lexical scope, hold the GstTraceSpanId returned by gst_trace_span_begin and close it later with gst_trace_span_end. In both cases the field values are only evaluated while a tracer is listening.

Since : 1.30

GST_TRACER_CAST

#define GST_TRACER_CAST(obj)       ((GstTracer *)(obj))

GST_TRACE_BEGIN

#define GST_TRACE_BEGIN(format, ...) \
  (G_UNLIKELY (gst_trace_format_is_enabled (format)) ? \
      gst_trace_span_begin ((format), \
          GST_TRACE_VALUES (__VA_ARGS__)) : \
      GST_TRACE_SPAN_ID_NONE)

Opens a span and returns its GstTraceSpanId. When format has no listening tracer the values are not evaluated and GST_TRACE_SPAN_ID_NONE is returned. The caller closes the span with gst_trace_span_end or gst_trace_span_end_and_clear at the desired point; use this when the span lifetime does not match a lexical scope (see GST_TRACE_FUNC for the auto-closed variant).

Since : 1.30

GST_TRACE_EVENT

#define GST_TRACE_EVENT(format, ...) \
  gst_trace_event ((format), GST_TRACE_VALUES (__VA_ARGS__))

Emits a point event for format. Unlike GST_TRACE_BEGIN, an event has no duration and no matching end; it is the structured equivalent of the legacy GstTracerRecord log entry and is emitted whenever the GST_TRACER debug level is enabled. As with gst_tracer_record_log the values are always evaluated, so keep them cheap.

Since : 1.30

GST_TRACE_FUNC

#define GST_TRACE_FUNC(format, ...) \
  __attribute__((cleanup (_gst_trace_span_id_cleanup), unused)) \
  GST_TRACE_SCOPE_BEGIN (format, __VA_ARGS__)

Opens a span like GST_TRACE_SCOPE_BEGIN but closes it automatically when the enclosing block exits via return, goto, or fall-through, so no GST_TRACE_SCOPE_END call is needed.

Implemented with __attribute__((cleanup)). On compilers that do not support the attribute (stock MSVC) this macro expands to nothing and its arguments are not evaluated; use the GST_TRACE_SCOPE_BEGIN / GST_TRACE_SCOPE_END pair there instead.

Since : 1.30

GST_TRACE_SCOPE_BEGIN

#define GST_TRACE_SCOPE_BEGIN(format, ...) \
  GstTraceSpanId _GST_TRACE_SCOPE_VAR (format) = \
      (G_UNLIKELY (gst_trace_format_is_enabled (format ())) ? \
          gst_trace_span_begin (format (), GST_TRACE_VALUES (__VA_ARGS__)) : \
          GST_TRACE_SPAN_ID_NONE)

Opens a span and stores its GstTraceSpanId in a local variable named after format, so the matching GST_TRACE_SCOPE_END can close it without the caller declaring a span-id variable. When no tracer is listening the values are not evaluated and GST_TRACE_SPAN_ID_NONE is stored.

Calling GST_TRACE_SCOPE_BEGIN twice for the same format in the same scope is not allowed, since the variable name is derived from format.

The span remains open until the matching GST_TRACE_SCOPE_END is called

Since : 1.30

GST_TRACE_SCOPE_END

#define GST_TRACE_SCOPE_END(format) \
  gst_trace_span_end_and_clear (&_GST_TRACE_SCOPE_VAR (format))

Closes the span opened by GST_TRACE_SCOPE_BEGIN for format and resets the variable to GST_TRACE_SPAN_ID_NONE.

Since : 1.30

GST_TRACE_VALUES

#define GST_TRACE_VALUES(...) \
  ((const GstTraceValue[]) { _GST_TRACE_MAP_VALUES (__VA_ARGS__) })

Builds a positional GstTraceValue array suitable for gst_trace_span_begin. Values are positional and must match the field order declared on the corresponding GstTraceFormat.

Since : 1.30

GST_TRACE_VALUE_BOOLEAN

#define GST_TRACE_VALUE_BOOLEAN(x) ((GstTraceValue) { .v_boolean = (x) })

Builds a GstTraceValue holding x for use inside GST_TRACE_VALUES.

Since : 1.30

GST_TRACE_VALUE_CLOCK_TIME

#define GST_TRACE_VALUE_CLOCK_TIME(x) ((GstTraceValue) { .v_uint64 = (x) })

Since : 1.30

GST_TRACE_VALUE_DOUBLE

#define GST_TRACE_VALUE_DOUBLE(x)  ((GstTraceValue) { .v_double  = (x) })

Since : 1.30

GST_TRACE_VALUE_INT

#define GST_TRACE_VALUE_INT(x)     ((GstTraceValue) { .v_int     = (x) })

Since : 1.30

GST_TRACE_VALUE_INT64

#define GST_TRACE_VALUE_INT64(x)   ((GstTraceValue) { .v_int64   = (x) })

Since : 1.30

GST_TRACE_VALUE_OBJECT

#define GST_TRACE_VALUE_OBJECT(x)  ((GstTraceValue) { .v_object = (GObject *) (x) })

x must outlive the trace call.

Since : 1.30

GST_TRACE_VALUE_STRING

#define GST_TRACE_VALUE_STRING(x)  ((GstTraceValue) { .v_string  = (x) })

x must outlive the trace call. NULL is passed through unchanged so tracers can distinguish unset from empty strings.

Since : 1.30

GST_TRACE_VALUE_STRUCTURE

#define GST_TRACE_VALUE_STRUCTURE(x) ((GstTraceValue) { .v_structure = (x) })

x must outlive the trace call.

Since : 1.30

GST_TRACE_VALUE_UINT

#define GST_TRACE_VALUE_UINT(x)    ((GstTraceValue) { .v_uint    = (x) })

Since : 1.30

GST_TRACE_VALUE_UINT64

#define GST_TRACE_VALUE_UINT64(x)  ((GstTraceValue) { .v_uint64  = (x) })

Since : 1.30

_GST_TRACE_SCOPE_VAR

#define _GST_TRACE_SCOPE_VAR(format) G_PASTE (_gst_trace_span_id_, format)

Internal helper that derives the span-id variable name from a format getter, so a begin/end macro pair can share it without the caller naming a variable.

Since : 1.30

GstTracerFieldType

The type of a trace format field. This is a deliberately small, self contained set rather than a GType so the tracer stream stays independent of the GObject type system.

Since : 1.30

GstTracerValueFlags

Flag that describe the value. These flags help applications processing the logs to understand the values.

GstTracerValueScope

Tracing record will contain fields that contain a measured value or extra meta-data. One such meta data are values that tell where a measurement was taken. This enumeration declares to which scope such a meta data field relates to. If it is e.g. GST_TRACER_VALUE_SCOPE_PAD, then each of the log events may contain values for different GstPad.

Since : 1.8

GST_TRACE_SPAN_ID_NONE

#define GST_TRACE_SPAN_ID_NONE ((GstTraceSpanId) 0)

Sentinel GstTraceSpanId value meaning "no span". Returned by gst_trace_span_begin when no tracer is listening, and accepted as a no-op by gst_trace_span_end.

Since : 1.30

_GST_TRACE_FUNC_HAS_CLEANUP

#define _GST_TRACE_FUNC_HAS_CLEANUP 1

Internal gate for GST_TRACE_FUNC. Defined when the compiler exposes both cleanup and unused attributes via __has_attribute().

Since : 1.30

GstTraceSpanId

typedef guint64 GstTraceSpanId

Opaque identifier for an in-flight trace span. Returned by gst_trace_span_begin and passed to gst_trace_span_end.

Since : 1.30