Logging and Diagnostics

A GStreamer pipeline is verbose by nature: with GST_DEBUG turned up, every element reports on every buffer, and the output quickly reaches thousands of lines per second. That is the right tool when debugging an element’s internals, and the wrong one when the question is simply did my pipeline link the way I intended. The SDK therefore offers two ways to look at the same pipeline:

Simplified logs — the SDK reads GStreamer’s log stream, keeps only what is meaningful at application level (state changes, errors, performance figures), and reprints it in a compact, uniform format alongside its own diagnostics. This is the default.
Raw GStreamer logs — the SDK steps out of the way and lets GStreamer log exactly as it normally would, with GST_DEBUG fully in control.

Which one is active is decided by SetImsdkGstLogMode(); how much detail the SDK’s own diagnostics carry is decided independently by SetImsdkLogLevel().

Responsibilities

Route GStreamer’s log stream either through the SDK’s parser or through GStreamer’s default handler.
Filter the SDK’s own diagnostics by verbosity level.
Recognize state changes, errors, and performance reports in GStreamer’s output and re-emit them in a uniform format.
Restore GStreamer’s default log handler when the runtime shuts down.

APIs

Both functions live in the qti namespace and are declared in qti/imsdk-logging.h, which qti/imsdk.h includes.

`qti`	Description
`void SetImsdkLogLevel(ImsdkLogLevel level)`	Sets the verbosity of the SDK’s own diagnostics. Records below the selected level are suppressed. Effective at any time.
`void SetImsdkGstLogMode(ImsdkGstLogMode mode)`	Selects simplified or raw GStreamer logging. Must be called before the first element or pipeline is constructed — see the warning under Usage.

`ImsdkLogLevel`	Prints
`Error`	Failures only — including the caps of any pads left unlinked when a link or a state change fails.
`Warning`	The above, plus recoverable problems.
`Info`	The above, plus lifecycle milestones and pipeline state changes. Default.
`Debug`	Everything, plus the resolved topology — each element with its pad-to-pad connections and any still-pending deferred links — and the per-element performance figures reported by the Qualcomm plugins.

Simplified logs — `ImsdkGstLogMode::ImsdkLog`

The default. The SDK installs itself as GStreamer’s log handler, replacing the default one, and does two things with what arrives:

It lowers GStreamer’s global threshold to errors only, then re-enables the LOG level for a specific set of categories it knows how to interpret — GST_STATE, GST_STATES, and the Qualcomm element categories (qtimlvconverter, qtimlpostprocess, qtimltflite, qtivcomposer, qtivoverlay, and the rest). Everything else GStreamer would have printed is dropped before it reaches the terminal.
Of what remains, it recognizes three things and reformats them: completed state changes, errors, and performance/HW-utilization reports from the plugins. Each is reprinted through the SDK’s own logger, in the same format as the SDK’s diagnostics.

The result is one uniform stream, on standard output:

[QIM SDK][INFO][STATE][cam-pipeline] PLAYING
[QIM SDK][DEBUG][qtimltflite0] Performance time 12.4 ms, HW utilization: 38%
[QIM SDK][ERROR][qtimlpostprocess] postprocessing <error text from GStreamer>

Errors carry the GStreamer category and the offending object’s name before the message itself. Only the level token is colorized — red for ERROR, yellow for WARN, green for INFO — which is convenient interactively and unhelpful in a log file. Set IMSDK_LOG_COLOR to 0, false, or off to disable the escape codes.

Because this mode reconfigures GStreamer’s thresholds, a GST_DEBUG value set in the environment does not have its usual effect: categories the SDK does not interpret are silenced regardless. If you set GST_DEBUG and see less than you expected, this is why — use raw mode instead.

Raw GStreamer logs — `ImsdkGstLogMode::GstLog`

In this mode the SDK hands every record to gst_debug_log_default(), GStreamer’s own handler, without inspecting or reformatting it. GStreamer’s log configuration is left completely untouched: thresholds are not lowered, no categories are re-enabled, and GST_DEBUG behaves exactly as it does in any other GStreamer application.

GST_DEBUG=3 ./my-app                      # all categories, warnings and up
GST_DEBUG=qtimlvconverter:5 ./my-app      # one element, in full detail

Output goes to standard error in GStreamer’s familiar format — timestamp, PID, thread, level, category, file, line, object — and honours the usual GStreamer environment variables. Use raw mode when the problem is inside an element rather than in the graph: caps negotiation that fails for a non-obvious reason, an element misbehaving mid-stream, or anything where a GStreamer maintainer would ask for a full log. The SDK’s own diagnostics continue to be emitted as usual and remain governed by SetImsdkLogLevel().

Choosing between them

	Simplified (`ImsdkLog`)	Raw (`GstLog`)
Volume	A handful of lines per pipeline	Thousands of lines per second at high levels
Format	`[IMSDK][LEVEL]`, uniform with SDK diagnostics	GStreamer’s native format
Stream	Standard output	Standard error
`GST_DEBUG`	Overridden — only interpreted categories survive	Fully honoured
Best for	Did the graph build correctly? Is it running? How fast?	Why is this element failing internally?

Usage

Set the mode first, before any element, filter, or pipeline is constructed, and the level wherever it is convenient:

#include <qti/imsdk.h>

using namespace qti;

int main() {
  SetImsdkGstLogMode(ImsdkGstLogMode::ImsdkLog);
  SetImsdkLogLevel(ImsdkLogLevel::Debug);

  Pipeline pipeline("my-pipeline");
  pipeline
      .add("qtiqmmfsrc", "source")
      .add_stream_filter("vf", VideoFilter().format("NV12"))
      .add("waylandsink", "display", "fullscreen", true)
      .execute();

  return 0;
}

The log mode is read once, when the SDK’s runtime starts — which happens implicitly on the first Pipeline, Element, or StreamFilter that gets constructed. A SetImsdkGstLogMode() call after that point is silently ignored. Put it at the top of main(), before anything else from the SDK. SetImsdkLogLevel() has no such restriction and can be changed at any time.

When a pipeline fails to start or a link does not resolve, the caps of the unlinked pads are reported at Error level, so they appear without any configuration. Raise the level to Debug to also see the topology the pipeline actually built — the quickest way to confirm that a deferred link resolved to the pad you expected. Reach for raw mode only once the graph itself is known to be correct.

SDK Architecture and API Reference — the Pipeline, Element, and filter APIs whose behaviour these logs describe.
Quick start guide — installation and a first pipeline.

Getting Started

Examples

Design

Plugins

Responsibilities

APIs

Simplified logs — `ImsdkGstLogMode::ImsdkLog`

Raw GStreamer logs — `ImsdkGstLogMode::GstLog`

Choosing between them

Usage

​Responsibilities

​APIs

​Simplified logs — ImsdkGstLogMode::ImsdkLog

​Raw GStreamer logs — ImsdkGstLogMode::GstLog

​Choosing between them

​Usage

​Related

Responsibilities

APIs

Simplified logs — `ImsdkGstLogMode::ImsdkLog`

Raw GStreamer logs — `ImsdkGstLogMode::GstLog`

Choosing between them

Usage

Related