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

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

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, отриманих під час виконання графа:

Run run = graph.build(RunOptions{});

TelemetryMonitor telemetry_monitor; // board power, temperatures, CPU usage, and memory
telemetry_monitor.start();
auto scope = run.start_measurement();
// run your normal push/pull loop here, then:
auto report = scope.stop();
Telemetry telemetry = telemetry_monitor.stop();
std::cout << report.to_text() << telemetry;

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

• run.graph_metrics.throughput_fps – це заголовок на рівні графа. run.graph_metrics.power заповнюється лише застарілим RunOptions::enable_board_power(); натомість використовуйте TelemetryMonitor.
• 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	Зміна форми/типу тензора під час виконання	Підтримуйте стабільну форму/тип тензора (без повторного узгодження)

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

Відновлення середовища виконання платформи

На Platform 3.0.0 недоступність диспетчера є помилкою, яку потрібно дослідити, а не запитом на запуск застарілих служб. Core не ініціалізує пам’ять MLA й не скидає віддалені процесори у відповідь на помилку диспетчера. Застарілий код і сценарій відновлення видалено; використовуйте процедуру відновлення, схвалену для платформи.

Якщо драйвер повідомляє про невідомий стан завершення, утримуйте його DMA-буфери та початкові позики з пулу. Закриття файлового дескриптора, зупинка застосунку або перезапуск служби не доводять, що апаратне забезпечення припинило доступ до пам’яті. Зберіть звіт про помилку й скористайтеся схваленою процедурою відновлення платформи перед повторною спробою.

Узгоджуйте пакети Core та Scheduler

Встановлюйте Core разом із набором пакетів Scheduler, вибраним для цього випуску Core. Scheduler керує відповідними залежностями Runner, Kernels, Codecs та прошивки. Однакова версія публічного C++ ABI сама по собі не гарантує сумісності середовища виконання.

Використовуйте опубліковані залежності, які вибирає build.sh, або передайте повний відповідний набір Scheduler DEB за допомогою --scheduler PATH. Див. Локальні залежності.

Для оновлення плати встановіть повний комплект Core за інструкцією Встановлення або оновлення Neat Library. Вибраний інсталятор Scheduler перевіряє набір пакетів і керує активацією прошивки. Якщо перевірка не проходить, отримайте відповідний комплект Core/Scheduler; не підміняйте записи встановлення й не встановлюйте примусово окремі несумісні пакети середовища виконання або прошивки.