Help:CLI: Difference between revisions
m (minor fixes) |
m (Added auth env vars) |
||
| Line 1: | Line 1: | ||
[[Category:Help]] | [[index.php?title=Category:Help]] | ||
== CLI features == | == CLI features == | ||
| Line 230: | Line 230: | ||
* Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов. | * Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов. | ||
=== Аутентификация из переменных окружения === | |||
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI | |||
SVACER_AUTH_CREDS=login:password | |||
SVACER_AUTH_TOKEN=token | |||
В качестве токена должен использовать токен, получаемый через REST endpoint <code>/api/public/login</code> | |||
=== Аутентификация из файла === | === Аутентификация из файла === | ||
Revision as of 14:11, 4 June 2024
CLI features
Перенос снимков
Svacer предоставляет возможность по экспорту и импорту снимков посредством интерфейса командной строки и веб-интерфейса. Экспорт снимка включает все предупреждения, информацию о снимке, прикрепленные файлы, объект сборки, пользовательские атрибуты, разметку и комментарии. Подавленные предупреждения также включаются в экспортированную информацию и импортируются в статусе подавленных.
Экспорт и импорт снимков из командной строки доступен пользователям с соответствующими правами для выбранного проекта/ветки.
Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>
Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>
Опция --force создаст проект и ветку, если их не было на сервере.
Создание PDF отчета
Для создания PDF отчета по проекту из интерфейса командной строки используется команда pdfgen.
Общий вид команды следующий:
svacer pdfgen --cmpMode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--targetProject [name|id] --targetBranch [name|id] --targetSnapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --outFile report_name --tz time_zone --lang report_lang
- cmpMode — параметры сравнения. Возможные значения: none — без сравнения, new — новые, missing — отсутствующие, matched — сопоставленные, same — одинаковые
- Project, Branch, Snapshot — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
- targetProject, targetBranch, targetSnapshot — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
- File, checker, severity, review — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т. д.)
- outFile — имя создаваемого файла отчета. Если не указано расширение, будет добавлено расширение pdf
- tz — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
- lang — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)
Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).
Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: targetProject, targetBranch, targetSnapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project -> targetProject, branch -> targetBranch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.
Для создания отчета можно использовать public API:
- URL — /api/public/exportPDF
- Метод — POST
Тело запроса — JSON, имеет следующий вид:
{
"compare_mode": "new",
"context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_131"
},
"target_context":{
"project": "zstd",
"branch": "v13",
"snapshot": "zstd_132"
},
"language": "en",
"timezone": 180,
"filters": {
"checker": "^Z.*$",
"file": ".*example.*",
"severity": "Cr.*",
"review": "Conf.*"
}
}
Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).
Импорт разметки из исходного кода
Импорт разметки из исходного кода на сервер истории возможен с помощью команды svacer markup import.
Синтаксис:
svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--excludePaths <path1, path2, ..., pathN> --from-build-object]
Где:
- user, password — пользователь и пароль учетной записи на сервере
- project — проект на сервере, в который будет произведен импорт разметки
- branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
- snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
- excludePaths — исключает файлы, соответствующие регулярным выражениям
- template — определяет имя шаблона для импорта разметки (флаг обязательный, в отличие от экспорта)
- from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.
После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект, ветку и снимок.
Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде
//svacer_review: -<warn class>[|-<warn class>]+
Пример:
if (!strncmp("--filelimit",argv[i],11)) {
j = 11; //svacer_review: -UNUSED_VALUE
if (*(argv[i]+11) == '=') {
Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.
Для импорта разметки при использовании команд import --upload и upload следует указывать флаг --template <template>. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.
Шаблон разметки DEFAULT
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в Settings > Markup templates (при наличии прав доступа).
Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через выгрузку кода с указанием шаблона.
В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарии к ней.
Пример:
//svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
//svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
printf("v = %d", fl3(), i);
Разметка нескольких одинаковых предупреждений на одной строчке проблематична, гарантируется только что разметка будет применена к маркеру с таким названием.
Изменение инвариантов (--pathPrefix)
Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг --pathPrefix, то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду svacer markup update.
Синтаксис:
svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --pathPrefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]
Где:
- user, password — пользователь и пароль учетной записи на сервере
- project — проект на сервере, в котором будет обновлена разметка
- branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
- pathPrefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement
В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в Settings > Server information).
Подавление предупреждений
Для подавление выбранных пользователем предупреждений предоставляется следующий интерфейс командной строки:
Список подавленных предупреждений (печатает JSON)
svacer markup [auth/selection] suppress list
Пример
svacer markup --user admin --password admin --project tree-command suppress list
Подавить предупреждение
svacer markup [auth/selection] suppress add id1 id2 id3
Пример
svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af
Убрать подавление предупреждения
svacer markup [auth/selection] suppress remove id1 id2 id3
Пример
svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af
Убрать все подавления
svacer markup [auth/selection] suppress remove
Пример
svacer markup --user admin --password admin --project tree-command suppress remove
Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline. На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.
При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.
Автомиграция разметки
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (у пользователя должны быть права на администрирование сервера).
svacer server automigrate [command] [flags]
Существующие command:
- add — добавляет автомиграцию в соответствии с паттерном
- delete — удаляет автомиграцию
- show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
- show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
- log — выводит список всех совершенных миграций (Done Automigrate Table)
Флаг pattern, применяется для команд <add|delete|show_config|log>
- Для add: Паттерн автомиграции в формате:
srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}
- regEx — в формате как для PostgreSQL
- Для delete: Паттерн автомиграции в формате:
srcProject{id|name}/srcBranch{id|name}=>receiveProject{id|name|regEx}/receiveBranch{id|name|regEx}
- Паттерн должен быть точно таким же, как он записан в Config Table
- Для show_config: Паттерн автомиграции. Поиск будет происходить в следующем виде:
ILIKE "'%"+pattern+"%'"
- Для log: Флаг в формате
srcProjectId/srcBranchId=>receiveProjectId/receiveBranchIdилиsrcProjectName/srcBranchName=>receiveProjectName/receiveBranchNameдля вывода автомиграций с данным паттерном
Флаг id, применяется для command <delete|show_automigrate> в формате uuid
- Для delete: id для удаления автомиграции (из Config Table)
- Для show_automigrate: id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id
Флаг format — формат вывода таблицы. Применяется для command <show_config|show_automigrate|log>
- Для show_config:
- table — вывод в виде таблицы
- json — вывод в виде json
- no-id — вывод без config id
- Значения можно перечислить через запятую:
json,no-id. По умолчанию — table.
- Для show_automigrate|log:
- table — вывод в виде таблицы
- json — вывод в виде json
- По умолчанию — table.
Также возможно использовать POST запрос по адресу /api/automigrate. В теле передается json, с полями action(not null), pattern, id. Выполняется по тому же принципу, что и в CLI.
Принцип работы сервиса:
- При запуске сервера запускается сервис automigrate
- При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
- При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
- Не может копировать разметку с нескольких веток на одну (будет выдавать ошибку)
- При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.
- Единственный случай, когда сервис не даёт выполнить действие — загрузка результатов Svace через CLI: upload, либо import с флагом --upload. В этом случае сервис выдает ошибку миграции и отменяет загрузку. Такое может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов.
Аутентификация из переменных окружения
Пользователь может использовать следующие переменные окружения для выполнения аутентификации при использовании CLI
SVACER_AUTH_CREDS=login:password SVACER_AUTH_TOKEN=token
В качестве токена должен использовать токен, получаемый через REST endpoint /api/public/login
Аутентификация из файла
Для упрощения работы с клиентом svacer возможно сохранять некоторые параметры соединения и токен аутентификации для дальнейшего использования. Сохранение данных производится с помощью команды:
svacer server login --host [hostname] --port [restPort] --grpc [grpcPort] --ssl-ca-certs [certs_path] --user [username] --password [password] --out [file]
Команда выполняет подключение к серверу svacer по указанным параметрам (host, port, user, password), получает токен аутентификации и сохраняет все эти данные в файл. Для указания файла, в котором следует сохранять данные, используется опция --out . Если опция --out опущена, то данные будут записаны в файл svacer_conn.json в текущей папке. Пример использования команды приведен ниже:
svacer server login --host svacer.local --port 8080 --grpc 3002 --user admin --password --out cn.json
В данном примере клиент произведет попытку аутентификации на сервере svacer.local и полученный токен вместе с параметрами (host, port, grpc) будет записан в файл cn.json.
Для использования созданного ранее файла с данными необходимо использовать опцию --conn_file. Данная опция определена во всех командах, в которых определены параметры --user --password (то есть параметры аутентификации). Например, для выполнения импорта данных на сервер с использованием сохраненной информации можно использовать следующую команду:
svacer import --conn_file cn.json .
В примере выше клиент считает токен из файла cn.json и выполнит загрузку данных по указанным в файле параметрам host, port, grpc.
Также имя файла с данными подключения можно передавать через переменную окружения SVACER_CONN_FILE.
Вывод списка предупреждений
Пользователь может получить таблицу предупреждений с сервера, используя команду
svacer marker list --host host --user user --password password --project project_name_or_id --branch branch_name_or_id --snapshot snapshot_name_or_id
Вывод:
# warn file line review msg
1000 INVARIANT_RESULT /.build/subst.c 7080 Expression 'tl->word->flags | (1 << 21)' is always
true , which may be caused by a logical error
1001 DEREF_AFTER_NULL.LOOP /.build/execute_cmd.c 3327 After having been compared to NULL value at execut
e_cmd.c:3325, pointer 'l' is dereferenced at execu
te_cmd.c:3327.
1002 DEREF_AFTER_NULL.LOOP /.build/variables.c 2749 After having been compared to NULL value at variab
les.c:2656, pointer 'vc' is dereferenced at variab
les.c:2749.
1003 CHECK_AFTER_PASS_TO_PROC /.build/redir.c 1219 Variable 'redirector' was passed to function at re
dir.c:1215 by calling function 'fcntl' that can't
use negative values is checked for negative value
at redir.c:1219.
При указании флага --out-format=json вывод будет произведен в JSON формате:
[{"id":"e0ec7389-42a0-403c-9ce2-bfaa3bfa0228","file":"/.build/subst.c","function":"WORD_DESC * parameter_brace_expand_rhs()","line":7080,"locID":1000,"lang":"CXX","tool":"CSA","warnClass":"INVARIANT_RESULT","mtid":"CSA.INVARIANT_RESULT.1","msg":"Expression 'tl-\u003eword-\u003eflags | (1 \u003c\u003c 21)' is always true , which may be caused by a logical error","details":"811ed8f680ae9b540707436615348aed6d32ee93","flags":0,"invariant":"TBXA/IYVZKVlH6f19tiGsd3stuI"},{"id":"184b85bf-a63f-4187-b290-25a5950b3353","file":"/.build/execute_cmd.c","function":"select_query","line":3327,"locID":1001,"
Svacer server features
Поддержка сквозной аутентификации
Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.
При включенном proxy-mode используется header с прокси Authorization Basic ..., откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем есть в БД пользователей Svacer.
Пример запуска сервера с поддержкой сквозной аутентификации:
svacer-server run --proxy-mode
Хуки
Для использования хуков при запуске сервера нужно указать опцию --hooks <path to JSON file>. Эта опция задаёт файл, содержащий описание хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует процессу или скрипту, который сервер запускает при вызове соответствующей команды из web-интерфейса.
Формат файла описания хуков следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>", ...],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, ...]
},
...
]
}
Параметры хуков
| id | Идентификатор хука. Должен быть уникальным в файле |
| label | Имя команды, которую пользователь видит в web-интерфейсе |
| target | Место в UI, в которое будет добавлена команда. Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса |
| input | Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. Поддерживаемые значения:
|
| cmd | Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска |
| args | Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input> |
Типичный сценарий использования хуков — создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira или Gitlab. Примеры скриптов для этого можно найти на странице Примеры использования хуков.