# GstTracer

Tracing modules will subclass GstTracer and register through gst_tracer_register. Modules can attach to various hook-types - see gst_tracing_register_hook. When invoked they receive hook specific contextual data, which they must not modify.

## GstTraceField

Transient field descriptor created by gst_trace_field_new and added to a GstTraceFormatBuilder.

Since : 1.30

## Gst.TraceField

Transient field descriptor created by gst_trace_field_new (not introspectable) and added to a Gst.TraceFormatBuilder.

Since : 1.30

## Gst.TraceField

Transient field descriptor created by gst_trace_field_new (not introspectable) and added to a Gst.TraceFormatBuilder.

Since : 1.30

### Methods

#### gst_trace_field_free

    gst_trace_field_free (GstTraceField * field)

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

Parameters:

`field` ( [transfer: full][nullable]) –

a GstTraceField

Since : 1.30

#### Gst.TraceField.prototype.free

    function Gst.TraceField.prototype.free(): {
        // javascript wrapper for 'gst_trace_field_free'
    }

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

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

Since : 1.30

#### Gst.TraceField.free

    def Gst.TraceField.free (self):
        #python wrapper for 'gst_trace_field_free'

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

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

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.

Parameters:

`field` –

a GstTraceField

`description` ( [nullable]) –

a human-readable description; NULL clears any previously set description

Returns ( [transfer: none]) –

field for chaining

Since : 1.30

#### Gst.TraceField.prototype.set_description

    function Gst.TraceField.prototype.set_description(description: String): {
        // javascript wrapper for 'gst_trace_field_set_description'
    }

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

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

`description` (String) –

a human-readable description; null clears any previously set description

Returns (Gst.TraceField) –

field for chaining

Since : 1.30

#### Gst.TraceField.set_description

    def Gst.TraceField.set_description (self, description):
        #python wrapper for 'gst_trace_field_set_description'

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

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

`description` (str) –

a human-readable description; None clears any previously set description

Returns (Gst.TraceField) –

field for chaining

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.

Parameters:

`field` –

a GstTraceField

`flags` –

the GstTracerValueFlags describing the field

Returns ( [transfer: none]) –

field for chaining

Since : 1.30

#### Gst.TraceField.prototype.set_flags

    function Gst.TraceField.prototype.set_flags(flags: Gst.TracerValueFlags): {
        // javascript wrapper for 'gst_trace_field_set_flags'
    }

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

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

`flags` (Gst.TracerValueFlags) –

the Gst.TracerValueFlags describing the field

Returns (Gst.TraceField) –

field for chaining

Since : 1.30

#### Gst.TraceField.set_flags

    def Gst.TraceField.set_flags (self, flags):
        #python wrapper for 'gst_trace_field_set_flags'

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

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

`flags` (Gst.TracerValueFlags) –

the Gst.TracerValueFlags describing the field

Returns (Gst.TraceField) –

field for chaining

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.

Parameters:

`field` –

a GstTraceField

`scope` –

the GstTracerValueScope the field relates to

Returns ( [transfer: none]) –

field for chaining

Since : 1.30

#### Gst.TraceField.prototype.set_scope

    function Gst.TraceField.prototype.set_scope(scope: Gst.TracerValueScope): {
        // javascript wrapper for 'gst_trace_field_set_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.

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

`scope` (Gst.TracerValueScope) –

the Gst.TracerValueScope the field relates to

Returns (Gst.TraceField) –

field for chaining

Since : 1.30

#### Gst.TraceField.set_scope

    def Gst.TraceField.set_scope (self, scope):
        #python wrapper for 'gst_trace_field_set_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.

Parameters:

`field` (Gst.TraceField) –

a Gst.TraceField

`scope` (Gst.TracerValueScope) –

the Gst.TracerValueScope the field relates to

Returns (Gst.TraceField) –

field for chaining

Since : 1.30

### Functions

#### 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.

Parameters:

`name` –

the field name

`type` –

the field GstTracerFieldType

Returns ( [transfer: full]) –

a new GstTraceField

Since : 1.30

## GstTraceFormat

Opaque registered format describing the fields of a trace span. Obtain one via gst_trace_format_register or GST_DEFINE_TRACE_FORMAT and pass it to gst_trace_span_begin.

Since : 1.30

## Gst.TraceFormat

Opaque registered format describing the fields of a trace span. Obtain one via gst_trace_format_register (not introspectable) or GST_DEFINE_TRACE_FORMAT (not introspectable) and pass it to Gst.prototype.trace_span_begin.

Since : 1.30

## Gst.TraceFormat

Opaque registered format describing the fields of a trace span. Obtain one via gst_trace_format_register (not introspectable) or GST_DEFINE_TRACE_FORMAT (not introspectable) and pass it to Gst.trace_span_begin.

Since : 1.30

### Methods

#### gst_trace_format_get_description

    const gchar *
    gst_trace_format_get_description (GstTraceFormat * format)

Parameters:

`format` –

a GstTraceFormat

Returns ( [transfer: none][nullable]) –

the description set on the builder, or NULL if none was set

Since : 1.30

#### Gst.TraceFormat.prototype.get_description

    function Gst.TraceFormat.prototype.get_description(): {
        // javascript wrapper for 'gst_trace_format_get_description'
    }

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (String) –

the description set on the builder, or null if none was set

Since : 1.30

#### Gst.TraceFormat.get_description

    def Gst.TraceFormat.get_description (self):
        #python wrapper for 'gst_trace_format_get_description'

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (str) –

the description set on the builder, or None if none was set

Since : 1.30

#### gst_trace_format_get_field_description

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

Parameters:

`format` –

a GstTraceFormat

`index` –

a field index

Returns ( [transfer: none][nullable]) –

the description declared for the field at index, or NULL if no description was set (or index is out of range)

Since : 1.30

#### Gst.TraceFormat.prototype.get_field_description

    function Gst.TraceFormat.prototype.get_field_description(index: Number): {
        // javascript wrapper for 'gst_trace_format_get_field_description'
    }

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (Number) –

a field index

Returns (String) –

the description declared for the field at index, or null if no description was set (or index is out of range)

Since : 1.30

#### Gst.TraceFormat.get_field_description

    def Gst.TraceFormat.get_field_description (self, index):
        #python wrapper for 'gst_trace_format_get_field_description'

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (int) –

a field index

Returns (str) –

the description declared for the field at index, or None if no description was set (or index is out of range)

Since : 1.30

#### gst_trace_format_get_field_name

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

Parameters:

`format` –

a GstTraceFormat

`index` –

a field index

Returns ( [transfer: none]) –

the name of the field at index, or NULL if index is out of range

Since : 1.30

#### Gst.TraceFormat.prototype.get_field_name

    function Gst.TraceFormat.prototype.get_field_name(index: Number): {
        // javascript wrapper for 'gst_trace_format_get_field_name'
    }

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (Number) –

a field index

Returns (String) –

the name of the field at index, or null if index is out of range

Since : 1.30

#### Gst.TraceFormat.get_field_name

    def Gst.TraceFormat.get_field_name (self, index):
        #python wrapper for 'gst_trace_format_get_field_name'

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (int) –

a field index

Returns (str) –

the name of the field at index, or None if index is out of range

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"`).

Parameters:

`format` –

a GstTraceFormat

`index` –

a field index

Returns ( [transfer: none][nullable]) –

the field structure, or NULL if index is out of range

Since : 1.30

#### Gst.TraceFormat.prototype.get_field_structure

    function Gst.TraceFormat.prototype.get_field_structure(index: Number): {
        // javascript wrapper for 'gst_trace_format_get_field_structure'
    }

Returns the raw Gst.Structure describing the field at index. The structure carries the field's type (`"type"`, a Gst.TracerFieldType stored as Number) and any optional metadata declared via Gst.TraceFormatBuilder.prototype.add_field_full (e.g. `"description"`).

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (Number) –

a field index

Returns (Gst.Structure) –

the field structure, or null if index is out of range

Since : 1.30

#### Gst.TraceFormat.get_field_structure

    def Gst.TraceFormat.get_field_structure (self, index):
        #python wrapper for 'gst_trace_format_get_field_structure'

Returns the raw Gst.Structure describing the field at index. The structure carries the field's type (`"type"`, a Gst.TracerFieldType stored as int) and any optional metadata declared via Gst.TraceFormatBuilder.add_field_full (e.g. `"description"`).

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (int) –

a field index

Returns (Gst.Structure) –

the field structure, or None if index is out of range

Since : 1.30

#### gst_trace_format_get_field_type

    GstTracerFieldType
    gst_trace_format_get_field_type (GstTraceFormat * format,
                                     guint index)

Parameters:

`format` –

a GstTraceFormat

`index` –

a field index

Returns –

the GstTracerFieldType of the field at index (defaults to GST_TRACER_FIELD_TYPE_BOOLEAN if index is out of range)

Since : 1.30

#### Gst.TraceFormat.prototype.get_field_type

    function Gst.TraceFormat.prototype.get_field_type(index: Number): {
        // javascript wrapper for 'gst_trace_format_get_field_type'
    }

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (Number) –

a field index

Returns (Gst.TracerFieldType) –

the Gst.TracerFieldType of the field at index (defaults to Gst.TracerFieldType.BOOLEAN if index is out of range)

Since : 1.30

#### Gst.TraceFormat.get_field_type

    def Gst.TraceFormat.get_field_type (self, index):
        #python wrapper for 'gst_trace_format_get_field_type'

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

`index` (int) –

a field index

Returns (Gst.TracerFieldType) –

the Gst.TracerFieldType of the field at index (defaults to Gst.TracerFieldType.BOOLEAN if index is out of range)

Since : 1.30

#### gst_trace_format_get_n_fields

    guint
    gst_trace_format_get_n_fields (GstTraceFormat * format)

Parameters:

`format` –

a GstTraceFormat

Returns –

the number of fields declared on format

Since : 1.30

#### Gst.TraceFormat.prototype.get_n_fields

    function Gst.TraceFormat.prototype.get_n_fields(): {
        // javascript wrapper for 'gst_trace_format_get_n_fields'
    }

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (Number) –

the number of fields declared on format

Since : 1.30

#### Gst.TraceFormat.get_n_fields

    def Gst.TraceFormat.get_n_fields (self):
        #python wrapper for 'gst_trace_format_get_n_fields'

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (int) –

the number of fields declared on format

Since : 1.30

#### gst_trace_format_get_name

    const gchar *
    gst_trace_format_get_name (GstTraceFormat * format)

Parameters:

`format` –

a GstTraceFormat

Returns ( [transfer: none]) –

the registered span name

Since : 1.30

#### Gst.TraceFormat.prototype.get_name

    function Gst.TraceFormat.prototype.get_name(): {
        // javascript wrapper for 'gst_trace_format_get_name'
    }

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (String) –

the registered span name

Since : 1.30

#### Gst.TraceFormat.get_name

    def Gst.TraceFormat.get_name (self):
        #python wrapper for 'gst_trace_format_get_name'

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (str) –

the registered span name

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.

Parameters:

`format` –

a GstTraceFormat

Returns –

TRUE if any tracer is active

Since : 1.30

#### Gst.TraceFormat.prototype.is_enabled

    function Gst.TraceFormat.prototype.is_enabled(): {
        // javascript wrapper for 'gst_trace_format_is_enabled'
    }

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.

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (Number) –

true if any tracer is active

Since : 1.30

#### Gst.TraceFormat.is_enabled

    def Gst.TraceFormat.is_enabled (self):
        #python wrapper for 'gst_trace_format_is_enabled'

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.

Parameters:

`format` (Gst.TraceFormat) –

a Gst.TraceFormat

Returns (bool) –

True if any tracer is active

Since : 1.30

### Functions

#### 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.

Parameters:

`name` –

the span name

`...` –

NULL-terminated list of (field-name, GType) pairs

Returns ( [transfer: none]) –

the registered GstTraceFormat

Since : 1.30

## GstTraceFormatBuilder

Opaque, chainable builder used to assemble a GstTraceFormat field by field; consumed by gst_trace_format_builder_register.

Since : 1.30

## Gst.TraceFormatBuilder

Opaque, chainable builder used to assemble a Gst.TraceFormat field by field; consumed by Gst.TraceFormatBuilder.prototype.register.

Since : 1.30

## Gst.TraceFormatBuilder

Opaque, chainable builder used to assemble a Gst.TraceFormat field by field; consumed by Gst.TraceFormatBuilder.register.

Since : 1.30

### Methods

#### 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.

Parameters:

`builder` –

a GstTraceFormatBuilder

`name` –

the field name

`type` –

the field GType

Returns ( [transfer: none]) –

builder for chaining

Since : 1.30

#### Gst.TraceFormatBuilder.prototype.add_field

    function Gst.TraceFormatBuilder.prototype.add_field(name: String, type: Gst.TracerFieldType): {
        // javascript wrapper for 'gst_trace_format_builder_add_field'
    }

Adds a positional field to the format. type must be one of G_TYPE_BOOLEAN (not introspectable), G_TYPE_INT (not introspectable), G_TYPE_UINT (not introspectable), G_TYPE_INT64 (not introspectable), G_TYPE_UINT64 (not introspectable), G_TYPE_DOUBLE (not introspectable), G_TYPE_STRING (not introspectable) or G_TYPE_POINTER (not introspectable), matching the `GstTraceValue` union member callers will pass to Gst.prototype.trace_span_begin. Duplicate field names are rejected.

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

`name` (String) –

the field name

`type` (Gst.TracerFieldType) –

the field GObject.Type

Returns (Gst.TraceFormatBuilder) –

builder for chaining

Since : 1.30

#### Gst.TraceFormatBuilder.add_field

    def Gst.TraceFormatBuilder.add_field (self, name, type):
        #python wrapper for 'gst_trace_format_builder_add_field'

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

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

`name` (str) –

the field name

`type` (Gst.TracerFieldType) –

the field GObject.Type

Returns (Gst.TraceFormatBuilder) –

builder for chaining

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.

Parameters:

`builder` –

a GstTraceFormatBuilder

`field` ( [transfer: full]) –

a GstTraceField built via gst_trace_field_new and optionally configured with chainable setters such as gst_trace_field_set_description

Returns ( [transfer: none]) –

builder for chaining

Since : 1.30

#### Gst.TraceFormatBuilder.prototype.add_field_full

    function Gst.TraceFormatBuilder.prototype.add_field_full(field: Gst.TraceField): {
        // javascript wrapper for 'gst_trace_format_builder_add_field_full'
    }

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

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

`field` (Gst.TraceField) –

a Gst.TraceField built via gst_trace_field_new (not introspectable) and optionally configured with chainable setters such as Gst.TraceField.prototype.set_description

Returns (Gst.TraceFormatBuilder) –

builder for chaining

Since : 1.30

#### Gst.TraceFormatBuilder.add_field_full

    def Gst.TraceFormatBuilder.add_field_full (self, field):
        #python wrapper for 'gst_trace_format_builder_add_field_full'

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

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

`field` (Gst.TraceField) –

a Gst.TraceField built via gst_trace_field_new (not introspectable) and optionally configured with chainable setters such as Gst.TraceField.set_description

Returns (Gst.TraceFormatBuilder) –

builder for chaining

Since : 1.30

#### gst_trace_format_builder_free

    gst_trace_format_builder_free (GstTraceFormatBuilder * builder)

Frees an unregistered builder.

Parameters:

`builder` ( [transfer: full][nullable]) –

a GstTraceFormatBuilder

Since : 1.30

#### Gst.TraceFormatBuilder.prototype.free

    function Gst.TraceFormatBuilder.prototype.free(): {
        // javascript wrapper for 'gst_trace_format_builder_free'
    }

Frees an unregistered builder.

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

Since : 1.30

#### Gst.TraceFormatBuilder.free

    def Gst.TraceFormatBuilder.free (self):
        #python wrapper for 'gst_trace_format_builder_free'

Frees an unregistered builder.

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

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.

Parameters:

`builder` ( [transfer: full]) –

a GstTraceFormatBuilder

Returns ( [transfer: none]) –

the registered GstTraceFormat

Since : 1.30

#### Gst.TraceFormatBuilder.prototype.register

    function Gst.TraceFormatBuilder.prototype.register(): {
        // javascript wrapper for 'gst_trace_format_builder_register'
    }

Registers the format declared by builder and consumes the builder. The returned format is valid until Gst.prototype.deinit.

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

Returns (Gst.TraceFormat) –

the registered Gst.TraceFormat

Since : 1.30

#### Gst.TraceFormatBuilder.register

    def Gst.TraceFormatBuilder.register (self):
        #python wrapper for 'gst_trace_format_builder_register'

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

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

Returns (Gst.TraceFormat) –

the registered Gst.TraceFormat

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.

Parameters:

`builder` –

a GstTraceFormatBuilder

`description` ( [nullable]) –

a human-readable description

Returns ( [transfer: none]) –

builder for chaining

Since : 1.30

#### Gst.TraceFormatBuilder.prototype.set_description

    function Gst.TraceFormatBuilder.prototype.set_description(description: String): {
        // javascript wrapper for 'gst_trace_format_builder_set_description'
    }

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

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

`description` (String) –

a human-readable description

Returns (Gst.TraceFormatBuilder) –

builder for chaining

Since : 1.30

#### Gst.TraceFormatBuilder.set_description

    def Gst.TraceFormatBuilder.set_description (self, description):
        #python wrapper for 'gst_trace_format_builder_set_description'

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

Parameters:

`builder` (Gst.TraceFormatBuilder) –

a Gst.TraceFormatBuilder

`description` (str) –

a human-readable description

Returns (Gst.TraceFormatBuilder) –

builder for chaining

Since : 1.30

### Functions

#### 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.

Parameters:

`name` –

the span name

Returns ( [transfer: full]) –

a new GstTraceFormatBuilder

Since : 1.30

## GstTracer

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

The opaque GstTracer instance structure

### Members

`parent` (GstObject) –
No description available

### Class structure

#### GstTracerClass

##### Fields

`parent_class` (GstObjectClass) –
No description available

### Gst.TracerClass

##### Attributes

`parent_class` (Gst.ObjectClass) –
No description available

### Gst.TracerClass

##### Attributes

`parent_class` (Gst.ObjectClass) –
No description available

## Gst.Tracer

    GObject.Object
        ╰──GObject.InitiallyUnowned
            ╰──Gst.Object
                ╰──Gst.Tracer

The opaque GstTracer instance structure

### Members

`parent` (Gst.Object) –
No description available

## Gst.Tracer

    GObject.Object
        ╰──GObject.InitiallyUnowned
            ╰──Gst.Object
                ╰──Gst.Tracer

The opaque GstTracer instance structure

### Members

`parent` (Gst.Object) –
No description available

### Class Methods

#### 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.

Parameters:

`tracer_class` –

the GstTracerFactoryClass to mark as using structure parameters

`use_structure_params` –

TRUE to use structure parameters, FALSE otherwise

Since : 1.26

#### Gst.TracerClass.prototype.set_use_structure_params

    function Gst.TracerClass.prototype.set_use_structure_params(tracer_class: Gst.TracerClass, use_structure_params: Number): {
        // javascript wrapper for 'gst_tracer_class_set_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.

Parameters:

`tracer_class` (Gst.TracerClass) –

the Gst.TracerFactoryClass to mark as using structure parameters

`use_structure_params` (Number) –

true to use structure parameters, false otherwise

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.

Parameters:

`tracer_class` –

the GstTracerClass to to check

Returns –

TRUE if the tracer uses structure parameters, FALSE otherwise

Since : 1.26

#### Gst.TracerClass.prototype.uses_structure_params

    function Gst.TracerClass.prototype.uses_structure_params(tracer_class: Gst.TracerClass): {
        // javascript wrapper for 'gst_tracer_class_uses_structure_params'
    }

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

Parameters:

`tracer_class` (Gst.TracerClass) –

the Gst.TracerClass to to check

Returns (Number) –

true if the tracer uses structure parameters, false otherwise

Since : 1.26

### Functions

#### 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.

Parameters:

`plugin` ( [allow-none]) –

A GstPlugin, or NULL for a static typefind function

`name` –

The name for registering

`type` –

GType of tracer to register

Returns –

TRUE, if the registering succeeded, FALSE on error

#### Gst.Tracer.prototype.register

    function Gst.Tracer.prototype.register(plugin: Gst.Plugin, name: String, type: GObject.Type): {
        // javascript wrapper for 'gst_tracer_register'
    }

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

Parameters:

`plugin` (Gst.Plugin) –

A Gst.Plugin, or null for a static typefind function

`name` (String) –

The name for registering

`type` (GObject.Type) –

GType of tracer to register

Returns (Number) –

true, if the registering succeeded, false on error

#### Gst.Tracer.register

    def Gst.Tracer.register (plugin, name, type):
        #python wrapper for 'gst_tracer_register'

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

Parameters:

`plugin` (Gst.Plugin) –

A Gst.Plugin, or None for a static typefind function

`name` (str) –

The name for registering

`type` (GObject.Type) –

GType of tracer to register

Returns (bool) –

True, if the registering succeeded, False on error

### Properties

#### params

    “params” gchar *

Flags : Read / Write / Construct

#### params

    “params” String

Flags : Read / Write / Construct

#### params

    “self.props.params” str

Flags : Read / Write / Construct

## Function Macros

### 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.

Parameters:

`getter` –

identifier of the getter function to define; its name is also used verbatim as the span name surfaced to tracers

`...` –

at least one (field-name, short-field-type) pair, where the type is a GstTracerFieldType name without the `GST_TRACER_FIELD_TYPE_` prefix (e.g. `STRING`, `UINT64`); the NULL terminator is added automatically

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).

Parameters:

`format` –

a GstTraceFormat (typically the result of a getter declared with GST_DEFINE_TRACE_FORMAT)

`...` –

one or more GST_TRACE_VALUE_* entries, in the field order declared on format

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.

Parameters:

`format` –

a GstTraceFormat (typically the result of a getter declared with GST_DEFINE_TRACE_FORMAT)

`...` –

one or more GST_TRACE_VALUE_* entries, in the field order declared on format

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.

Parameters:

`format` –

a span format getter declared with GST_DEFINE_TRACE_FORMAT

`...` –

one or more GST_TRACE_VALUE_* entries, in the field order declared on format

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

Parameters:

`format` –

a span format getter declared with GST_DEFINE_TRACE_FORMAT

`...` –

one or more GST_TRACE_VALUE_* entries, in the field order declared on format

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.

Parameters:

`format` –

the span format getter passed to the matching GST_TRACE_SCOPE_BEGIN

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.

Parameters:

`...` –

one or more short value entries, e.g. `STRING (s)`, `UINT (n)`, `OBJECT (o)`; each names a `GST_TRACE_VALUE_*` constructor without the `GST_TRACE_VALUE_` prefix

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.

Parameters:

`x` –

a gboolean value

Since : 1.30

### GST_TRACE_VALUE_CLOCK_TIME

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

Parameters:

`x` –

a GstClockTime value

Since : 1.30

### GST_TRACE_VALUE_DOUBLE

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

Parameters:

`x` –

a gdouble value

Since : 1.30

### GST_TRACE_VALUE_INT

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

Parameters:

`x` –

a gint value

Since : 1.30

### GST_TRACE_VALUE_INT64

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

Parameters:

`x` –

a gint64 value

Since : 1.30

### GST_TRACE_VALUE_OBJECT

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

x must outlive the trace call.

Parameters:

`x` ( [nullable]) –

a borrowed GObject

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.

Parameters:

`x` ( [nullable]) –

a borrowed gchar pointer; NULL means the field is unset

Since : 1.30

### GST_TRACE_VALUE_STRUCTURE

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

x must outlive the trace call.

Parameters:

`x` ( [nullable]) –

a borrowed GstStructure

Since : 1.30

### GST_TRACE_VALUE_UINT

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

Parameters:

`x` –

a guint value

Since : 1.30

### GST_TRACE_VALUE_UINT64

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

Parameters:

`x` –

a guint64 value

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

## Enumerations

### 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.

##### Members

`GST_TRACER_FIELD_TYPE_BOOLEAN` (0) –

a gboolean

`GST_TRACER_FIELD_TYPE_INT` (1) –

a gint

`GST_TRACER_FIELD_TYPE_UINT` (2) –

a guint

`GST_TRACER_FIELD_TYPE_INT64` (3) –

a gint64

`GST_TRACER_FIELD_TYPE_UINT64` (4) –

a guint64

`GST_TRACER_FIELD_TYPE_DOUBLE` (5) –

a gdouble

`GST_TRACER_FIELD_TYPE_STRING` (6) –

a borrowed string (may be NULL)

`GST_TRACER_FIELD_TYPE_CLOCK_TIME` (7) –

a GstClockTime

`GST_TRACER_FIELD_TYPE_STRUCTURE` (8) –

a borrowed GstStructure (may be NULL)

`GST_TRACER_FIELD_TYPE_OBJECT` (9) –

a borrowed GObject (may be NULL)

Since : 1.30

### Gst.TracerFieldType

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

##### Members

`Gst.TracerFieldType.BOOLEAN` (0) –

a Number

`Gst.TracerFieldType.INT` (1) –

a Number

`Gst.TracerFieldType.UINT` (2) –

a Number

`Gst.TracerFieldType.INT64` (3) –

a Number

`Gst.TracerFieldType.UINT64` (4) –

a Number

`Gst.TracerFieldType.DOUBLE` (5) –

a Number

`Gst.TracerFieldType.STRING` (6) –

a borrowed string (may be null)

`Gst.TracerFieldType.CLOCK_TIME` (7) –

a Number

`Gst.TracerFieldType.STRUCTURE` (8) –

a borrowed Gst.Structure (may be null)

`Gst.TracerFieldType.OBJECT` (9) –

a borrowed GObject.Object (may be null)

Since : 1.30

### Gst.TracerFieldType

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

##### Members

`Gst.TracerFieldType.BOOLEAN` (0) –

a bool

`Gst.TracerFieldType.INT` (1) –

a int

`Gst.TracerFieldType.UINT` (2) –

a int

`Gst.TracerFieldType.INT64` (3) –

a int

`Gst.TracerFieldType.UINT64` (4) –

a int

`Gst.TracerFieldType.DOUBLE` (5) –

a float

`Gst.TracerFieldType.STRING` (6) –

a borrowed string (may be None)

`Gst.TracerFieldType.CLOCK_TIME` (7) –

a int

`Gst.TracerFieldType.STRUCTURE` (8) –

a borrowed Gst.Structure (may be None)

`Gst.TracerFieldType.OBJECT` (9) –

a borrowed GObject.Object (may be None)

Since : 1.30

### GstTracerValueFlags

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

##### Members

`GST_TRACER_VALUE_FLAGS_NONE` (0) –

no flags

`GST_TRACER_VALUE_FLAGS_OPTIONAL` (1) –

the value is optional. When using this flag one need to have an additional boolean arg before this value in the var-args list passed to gst_tracer_record_log.

`GST_TRACER_VALUE_FLAGS_AGGREGATED` (2) –

the value is a combined figure, since the start of tracing. Examples are averages or accumulated durations.

### Gst.TracerValueFlags

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

##### Members

`Gst.TracerValueFlags.NONE` (0) –

no flags

`Gst.TracerValueFlags.OPTIONAL` (1) –

the value is optional. When using this flag one need to have an additional boolean arg before this value in the var-args list passed to gst_tracer_record_log (not introspectable).

`Gst.TracerValueFlags.AGGREGATED` (2) –

the value is a combined figure, since the start of tracing. Examples are averages or accumulated durations.

### Gst.TracerValueFlags

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

##### Members

`Gst.TracerValueFlags.NONE` (0) –

no flags

`Gst.TracerValueFlags.OPTIONAL` (1) –

the value is optional. When using this flag one need to have an additional boolean arg before this value in the var-args list passed to gst_tracer_record_log (not introspectable).

`Gst.TracerValueFlags.AGGREGATED` (2) –

the value is a combined figure, since the start of tracing. Examples are averages or accumulated durations.

### 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.

##### Members

`GST_TRACER_VALUE_SCOPE_PROCESS` (0) –

the value is related to the process

`GST_TRACER_VALUE_SCOPE_THREAD` (1) –

the value is related to a thread

`GST_TRACER_VALUE_SCOPE_ELEMENT` (2) –

the value is related to an GstElement

`GST_TRACER_VALUE_SCOPE_PAD` (3) –

the value is related to a GstPad

Since : 1.8

### Gst.TracerValueScope

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.TracerValueScope.PAD, then each of the log events may contain values for different Gst.Pad.

##### Members

`Gst.TracerValueScope.PROCESS` (0) –

the value is related to the process

`Gst.TracerValueScope.THREAD` (1) –

the value is related to a thread

`Gst.TracerValueScope.ELEMENT` (2) –

the value is related to an Gst.Element

`Gst.TracerValueScope.PAD` (3) –

the value is related to a Gst.Pad

Since : 1.8

### Gst.TracerValueScope

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.TracerValueScope.PAD, then each of the log events may contain values for different Gst.Pad.

##### Members

`Gst.TracerValueScope.PROCESS` (0) –

the value is related to the process

`Gst.TracerValueScope.THREAD` (1) –

the value is related to a thread

`Gst.TracerValueScope.ELEMENT` (2) –

the value is related to an Gst.Element

`Gst.TracerValueScope.PAD` (3) –

the value is related to a Gst.Pad

Since : 1.8

## Constants

### 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_SPAN_ID_NONE

Sentinel Number value meaning "no span". Returned by Gst.prototype.trace_span_begin when no tracer is listening, and accepted as a no-op by Gst.prototype.trace_span_end.

Since : 1.30

### Gst.TRACE_SPAN_ID_NONE

Sentinel int 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

## Aliases

### 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

The results of the search are