ADT

Материал из ALT Linux Wiki


Stub.png
Данная страница находится в разработке.
Эта страница ещё не закончена. Информация, представленная здесь, может оказаться неполной или неверной.

ADT - ALT Diagnostic Tool - представляет собой инструмент для запуска тестов в терминале или в графическом интерфейсе.

Цель создания

Цель создания ADT — упрощение проведения диагностики и анализа работы системы. Работа ADT по поиску доступных тестов, их запуску и получению результатов работы теста осуществляется через D-Bus с использованием Alterator Manager и его модуля Executor. Благодаря подобной схеме реализации утилита диагностики системы получает доступ к интерфейсу взаимодействия на шине D-Bus. С использованием Alterator Manager и D-Bus возвращается информация о результатах выполнения теста.

Назначение

Программа ADT предназначена для:

  1. Cистемных администраторов.
  2. Опытных пользователей.
  3. Cлужбы технической поддержки.

Возможности программы позволяют проводить диагностику системы в графическом приложении и записать файл с отчетом. Запуск инструментов диагностики регулируется системным администратором, позволяя создавать отчеты пользователям, не передавая административные полномочия.

Установка

Команды установки ADT 

# apt-get update
# apt-get install adt
Примечание: Вместе с adt устанавливаются:
  • alterator-manager;
  • alterator-module-executor;
  • alterator-interface-diag.

Запуск

Запуск службы alterator-manager

# systemctl start alterator-manager.service
# systemctl enable alterator-manager.service

Запуск ADT

Вызов утилиты ADT возможен через графическое меню либо через терминал. Внешний вид программы без установленных инструментов диагностики

Диагностические инструменты добавляются установкой отдельных пакетов.

Интерфейс

Пользовательский интерфейс программы состоит из секций:

  • Список инструментов диагностики.
  • Описание инструмента.
  • Действия пользователя.

Спецификация

Компоненты

Руководство пользователя

Для работы с инструментом диагностики его необходимо выбрать в списке.

Список инструментов

Двойной щелчок мыши либо кнопка "Выбрать инструмент" перемещают пользователя к работе с набором тестов инструмента. Кнопка "Запустить все" автоматически запускает весь набор тестов выбранного инструмента.

Запуск всего набора тестов выбранного инструмента

В области управления инструментом диагностики доступны опции: "Отчет", "Запустить все тесты", "Назад". Напротив каждого теста находятся кнопки "Запустить" и "Журнал".

Пример выполнения всех тестов:

Пример выполнения всех тестов

Кнопка "Журнал" выводит отчет теста от утилиты инструмента диагностики (если инструмент поддерживает такую возможность):

Отчет

Кнопка "Отчет" сохраняет в файл полный текст информации инструмента диагностики (если инструмент поддерживает такую возможность).

Руководство администратора

Схема взаимодействия компонентов

Алгоритм работы ALT Diagnostic Tool

  1. Systemd служба alterator-manager во время запуска создает на шине D-Bus службу с именем "ru.basealt.alterator";
  2. Systemd служба alterator-module-executor собирает информацию из файлов .backend обо всех установленных диагностических инструментах и создает объекты на D-Bus;
  3. ADT формирует список диагностических инструментов, обращаясь к D-Bus службе "ru.basealt.alterator";
  4. Таким же способом ADT запускает тест и получает информацию о результате его выполнения.

Разработка инструмента диагностики

Формат файлов инструмента диагностики

Минимальный набор файлов для инструмента диагностики в ADT:

  • исполняемый файл
  • файл .backend
  • файл .diagnostic

.backend и .diagnostic описывают сущности Alterator Entry

Требования к исполняемому файлу

Может быть как бинарным, так и текстовым (написанным на интерпретируемом языке). Должен поддерживать запуск в следующем виде:

/путь_к_исполняемому_файлу {param}

{param} - означает имя теста, который необходимо выполнить. При успешном завершении теста исполняемый файл должен завершиться с кодом возврата 0. При не успешном завершении теста - с кодом возврата отличным от 0. Лог выполнения нужно выводить в стандартный вывод.

Также необходима поддержка следующих ключей:

  • -l или --list - вывести список тестов. Список необходимо выводить в стандартный вывод. Имя каждого теста с новой строки.
  • -r или --report - сгенерировать файл с отчетом. Файл с отчетом может представлять из себя как текстовые данные, так и бинарные (например архив). Его содержимое необходимо направить в стандартный вывод. ADT получит этот вывод и сохранит в файл с именем вида "имя_инструмента_дата" и суффиксом, указанным в файле .diagnostictool.

Рекомендации к файлам

  1. Исполняемый файл рекомендуется разместить в каталоге согласно стандарту FHS (Filesystem Hierarchy Standard)
  2. Для описания файлов .backend и .diagnostictool следует воспользоваться спецификацией Alterator Entry.

Имя директории соответствует суффиксу в имени файла:

  • ./backends для файла .backend
  • ./diagnostictools для файла .diagnostictool
.diagnostictool

Имеет имя вида <имя диагностического инструмента>.diagnostictool

Если разрабатываемый диагностический инструмент предполагается распространять, то файлы сущностей необходимо разместить в каталоге 

/usr/share/alterator/diagnostictool/

В противном случае, рекомендуется использовать каталог: 

/etc/alterator/diagnostictool/

Файл .diagnostictool хранит в себе информацию для GUI. Содержит секции [Alterator Entry] и секции, описывающие варианты тестирования:

Секция Alterator Entry

  • [Alterator Entry]
    • Name - идентификатор инструмента (имя без пробелов)
    • Type - всегда Diagnostictool
    • DisplayName - идентификатор
    • DisplayName[локаль] - имя инструмента, выводящиеся в GUI с использованием интерфейса с использованием указанной в скобках локали
    • Comment - описание инструмента
    • Comment[локаль] - описание, выводящиеся в GUI с использованием интерфейса с использованием указанной в скобках локали
    • Icon - имя файла с иконкой
    • ReportSuffix - суффикс файла с отчетом. Этот файл будет создаваться при вызове метода Report

Секции, описывающие варианты тестирования

  • [Название секции соответствует названию теста]
    • DisplayName - идентификатор
    • DisplayName[локаль] - имя теста, выводящиеся в GUI с использованием интерфейса с использованием указанной в скобках локали
    • Comment - описание теста
    • Comment[локаль] - описание теста, выводящиеся в GUI с использованием интерфейса с использованием указанной в скобках
.backend

Имеет имя вида <имя диагностического инструмента>.ru.basealt.alterator.backend

Если разрабатываемый диагностический инструмент предполагается распространять, то файлы сущностей необходимо разместить в каталоге 

/usr/share/alterator/backends/system  - если объект необходимо создать на системной шине
/usr/share/alterator/backends/user  - если объект необходимо создать на сессионной шине

В противном случае, рекомендуется использовать каталог: 

/etc/alterator/backends/system/  - если объект необходимо создать на системной шине
/etc/alterator/backends/user/  - если объект необходимо создать на сессионной шине


  • [Alterator Entry] - описывает информацию об объекте и содержит следующие поля:
    • Type - содержит тип метода. Всегда имеет значение Backend
    • Module - всегда executor
    • Name - идентификатор инструмента (имя без пробелов)
    • Interface - идентификатор интерфейса. Имеет значение ru.basealt.alterator.diag1. Можно сократить до diag1
    • thread_limit - Указывает максимальное число потоков при одновременном выполнении нескольких методов.
  • [Info] описывает метод Info и содержит следующие поля:
    • execute - в качестве параметра необходимо передать команду, выводящую содержимое файла .diagnostictool (cat <путь к файлу>)
    • stdout_bytes - всегда enabled?
    • thread_limit - всегда 3?
    • action_id - содержит идентификатор метода. Всегда имеет значение Info
  • [Run] описывает метод Run и содержит следующие поля:
    • execute - содержит строку для запуска тестов вида <путь к исполняемому файлу> {param}
    • stdout_signal_name - всегда diag1_stdout_signal. ADT ожидает сигнал с таким именем.
    • stderr_signal_name - всегда diag1_stderr_signal. ADT ожидает сигнал с таким именем.
    • action_id - содержит идентификатор метода. Всегда имеет значение Run
  • [List] описывает метод List и содержит следующие поля:
    • execute - содержит команду для вывода списка всех возможных тестов в виде <путь к исполняемому файлу> -l
    • stdout_strings - всегда enabled
    • action_id - содержит идентификатор метода. Всегда имеет значение List
  • [Report]
    • execute = содержит команду для создания отчета в виде <путь к исполняемому файлу> -R
    • stdout_bytes = enabled
    • action_id = Report

Пример инструмента диагностики

Ниже представлен пример диагностического инструмента для определения производителя материнской платы. Пример состоит из трех файлов:

  • исполняемый файл: /usr/bin/diag-example
  • файл .backend: /usr/share/alterator/backends/diag-example.backend
  • файл .diag, описывающий тесты: /usr/share/alterator/diag/diag-example.diag

Исполняемый файл

Example diagnostic tool
#!/bin/bash
#
# Copyright (c) 2024 Evgeny Sinelnikov <sin@altlinux.org>
#
# Example diagnostic tool
#
# SPDX-License-Identifier: GPL-2.0-or-later
#

set -euo pipefail

. shell-getopt

PROG="${0##*/}"
PROG_VERSION='0.0.1'

cmd="run"
global_retval=0

print_version()
{
	cat <<EOF
$PROG version $PROG_VERSION
Written by Evgeny Sinelnikov <sin@altlinux.org>

Copyright (C) 2024 Evgeny Sinelnikov <sin@altlinux.org>
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
EOF
	exit
}

show_usage()
{
	cat <<EOF
$PROG - example diagnostic tool.

Usage: $PROG [options] [<diagnostic-task>]

Options:
  -l, --list                list of diagnostic tasks;
  -V, --version             print program version and exit;
  -h, --help                show this text and exit.

Report bugs to https://bugzilla.altlinux.org/

EOF
	exit
}

TEMP=$(getopt -n "$PROG" -o "l,V,h" -l "list,version,help" -- "$@") || show_usage
eval set -- "$TEMP"

while :; do
	case "$1" in
		--) shift; break
			;;
		-l|--list) cmd="list";
			;;
		-V|--version) print_version
			;;
		-h|--help) show_usage
			;;
		*) fatal "Unrecognized option: $1"
			;;
	esac
	shift
done

task_list="$*"

task_show()
{
	local func="$1"

	echo "$func"
}

task_run()
{
	local retval=126
	local func="$1"

	if test -n "$task_list"; then
		echo "$task_list" | tr ' ' '\n' | grep -q "^$func\$" ||
			return 0
	fi

	$func && retval=0 || retval="$?"
	test $retval = 0 || global_retval=1

	return $retval
}

task()
{
	local task="$1"

	case "$cmd" in
		list) task_show "$task"
			;;
		run) task_run "$task" && echo "[DONE]: $task" || echo "[FAIL]: $task"
			;;
		*) fatal "Unrecognized command: $cmd"
			;;
	esac
}

is_gigabyte()
{
	/usr/sbin/dmidecode -s baseboard-manufacturer | grep -q "^Gigabyte Technology"
}

is_std_def_kernel_running()
{
	uname -r | grep -q '^[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]]\+-std-def-'
}

task is_gigabyte
task is_std_def_kernel_running

exit "$global_retval"

Файл .backend

[Alterator Entry]
Type = Backend
Module = executor
Name = diag_example
Interface = diag1

[Info]
execute = cat /usr/share/alterator/diag/diag-example.diag
stdout_bytes = enabled
stdout_byte_limit = 200000
action_id = Info

[Run]
execute = diag-example {param}
stdout_signal_name = diag_example_stdout_signal
stderr_signal_name = diag_example_stderr_signal
thread_limit = 1
action_id = Run

[List]
execute = diag-example -l
stdout_strings = enabled
stdout_strings_limit = 200000
action_id = List

Файл .diag, описывающий тесты

[Alterator Entry]
Type = diag
Name = Example
DisplayName = Diagnostic tool example
DisplayName[ru] = Пример инструмента диагностики
Comment = Diagnostic tool comment
Comment[ru] = Комментарий к диагностическому инструменту
Icon = system-run

[is_gigabyte]
DisplayName = Is motherboard manufacturer - Gigabyte?
DisplayName[ru] = Производитель материнской платы - Gigabyte?

Отображение диагностического инструмента в интерфейсе ADT

Пример отображения диагностического инструмента в интерфейсе ADT

Набор тестов инструмента

Шаблон примера

Ошибки и нестандартные случаи

Диагностический инструмент не отображается

Необходимо проверить объект alterator-manager с именем “ru.basealt.alterator” на системной шине D-Bus. Используйте утилиту D-Feet: 

# apt-get update
# apt-get install d-feet

В D-Feet можно посмотреть объекты заведенные как на системной шине, так и на сессионной шине для текущего пользователя:

D-Feet, системная шина

D-Feet, сессионная шина

Публикации на тему