P
perfscale

Начало работы

Интеграция с CI/CD

Нагрузочное тестирование из пайплайна — GitHub Action, REST API и вебхуки обратно в CI

Обзор

perfscale встраивается в пайплайн четырьмя способами, и они комбинируются:

  • GitHub Action — запускает нагрузочный тест шагом workflow и гейтит сборку по метрикам, всё на раннере GitHub.
  • Шаблоны GitLab CI — та же пара «прогон + гейт» для пайплайнов GitLab, в одном include: от вашего .gitlab-ci.yml.
  • REST API — запуск задачи на машинах вашего рабочего пространства из любой CI-системы с опросом результата.
  • Вебхуки — события о завершении прогона, отправленные обратно в ваш CI, чат или статус-страницу.

GitHub Action

Perfscale/github-action устанавливает закреплённый релизный бинарник perfscale на раннер (Linux, macOS, Windows; x64 и arm64), проверяет его sha256, запускает ваш тест и упаковывает сводку вместе со сгенерированными файлами метрик в zip. Укажите ровно один engine-input — k6, locust или file:

name: load-test
on:
  push:
    branches: [main]

jobs:
  perfscale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: Perfscale/github-action@v1
        id: loadtest
        with:
          file: examples/hello.test.yaml      # нативный step-движок
          config: examples/hello.config.yaml  # обязателен с `file`

      - name: Gate on p95
        run: |
          p95=$(jq '.summary.p95_ms' "${{ steps.loadtest.outputs.summary-json }}")
          echo "p95 = ${p95} ms"
          awk "BEGIN { exit !(${p95} < 500) }" || { echo '::error::p95 over budget'; exit 1; }

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: perfscale-metrics
          path: ${{ steps.loadtest.outputs.output-file }}

Ключевые входы (все опциональны, если не сказано иное):

ВходПо умолчаниюОписание
versionlatestРелиз perfscale для установки (тег вида v0.2.0)
k6 / locust / file—Скрипт для запуска — ровно один; file — нативный движок, требует config
config—Путь к config.yaml (vus, duration); опционально для locust
host—Базовый URL цели для движка locust
summary-exportperfscale-summary.jsonМашиночитаемая JSON-сводка; пустое значение отключает
job-summarytrueОтрисовать таблицу метрик в job summary GitHub Actions
outputperfscale-output.zipZip-артефакт со сводкой и файлами метрик
args—Дополнительные сырые аргументы, добавляемые к perfscale run как есть

Выходы: summary-json (для гейтов вроде приведённого выше), summary-file, output-file и exit-code. Коды выхода повторяют CLI: 0 — прогон завершился (даже если запросы или проверки падали), 1 — прогон не смог выполниться, 2 — неверные аргументы, — поэтому зелёный шаг не означает выполненный SLA; гейтить нужно по summary-json, как показано выше.

На раннерах GitHub Enterprise Server action работает, если у раннера есть доступ к github.com, — бинарь perfscale скачивается с публичных релизов. Отдельного GHES-зеркала нет.

GitLab CI

Для пайплайнов GitLab есть готовые CI-шаблоны в репозитории Perfscale/gitlab-ci: скрытая джоба .perfscale:run (скачивает закреплённый, проверенный по sha256 бинарь perfscale, запускает ваш тест и сохраняет JSON-сводку как артефакт) и джоба .perfscale:gate, которая валит пайплайн, когда метрика превышает бюджет. Подключите их и расширьте:

include:
  - remote: https://raw.githubusercontent.com/Perfscale/gitlab-ci/main/templates/perfscale.gitlab-ci.yml
  - remote: https://raw.githubusercontent.com/Perfscale/gitlab-ci/main/templates/gate.gitlab-ci.yml

load-test:
  extends: .perfscale:run
  variables:
    PERFSCALE_FILE: examples/hello.test.yaml     # нативный step-движок
    PERFSCALE_CONFIG: examples/hello.config.yaml # обязателен с FILE

p95-gate:
  extends: .perfscale:gate
  needs: [load-test]   # скачивает артефакт сводки run-джобы
  variables:
    PERFSCALE_GATE_METRIC: ".summary.p95_ms"
    PERFSCALE_GATE_MAX: "500"

Укажите ровно одну engine-переменную — PERFSCALE_K6, PERFSCALE_LOCUST или PERFSCALE_FILE. Ключевые переменные (все опциональны, если не сказано иное):

ПеременнаяПо умолчаниюОписание
PERFSCALE_VERSIONlatestРелиз perfscale для установки; для air-gapped закрепите тег
PERFSCALE_K6 / PERFSCALE_LOCUST / PERFSCALE_FILE—Скрипт для запуска — ровно один; FILE — нативный движок
PERFSCALE_CONFIG—Путь к config.yaml; обязателен с FILE, опционален для locust
PERFSCALE_SUMMARYperfscale-summary.jsonМашиночитаемая JSON-сводка, сохраняется артефактом джобы
PERFSCALE_ARCHamd64Архитектура бинаря: amd64 или arm64
PERFSCALE_DOWNLOAD_BASEрелизы github.comБазовый URL дерева релизов — укажите своё зеркало для air-gapped раннеров
PERFSCALE_GATE_METRIC.summary.p95_msjq-путь метрики, которую проверяет гейт
PERFSCALE_GATE_MAX500Бюджет: гейт-джоба падает выше этого значения

Коды выхода повторяют CLI: 0 — прогон завершился (даже если запросы или проверки падали), 1 — прогон не смог выполниться, 2 — невалидные переменные. Зелёная джоба не означает выполненный SLA — для этого и нужна гейт-джоба, и ей необходим needs: на run-джобу, чтобы видеть её артефакт сводки.

Self-managed GitLab

Шаблоны работают на любом инстансе GitLab с docker-executor'ом на Linux-раннерах, но две вещи по умолчанию указывают на github.com:

  • Подключение шаблона. include: remote заставляет инстанс забирать файл с raw.githubusercontent.com. Если инстанс туда не достаёт, скопируйте templates/*.gitlab-ci.yml в свой репозиторий и используйте include: local, либо зеркалируйте Perfscale/gitlab-ci в свой инстанс и используйте include: project.
  • Скачивание бинаря. В air-gapped сети зеркалируйте релизные ассеты на хост, доступный вашим раннерам, — сохраняя layout download/<tag>/<asset> и sha256sums.txt — укажите его в PERFSCALE_DOWNLOAD_BASE и закрепите PERFSCALE_VERSION: редирект latest существует только на github.com.

REST API

Любая CI-система может управлять платформой напрямую. Создайте персональный API-токен в дашборде в Settings → API Tokens — открытый psk_... показывается один раз; сохраните его в секрет-хранилище вашей CI. Лимиты токенов зависят от тарифа, а на Starter API-доступ не входит.

# 1. Запуск задачи — возвращает 202 Accepted с ID задачи
curl -X POST https://perfscale.su/api/v1/tasks \
  -H "Authorization: Bearer $PERFSCALE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"testId": "your-test-id"}'

# 2. Опрос, пока задача не выйдет из pending/running
curl https://perfscale.su/api/v1/tasks/task_02 \
  -H "Authorization: Bearer $PERFSCALE_TOKEN"

В итоге объект задачи содержит status (passed, failed, …) и сводные метрики — p50, p95, p99, error_rate, requests_per_sec, total_requests — всё, что нужно гейту на jq. Если ваше рабочее пространство живёт на perfscale.ru, используйте https://perfscale.ru как базовый URL. Полный справочник endpoint'ов — Справочник API.

Вебхуки обратно в CI

Когда прогон запущен расписанием или чужим пайплайном, событие о завершении всё равно нужно в вашей системе. Подпишите вебхук на test.completed / test.failed и направьте его на incoming-webhook вашего CI или чата:

  • Доставки подписаны (X-Perfscale-Signature, HMAC-SHA256) — проверяйте подпись до того, как доверять payload.
  • Ошибки ретраятся с backoff (1 мин, 5 мин, 30 мин, 2 ч) и попадают в историю доставок вебхука, так что красную доставку можно отладить.
  • Payload несёт task_id, status, duration_ms и log_url — достаточно, чтобы отправить в Slack «ночная регрессия прошла, p95 310 мс» или завалить ожидающий джоб пайплайна.

Дальше