Skip to main content

Diagnostics In 3 Commands

FieldValue
DifficultyIntermediate
Estimated Read Time<10 minutes
Labelsdiagnostics, debugging, observability

Concept​

This tutorial gives you a compact three-step diagnostics workflow you can run before deep debugging.

The goal is to answer three questions quickly:

  1. Is the session contract/build valid?
  2. Does one run succeed with metrics enabled?
  3. What do runtime diagnostics report about performance and behavior?

This chapter is especially useful when onboarding new models or environments, because it provides a repeatable triage baseline before diving into plugin internals.

Reference:

Learning Process​

  1. Validate session contract and backend parse path (validate()).
  2. Run one deterministic frame with metrics enabled.
  3. Inspect runtime stats/report/diagnostic summary outputs.
  4. Use CHECK, SIGNATURE, and [OK] markers to gate readiness.

Run​

NEAT_EXTRAS_ROOT=<sima-neat-*-Linux-extras>
cd $NEAT_EXTRAS_ROOT/lib/sima-neat/tutorials
./tutorial_v2_011_diagnostics_in_3_commands

Code​

tutorials/011_diagnostics_in_3_commands/diagnostics_in_3_commands.cpp
// Three diagnostic commands: Session::validate, Run::stats, Run::report / diagnostics_summary.
//
// Usage:
//   tutorial_v2_011_diagnostics_in_3_commands

#include "neat.h"

#include <opencv2/core.hpp>

#include <iostream>
#include <stdexcept>

int main() {
  try {
    cv::Mat rgb(96, 128, CV_8UC3, cv::Scalar(22, 44, 66));
    if (!rgb.isContinuous())
      rgb = rgb.clone();

    simaai::neat::Session session;
    simaai::neat::InputOptions in;
    in.format = "RGB";
    in.width = rgb.cols;
    in.height = rgb.rows;
    in.depth = rgb.channels();
    session.add(simaai::neat::nodes::Input(in));
    session.add(simaai::neat::nodes::Output());

    // CORE LOGIC
    // 1) validate() checks the Session before build() and prints any caps problems.
    auto report = session.validate();
    std::cout << "validate.error_code=" << report.error_code << "\n";

    // 2) Run the Session with metrics enabled so stats() has data.
    simaai::neat::RunOptions run_opt;
    run_opt.enable_metrics = true;
    run_opt.output_memory = simaai::neat::OutputMemory::Owned;
    auto run = session.build(rgb, simaai::neat::RunMode::Sync, run_opt);
    auto out = run.push_and_pull(rgb, /*timeout_ms=*/1000);
    if (!out.tensor.has_value())
      throw std::runtime_error("missing output tensor");

    // 3) Post-run diagnostics: counters, per-element report, and a summary string.
    auto stats = run.stats();
    std::cout << "stats.inputs_enqueued=" << stats.inputs_enqueued
              << " outputs_pulled=" << stats.outputs_pulled << "\n";
    std::cout << "report.size=" << run.report().size() << "\n";
    std::cout << "diagnostics_summary=" << run.diagnostics_summary() << "\n";

    std::cout << "[OK] 011_diagnostics_in_3_commands\n";
    return 0;
  } catch (const std::exception& e) {
    std::cerr << "[FAIL] " << e.what() << "\n";
    return 1;
  }
}

Source​