Діагностика та налагодження.

Звіт про граф.

GraphReport збирає структуровані дані для діагностики:

• рядок конвеєра (для відтворення)
• канонічний error_code (автоматизована класифікація)
• repro_note (короткий опис, зрозумілий людині + підказка)
• звіти вузлів і назви керованих елементів
• повідомлення та деталі про помилки, що стосуються шини даних.
• необов’язкові лічильники потоку/часу

У разі виникнення помилки, NeatError містить GraphReport, який можна записати в журнал або серіалізувати.

Таксономія помилок

У разі виникнення помилок у фреймворку використовуються стабільні кодові бази:

Код помилки	Опис	Типове рішення
misconfig.pipeline_shape	Порушення правил щодо порядку/структури вузлів у конвеєрі	Переконайтеся, що Input() розміщено першим у конвеєрах, які передають дані, і Output() – останнім у конвеєрах, які отримують дані
misconfig.caps	Несумісність через неправильну конфігурацію або невідповідність контракту сусіднього вузла	Узгодьте caps_override та оголошені контракти вузлів
misconfig.input_shape	Форма або тип даних вхідного тензора/кадру/зразка не відповідає вимогам моделі.	Вкажіть очікувану форму та тип даних або налаштуйте попередню обробку моделі.
misconfig.runtime_abi_mismatch	Neat і плагін середовища виконання використовують несумісні ABI	Встановіть версію Neat Library, яка відповідає версії середовища виконання.
misconfig.graph_element_name	Не можна призначити користувацькому елементу стабільне ім’я вузла	Надавайте користувацьким елементам стабільні, унікальні імена
misconfig.input_capacity	Зображення-джерело перевищує допустимі розміри для попередньої обробки	Збільште input_max_width / input_max_height, або зменште розмір зображення перед передачею в модель
misconfig.media_caps	Суміжні етапи GStreamer вимагають несумісних параметрів медіа	Узгодьте формат, роздільну здатність і частоту кадрів або вставте етап перетворення
misconfig.media_format	На етапі було використано непідтримуваний формат медіафайлу	Налаштуйте підтримуваний формат або додайте конвертацію формату
misconfig.tensor_dtype_missing	У контракті тензора відсутній тип даних/формат	Вкажіть підтримуваний тип даних тензора у вихідному контракті
misconfig.option_out_of_range	Обраний параметр для поточної стадії недійсний для тензора	Будь ласка, виберіть значення в діапазоні, який показує діагностичний інструмент.
build.parse_launch	Помилка gst_parse_launch не має більш конкретної класифікації.	Перегляньте доданий звіт, щоб отримати інформацію про контекст парсера.
build.pipeline_syntax	Синтаксис спеціального фрагмента GStreamer є недійсним.	Виправте та перевірте фрагмент за допомогою gst-launch-1.0.
build.plugin_missing	Необхідний елемент або кодек GStreamer не встановлено	Встановіть/замініть його та перевірте за допомогою gst-inspect-1.0.
build.property_invalid	Властивість елемента невідома або недійсна.	Перевірте назву та значення властивості за допомогою gst-inspect-1.0.
runtime.pull	Операція завантаження завершилася невдало, і не вдалося визначити конкретну причину.	Перегляньте доданий звіт і першу помилку, що виникла у вихідному коді.
runtime.element_failed	Один із етапів завершився невдало через відсутність більш детального відображення.	Виправте вказаний етап і відповідний вхідний параметр.
runtime.output_timeout	Не отримано жодного виводу до закінчення встановленого часу очікування	Перевірте потік даних або збільште очікуваний час очікування
runtime.unexpected_eos	Конвеєр завершив роботу до того, як було отримано необхідний результат.	Перевірте, чи не настав передчасний кінець вхідного потоку, і забезпечте достатню кількість вхідних даних.
io.parse	Помилка під час розбору JSON або схеми конфігурації етапу	Перевірте синтаксис конфігурації та наявність обов’язкових полів
io.open	Помилка при відкритті/читанні/записі файлу для збереження/завантаження графа	Перевірте існування шляху, права доступу та стан сховища
io.file_not_found	Вхідний файл не існує	Перевірте шлях до файлу та переконайтеся, що файл існує в DevKit
io.permission_denied	Файл або пристрій недоступний для читання	Перевірте права доступу/власника
io.rtsp_connection_failed	Не вдалося встановити з’єднання з джерелом RTSP.	Перевірте URL-адресу, доступність, сервер і облікові дані.
io.camera_not_found	Запитана камера недоступна	Виберіть доступну камеру або використовуйте камеру за замовчуванням
io.model_not_found	Запит на архів моделі неможливий, оскільки його не існує.	Перевірте шлях до моделі та переконайтеся, що вона встановлена.
io.source_ended	Джерело вхідних даних досягло свого звичайного кінця	Припиніть обробку або надайте більше вхідних даних
codec.invalid_h264_stream	Вхідний потік не містить дійсних H.264-кадрів	Надайте повний H.264-потік або виправте кодек
codec.decode_failed	Декодер не зміг обробити потік даних	Перевірте кодек і цілісність вхідних даних
codec.encode_failed	Кодек не зміг обробити надані кадри	Перевірте формат вхідних даних, роздільну здатність і налаштування кодека
resource.memory_allocation_failed	Виникла помилка під час виділення необхідного обсягу пам’яті.	Зменште обсяг пам’яті, що використовується під час виконання завдання, і звільніть пам’ять, яку використовують інші застосунки або конвеєри.
Не вдалося виділити пам’ять для пристрою DMA/CMA resource.device_memory_exhausted	Зменште кількість одночасних потоків, роздільну здатність або розмір буфера
resource.output_pool_exhausted	Усі буфери виводу залишаються в активному стані	Звільніть вихідні дані, що не потребують копіювання, або використовуйте копії, якими ви володієте
resource.buffer_too_small	Розмір буфера менший за заявлений розмір даних	Виправте розміри/крок або виділіть необхідну кількість байтів
resource.disk_full	Запис не вдався, оскільки сховище заповнене	Звільніть місце або оберіть інше місце призначення
infra.dispatcher_unavailable	Не вдалося отримати доступ до середовища виконання прискорювача.	Зупиніть інші процеси, що використовують ресурси, і перевірте DevKit на сумісність.
infra.accelerator_execution_failed	Не вдалося виконати етап моделі за допомогою прискорювача	Перезапустіть конвеєр і зменште кількість одночасних завдань для прискорювача
DispatcherUnavailable	Застаріле написання infra.dispatcher_unavailable	Перенесіть обробники до стандартного коду інфраструктури
internal.plugin_failure	Під час роботи плагіна виникла помилка, і не вдалося визначити причину, з якою користувач може взаємодіяти.	Збережіть звіт і зверніться до служби підтримки.

PullError.code використовує ту саму таксономію (а не лише шляхи обробки винятків). Див. Каталог кодів помилок., щоб отримати інформацію про константи C++ і Python, а також інструкції щодо міграції для застосунків, які відповідали попереднім грубим кодам.

У виробничих повідомленнях навмисно не вказуються внутрішні деталі GStreamer. Підвищення рівня деталізації налагодження плагіна додає необроблені домен/код GError, фабрику елементів, повідомлення та структуровані деталі плагіна. Розпізнані облікові дані та секретні параметри URL, зокрема URI userinfo, auth, playback-token, hdnts, stream-key і tkn, видаляються, перш ніж будь-яка з форм буде збережена. Рядки конвеєра, фрагменти Node, команди відтворення та серіалізований JSON, що використовуються для формування звітів, видаляються без зміни виконуваного конвеєра, який зберігається внутрішньо.

Програмна обробка.

#include "pipeline/ErrorCodes.h"
#include "pipeline/NeatError.h"

try {
  auto run = graph.build(input);
  simaai::neat::Sample out;
  simaai::neat::PullError perr;
  const auto st = run.pull(500, out, &perr);
  if (st == simaai::neat::PullStatus::Error) {
    if (perr.code == simaai::neat::error_codes::kMediaCaps) {
      // Fix the incompatible upstream/downstream media contract.
    } else {
      // Handle another specific code, including future codes, or report it.
    }
  }
} catch (const simaai::neat::NeatError& e) {
  if (e.report().error_code == simaai::neat::error_codes::kPluginMissing) {
    // Install or replace the missing GStreamer component.
  }
}

Налаштування для налагодження (середовище)

Основні змінні середовища (детальніше див. у розділі Архітектура):

• SIMA_GST_DOT_DIR: створюйте DOT-файли для візуалізації даних про помилки у вигляді графа.
• SIMA_GST_BOUNDARY_PROBES: лічильники граничного потоку.
• SIMA_GST_ELEMENT_TIMINGS: часові параметри для кожного елемента.
• SIMA_GST_FLOW_DEBUG: лічильники потоку для кожного елемента.
• SIMA_GST_ENFORCE_NAMES: забезпечує дотримання правил іменування.

Щоб додати відредагований необроблений контекст GStreamer до NeatError::what() та GraphReport.repro_note, встановіть значення обох змінних для команди, яка викликала помилку:

SIMA_NEAT_VERBOSE_LEVEL=2 \
SIMA_NEAT_VERBOSE_TOPICS=gstreamer \
./your-neat-application

NEAT_LOG_LEVEL=debug не є налаштуванням Neat Library. Під час звичайного використання слід вимикати детальне виведення інформації; воно призначене для коротких діагностичних тестів і може містити шляхи або адреси, специфічні для розгортання, навіть якщо ідентифіковані поля облікових даних замасковано.

Відлагодження робочого процесу.

1. Зафіксуйте GraphReport.error_code та спочатку згрупуйте помилки за таксономією.
2. Зафіксуйте GraphReport.repro_note для конкретного контексту та вбудованої підказки.
3. Текст конвеєра обробки: Graph::describe_backend() або last_pipeline().
4. Збирайте структуровані дані для діагностики: MeasureReport::to_text() або NeatError::report().
5. Перевірте GraphReport.bus на наявність першого терміналу, з якого виникла помилка ERROR, та отримайте детальну інформацію про неї.
6. Якщо в середовищі виконання виникають збої або перевищується час очікування, увімкніть зондування меж/елементів, щоб визначити місце зупинки потоку.

Рекомендований пакет підтримки:

• error_code
• repro_note
• повний pipeline_string
• перші 3–5 помилок, що виникли на кінцевих зупинках автобусів (GraphReport.bus)
• налаштування середовища, які використовуються під час виконання/перевірки.

Артефакт, що відображає показники продуктивності клієнтського графа.

Для звітування про пропускну здатність/затримку/споживання енергії, надавайте перевагу експорту даних у форматі JSON, отриманих під час виконання графа:

RunOptions opt;
opt.enable_board_power();        // graph-level power when supported by the board/SOM
Run run = graph.build(opt);

// run your normal push/pull loop inside a measurement window, then:
auto report = run.start_measurement().stop();
std::cout << report.to_text();

Експортований модуль зберігає чітке визначення областей видимості:

• run.graph_metrics.throughput_fps та run.graph_metrics.power – це заголовки на рівні графа.
• run.node_metrics[] містить лише дані про затримку вузла/плагіна; інформація про енергоспоживання вузла/плагіна навмисно відсутня.
• latency_semantics та aggregation показують, чи є значення змінами, обчисленими протягом усього часу роботи, чи змінами, виміряними протягом певного проміжку часу.
• plugin_metrics_unattributed[] зберігає рядки з таблиць kernel/plugin, які не вдалося однозначно зіставити з жодним вузлом.

Для вимірювання в певному проміжку часу використовуйте Run::start_measurement() і передайте отриманий MeasureReport до run_to_json(run, report, ...) / save_run_json(run, report, ...). Вузол, що вимірює в певному проміжку часу, має значення min_ms / max_ms, які позначено як недоступні, оскільки неможливо точно відняти кумулятивні лічильники мінімальних/максимальних значень без локальних лічильників для кожного проміжку часу.

Важлива примітка щодо живлення: поточна плата DVT може виконувати перевірку параметрів і структуру JSON, але її показники потужності не вважаються надійними з точки зору числових значень. SOM-апаратне забезпечення є цільовою платформою для перевірки показників потужності.

Найпоширеніші несправності → способи їх усунення

Симптом	Ймовірна причина	Рішення
missing ... plugin	GStreamer не знайдено	Перевірте GST_PLUGIN_PATH, запустіть gst-inspect-1.0 <plugin>.
appsink 'mysink' not found	Відсутній кінцевий Output()	Переконайтеся, що Output є останнім вузлом у конвеєрах виконання/збірки.
caps_override is set; renegotiation disabled	фіксовано великі літери	Видалити caps_override або залишити вхідні великі літери незмінними
tensor caps change not supported	Зміна форми/типу тензора під час виконання	Підтримуйте стабільну форму/тип тензора (без повторного узгодження)

Для отримання інформації про структуровані помилки плагінів і корисні підказки, зверніться до розділу Усунення несправностей., присвяченого усуненню несправностей.