kuma_metrics.sh — экспорт и импорт метрик KUMA

Скрипт выгружает метрики из встроенной в Kaspersky KUMA VictoriaMetrics через её HTTP API и (опционально) импортирует их в отдельную инсталляцию. Предназначен для замены ручного сбора метрик по скриншотам.

Что это за метрики

Внутри KUMA метрики хранит VictoriaMetrics. Доступ идёт по внутренним сертификатам KUMA, API живёт под префиксом /prometheus/. Группы метрик:

kuma_* — рабочие показатели KUMA (поток событий, EPS, потери, нагрузка и т.д.). Именно они обычно интересны поддержке. Фильтр по умолчанию — kuma_.+.
ClickHouseAsyncMetrics_*, km_*, vm_*, process_* — внутренняя телеметрия компонентов (ClickHouse, VictoriaMetrics, процессов). Берутся только при -match '.+'.

Требования

bash, curl, GNU date (стандартно для ОС, на которой работает KUMA).
Для сжатия: gzip и/или zstd (проверяются автоматически при использовании).
Доступ к файлам сертификатов KUMA (по умолчанию в каталоге core).

Конфигурация

В начале скрипта заданы значения по умолчанию — поправьте при необходимости:

BASE="https://localhost:7227/prometheus"
CORE_DIR="/opt/kaspersky/kuma/core/00000000-0000-0000-0000-000000000000/certificates"
CERT="${CORE_DIR}/internal.cert"
KEY="${CORE_DIR}/internal.key"
DEFAULT_MATCH='kuma_.+'

BASE указывает на localhost, поэтому скрипт нужно запускать на сервере с KUMA Core. Идентификатор 00000000-... у разных инсталляций отличается — проверьте реальный путь.

Установка

chmod +x kuma_metrics.sh

Использование

./kuma_metrics.sh [РЕЖИМ] [ВРЕМЯ] [ОПЦИИ]

Режим

Аргумент	Описание
`-export`	Экспорт метрик (режим по умолчанию).
`-import FILE`	Импорт JSON-файла. По умолчанию — в локальную инсталляцию.
`-list`	Вывести список всех доступных метрик в консоль и выйти.
`-groups`	Вариация `-list`: вывести только префиксы имён до первого `_`.
`-delete`	Удалить метрики по `-match` (по умолчанию `kuma_.+`). Деструктивно, требует подтверждения.
`-reset-cache`	Сбросить кэш результатов запросов (rollupResult cache) на `BASE`.

Выбор времени (только для экспорта)

Выберите один вариант. Если время не задано — берётся последний 1 час.

Аргумент	Описание
`-hour N`	За последние N часов.
`-days N`	За последние N дней.
`-range Д1 В1 Д2 В2`	За промежуток, время трактуется как UTC.

Пример -range: -range 2026-06-10 10:00:00 2026-06-10 11:00:00. Начало должно быть строго раньше конца — иначе скрипт остановится с ошибкой.

Опции экспорта

Аргумент	Описание
`-format csv\|json`	Формат выгрузки (по умолчанию `json`).
`-compress gzip\|zstd\|none`	Сжатие на лету. По умолчанию `gzip`. `zstd` — уровень `-19`; `none` — без сжатия.
`-match REGEX`	Regex по имени метрики (по умолчанию `kuma_.+`).
`-all`	Выгрузить все метрики (эквивалент `-match '.+'`).
`-out FILE`	Имя выходного файла (по умолчанию — с меткой времени).
`-progress`	Показывать индикатор прогресса curl (байты, скорость, время).

Опции импорта

Все необязательны: по умолчанию импорт идёт в локальную инсталляцию (те же BASE/CERT/KEY, что и при экспорте).

Аргумент	Описание
`-target URL`	Базовый URL цели (по умолчанию локальный `BASE`).
`-target-cert FILE`	Сертификат цели (по умолчанию локальный `CERT`).
`-target-key FILE`	Ключ цели (по умолчанию локальный `KEY`).
`-no-cache-reset`	Не сбрасывать кэш результатов после импорта (по умолчанию — сбрасывать).

Примеры фильтра `-match REGEX`

-match принимает regex по имени метрики (__name__). Регистр важен. Несколько имён объединяются через |. Значение всегда берите в одинарные кавычки.

Что нужно	`-match`
Все рабочие метрики KUMA (по умолчанию)	`'kuma_.+'`
Вообще все метрики (KUMA + ClickHouse + VM)	`'.+'`
Одна конкретная метрика	`'kuma_licenseEPS'`
Несколько конкретных метрик	`'kuma_eventSource\|kuma_out\|kuma_processing'`
Все метрики потока событий (общая основа)	`'kuma_event.+'`
Метрики хранилища/ClickHouse в KUMA	`'kuma_storage.+'`
Телеметрия ClickHouse целиком	`'ClickHouseAsyncMetrics_.+'`
Только диски ClickHouse	`'ClickHouseAsyncMetrics_Disk.+'`
Внутренние метрики VictoriaMetrics	`'km_.+'`
Ресурсы процессов (CPU/память/FD)	`'process_.+'`
KUMA + процессы, но без ClickHouse и VM	`'kuma_.+\|process_.+'`

Команды целиком:

# одна метрика — лицензионный EPS за последний час
./kuma_metrics.sh -export -hour 1 -match 'kuma_licenseEPS' -format json

# набор метрик по событиям за 3 часа, json + zstd
./kuma_metrics.sh -export -hour 3 \
    -match 'kuma_eventSource|kuma_out|kuma_processing|kuma_eventLoss' \
    -format json -compress zstd

# всё про хранилище за сутки
./kuma_metrics.sh -export -days 1 -match 'kuma_storage.+' -format csv -compress gzip

# диагностический полный срез (всё) за интервал — обязательно со сжатием
./kuma_metrics.sh -export -range 2026-06-10 10:00:00 2026-06-10 11:00:00 \
    -match '.+' -format json -compress zstd

Подобрать точные имена под свой фильтр удобно по списку всех метрик:

curl -G "https://localhost:7227/prometheus/api/v1/label/__name__/values" \
  --cert "$CERT" --key "$KEY" -k

csv или json — что выбрать

csv — компактно, удобно открыть в Excel/таблицах для анализа. Колонки: имя метрики, значение, timestamp (unix-секунды). Лейблы не сохраняются.
json — формат JSON line, по серии на строку, с полным набором лейблов (например, по какому коллектору/сервису метрика). Только этот формат пригоден для последующего импорта.

Правило простое: для анализа значений — csv; если важен контекст (лейблы) или планируется загрузка в другую систему — json.

Примеры

# Список всех доступных метрик (вывод в консоль)
./kuma_metrics.sh -list

# Список только метрик KUMA
./kuma_metrics.sh -list -match 'kuma_.+'

# Только префиксы имён — группы метрик (kuma, process, ClickHouseAsyncMetrics, …)
./kuma_metrics.sh -groups

# Выгрузить ВСЕ метрики за сутки
./kuma_metrics.sh -export -all -days 1

# Удалить метрики KUMA (по умолчанию kuma_.+) — спросит подтверждение
./kuma_metrics.sh -delete

# Удалить ВСЕ метрики
./kuma_metrics.sh -delete -all

# С индикатором прогресса (байты, скорость, время)
./kuma_metrics.sh -export -days 7 -match '.+' -format json -progress

# Последние 3 часа, kuma_*, csv со сжатием zstd
./kuma_metrics.sh -export -hour 3 -format csv -compress zstd

# Последние 7 дней, ВСЕ метрики, json + gzip
./kuma_metrics.sh -export -days 7 -match '.+' -format json -compress gzip

# Конкретный интервал (UTC), только две метрики
./kuma_metrics.sh -export -range 2026-06-10 10:00:00 2026-06-10 11:00:00 \
    -match 'kuma_eventSource|kuma_out' -format json -compress zstd

# Импорт в другую инсталляцию
./kuma_metrics.sh -import kuma_metrics_20260610_110000.json.zst \
    -target https://other-host:7227/prometheus \
    -target-cert /opt/kaspersky/kuma/core/<UUID>/certificates/internal.cert \
    -target-key  /opt/kaspersky/kuma/core/<UUID>/certificates/internal.key

Проверки перед запуском

Скрипт сам, до начала работы:

Проверяет наличие curl и date.
При запросе сжатия — проверяет наличие gzip/zstd.
Проверяет, что файлы сертификата и ключа существуют и читаемы.
Делает тестовый запрос к …/api/v1/labels и убеждается в ответе HTTP 200 (для экспорта — к источнику, для импорта — к цели).

При любой неуспешной проверке выполнение останавливается с понятным сообщением, частично записанный файл удаляется.

Импорт: важные детали

Импортируется только JSON (в т.ч. .json.gz / .json.zst). CSV обратно не загружается: в нём имя метрики лежит колонкой __name__, которая не восстанавливается стандартным CSV-импортом. Поэтому для переноса всегда экспортируйте с -format json.
Данные уходят в …/api/v1/import целевой инсталляции. После загрузки они могут появиться с небольшой задержкой (флаш внутреннего буфера).
Большие файлы передаются потоково (curl -T -, chunked), без загрузки всего тела в память.
После успешного импорта скрипт автоматически сбрасывает кэш результатов запросов (/internal/resetRollupResultCache), чтобы импортированные исторические данные сразу были видны в Grafana, а не появлялись по мере устаревания кэша. Отключается флагом -no-cache-reset. Сброс некритичен: если эндпоинт недоступен, скрипт лишь предупредит — данные всё равно записаны. При ручном импорте кэш можно сбросить отдельно режимом -reset-cache.
По умолчанию цель — локальная инсталляция (тот же BASE/CERT/KEY). Для переноса в другой экземпляр укажите -target (и при необходимости -target-cert/-target-key). По возможности импортируйте в отдельный тестовый/аналитический экземпляр, а не в боевую KUMA, чтобы не смешивать перенесённые метрики с её собственными.

Удаление: важные детали

Режим -delete необратим. Перед удалением скрипт показывает цель и фильтр и требует ввести слово DELETE. Любой другой ввод отменяет операцию.
Удаляются серии, чьё имя подходит под -match (по умолчанию kuma_.+). Для полного удаления используйте -delete -all.
Удаление идёт на адрес из BASE (тот же, что у -list/-export) через admin-эндпоинт …/api/v1/admin/tsdb/delete_series. Чтобы удалять в другой инсталляции, запускайте скрипт на ней или поправьте BASE в шапке.
Место на диске освобождается не мгновенно, а при фоновом слиянии данных.
Если KUMA продолжает собирать метрики, удалённые серии вскоре появятся снова (уже с новыми значениями) — удаление стирает историю, но не останавливает сбор.
Флаг -yes пропускает подтверждение (для автоматизации) — применяйте осознанно.
Если admin-эндпоинт удаления в инсталляции отключён, скрипт сообщит об ошибке HTTP вместо удаления.

Замечания и ограничения

Прогресс. По умолчанию выгрузка идёт тихо (удобно для cron). Флаг -progress включает индикатор curl. Поскольку API отдаёт поток без заранее известного размера (chunked), процентов не будет — показываются принятые байты, скорость и время. Индикатор пишется в stderr и не попадает в выходной файл.
Время — в UTC. И -range, и метки времени в выводе. При сопоставлении с локальным временем учитывайте смещение часового пояса.
Глубина истории ограничена настройками retention самой KUMA — за очень старый период данных может уже не быть.
Объём. Часовой срез kuma_* — это десятки/сотни МБ; со сжатием zstd -19 файл уменьшается в разы. Для -match '.+' за дни объём вырастает значительно — обязательно используйте сжатие.
Путь эндпоинта. Экспортные/импортные эндпоинты — это специфика VictoriaMetrics. Если на вашей версии они не отвечают под /prometheus/, попробуйте BASE без этого префикса.
Сертификаты. UUID в пути сертификатов индивидуален для каждой инсталляции — при ошибке «файл не найден» сверьте реальный путь в каталоге core.

Диагностика

Симптом	Что проверить
`эндпоинт недоступен (HTTP ...)`	URL/порт, запущен ли сервис, верны ли сертификаты.
`не найден файл (сертификат ...)`	Реальный UUID и путь в каталоге core.
Пустой/битый файл при экспорте	Слишком широкий `-match` + нет сжатия; есть ли данные за период.
`не найдена утилита 'zstd'`	Установить `zstd` или использовать `-compress gzip`.
`--data-binary: out of memory` при импорте	Обновлённый скрипт шлёт поток через `-T -`; при ручном импорте не используйте `--data-binary @-` на больших файлах.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
README.md		README.md
kuma_metrics.sh		kuma_metrics.sh

Navigation Menu

Repository files navigation

kuma_metrics.sh — экспорт и импорт метрик KUMA

Что это за метрики

Требования

Конфигурация

Установка

Использование

Режим

Выбор времени (только для экспорта)

Опции экспорта

Опции импорта

Примеры фильтра `-match REGEX`

csv или json — что выбрать

Примеры

Проверки перед запуском

Импорт: важные детали

Удаление: важные детали

Замечания и ограничения

Диагностика

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

kuma_metrics.sh — экспорт и импорт метрик KUMA

Что это за метрики

Требования

Конфигурация

Установка

Использование

Режим

Выбор времени (только для экспорта)

Опции экспорта

Опции импорта

Примеры фильтра -match REGEX

csv или json — что выбрать

Примеры

Проверки перед запуском

Импорт: важные детали

Удаление: важные детали

Замечания и ограничения

Диагностика

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Примеры фильтра `-match REGEX`