# Снятие дампов памяти

Для анализа ошибок в работе Global ERP разработчики могут запросить дамп кучи (heap) сервера приложений, шедулера,
компонента gossiprouter или обходчика очередей. Снять его в gs-ctk можно при помощи встроенной утилиты `./make_dump.sh`.

## Требования к системному NFS-хранилищу

Дампы памяти автоматически выгружаются на системное NFS-хранилище, где также находятся `appkit` и `groupkit`.
Его минимальный объём должен составлять **5–6 размеров максимального `-Xmx`, но не менее 120 ГБ**. Для планирования
используйте коэффициент 6 и наибольший `-Xmx` среди Java-процессов, сохраняющих дампы на это хранилище.

Учитывайте также место под комплекты и накопление дампов от нескольких подов до автоматической очистки. Подробный
расчёт приведён в [требованиях к системному NFS-хранилищу](020_min_requirements.md#системное-nfs-хранилище-кластера).

## Автоматическое снятие дампов

Помимо ручного запуска, дамп кучи снимается автоматически при возникновении критических ситуаций, свидетельствующих о
проблемах в работе сервера приложений. Это позволяет зафиксировать состояние памяти в момент сбоя для последующего
анализа.

Автоматическое снятие дампа происходит в следующих случаях:

1. **Сборщик мусора (GC) в Java работает без перерыва более 30 секунд.**

   Это может указывать на чрезмерную нагрузку на память или утечки, из-за которых JVM не может завершить сборку мусора.
   Такое состояние часто приводит к «застыванию» приложения.

2. **Работа GC занимает более 99% всего времени выполнения JVM.**

   При такой ситуации приложение практически остановлено из-за постоянных сборок мусора, что серьёзно снижает
   производительность и отзывчивость сервиса. Постоянная работа GC может сопровождаться возникновением
   `OutOfMemoryError` в прикладном коде. Само исключение `OutOfMemoryError` не является триггером снятия дампа, дамп
   снимается при достижении пороговых значений работы GC.

3. **Сервер перестаёт корректно отвечать на запросы на [сервис `/app/sys/monitor/public/isAlive`](https://help.globalerp.ru/books/gs-docs-sphinx/master/spec/services/http/rest/monitor/index.html#id3).**

   Это сигнализирует о том, что приложение не отвечает на внешние проверки доступности, что может быть вызвано
   зависанием, нехваткой ресурсов, внутренней ошибкой или незапланированным
   переходом [в другой режим работы сервера](https://help.globalerp.ru/books/gs-docs-sphinx/master/spec/server/server_modes.html).

```{important}
Автоматическое снятие дампа не выполняется при завершении контейнера Kubernetes по причине превышения установленного лимита памяти (`OOMKilled`). В этом случае процесс завершается ядром операционной системы непосредственно при возникновении нехватки памяти. Предварительно выполнить команду снятия heap dump невозможно, поэтому состояние памяти JVM непосредственно перед завершением контейнера сохранить нельзя.

Событие `OutOfMemoryError` внутри JVM также само по себе не является триггером автоматического снятия дампа. Если нехватка памяти приводит к длительной или практически непрерывной работе GC, дамп может быть снят по одному из описанных выше GC-триггеров до завершения процесса.

При расследовании `OOMKilled` следует использовать логи приложения, события Kubernetes и метрики использования памяти за период перед перезапуском пода.
```

При срабатывании любого из условий происходит следующее:

- снимается дамп кучи и сохраняется в системное NFS-хранилище (в директорию `dumps/<группа_ресурсов>/...`);
- сервер приложений автоматически перезапускается, чтобы восстановить нормальную работу.

Это означает, что в проблемном состоянии дамп снимается только один раз; после перезапуска, если проблема возникнет
снова, условия будут отслеживаться заново и может быть снят новый дамп.

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

### Что делать при появлении автоматических дампов

Если вы обнаружили в системном хранилище дамп, снятый автоматически, это указывает на потенциальные проблемы в работе
компонента. Рекомендуется выполнить следующие действия:

- **Скачайте файл дампа** с NFS-хранилища для дальнейшего анализа или передачи разработчикам.
- **Проверьте логи сервера приложений и метрики в Grafana** (особенно, дашборд VM Memory) за период 5–15 минут до
  момента создания дампа, чтобы получить контекст произошедшего (нагрузка, количество запросов, использование памяти,
  время ответа и т.п.).
- **Сообщите о проблеме специалистам сопровождения Global ERP**, приложив собранную информацию. По умолчанию анализ
  выполняется в контуре заказчика; дамп передаётся за его пределы только при разрешённой передаче, как описано ниже.

```{note}
Все дампы (как автоматические, так и созданные вручную) автоматически удаляются из системного хранилища через три дня. Удаление выполняется компонентом **nsctl**, который регулярно проверяет время создания файлов и очищает устаревшие. Поэтому при обнаружении проблемы следует своевременно скачать необходимые файлы.
```

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

Запустите утилиту, указав ваше пространство имен и, опционально, название пода:

```bash
./make_dump.sh --namespace gs-ctk --pod gs-cluster-1-global-server-share-12345678-9abc
```

Если вы не укажете название пода, вам будет предложено выбрать один из подов, в котором можно снять дамп. Выбрать под
можно клавишами клавиатуры со стрелками.

```text
Выберите под для снятия дампа:gs-cluster-1-global-server-share-12345678-9abc
Снятие дампа сервера приложения (планировщика, gossiprouter, обходчика очередей) с пода gs-cluster-1-global-server-share-12345678-9abc
Снятие дампа globalserver
Dumping heap to /root/globalserver/workspace/mnt/sys/dumps/gs-cluster-1/gs-cluster-1-global-server-share-12345678-9abc-qgld8_2026_04_01_10_00_00.hprof.tmp ...
Heap dump file created [28915853 bytes in 0.038 secs]
Снят дамп и сохранен на системное (NFS) хранилище по адресу: `dumps/gs-cluster-1/gs-cluster-1-global-server-share-12345678-9abc-qgld8_2026_04_01_10_00_00.hprof`. Файл будет автоматически удален через три дня.
```

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

Если вы не хотите использовать nscli, вы можете запустить команду непосредственно в поде:

```bash
./make_dump.sh
```

```text
Снятие дампа globalserver
Dumping heap to /root/globalserver/workspace/mnt/sys/dumps/gs-cluster-1/gs-cluster-1-global-server-share-12345678-9abc-qgld8_2026_04_01_10_00_00.hprof.tmp ...
Heap dump file created [28915853 bytes in 0.038 secs]
Снят дамп и сохранен на системное (NFS) хранилище по адресу: `dumps/gs-cluster-1/gs-cluster-1-global-server-share-12345678-9abc-qgld8_2026_04_01_10_00_00.hprof`. Файл будет автоматически удален через три дня.
```
## Порядок работы с дампом

1. Зафиксируйте проблему: время с часовым поясом, симптомы, компонент, под и действия пользователей.
2. Снимите дамп нужного пода командой из раздела [Использование в nscli](#использование-в-nscli) либо используйте уже
   созданный автоматический дамп.
3. Сохраните завершённый `.hprof` из NFS до автоматического удаления. Перенесите его в рабочий каталог на ВМ для
   анализа.
4. Откройте файл в VisualVM для первичного просмотра или сразу в MAT для подробного исследования.
5. Сопоставьте найденные объекты с логами и графиками памяти.
6. Запишите результаты по шаблону в конце инструкции. При необходимости передайте их специалистам сопровождения.

### Перед ручным снятием на работающем приложении

Ручной дамп можно снять с работающего Global ERP, не дожидаясь аварии. Выберите под, на котором наблюдается проблема:
снимок соседнего исправного пода может не содержать нужных объектов.

Снятие дампа создаёт дополнительную нагрузку на JVM и хранилище и может временно приостановить обработку запросов. Не
запускайте его одновременно на всех производственных подах. Проверьте свободное место на системном NFS; планируйте место
с учётом потенциального объёма кучи выбранной JVM. Размер файла заранее точно неизвестен.

До запуска сохраните:

- namespace, группу ресурсов, имя пода и контейнера;
- версию Global ERP, gs-ctk и Java, параметры `-Xmx` и лимит памяти контейнера;
- время последнего запуска пода и число перезапусков;
- описание выполнявшейся операции: отчёт, импорт, интеграция, фоновое задание или обычная работа пользователей;
- логи и графики VM Memory за период до и после проблемы.

## Выполнение анализа

### В контуре заказчика

Если передавать дамп за пределы организации нельзя, инструменты устанавливаются на стороне заказчика. Для этого
подготовьте отдельную рабочую станцию или ВМ с доступом к копии дампа. Для графических инструментов потребуется
графический сеанс.

1. Установите Java 21 и анализаторы по следующему разделу. В закрытый контур перенесите согласованные установочные пакеты
   заранее.
2. Скопируйте завершённый `.hprof` с NFS на диск ВМ.
3. При участии поддержки организуйте разрешённый доступ к ВМ либо совместный просмотр результатов.
4. Перед передачей даже краткого отчёта проверьте его содержимое: в нём могут оказаться значения полей объектов, пути и
   фрагменты прикладных данных.


### Передача через Nextcloud

Если передача разрешена правилами заказчика, дамп можно предоставить специалистам сопровождения через согласованный
Nextcloud.

1. Подготовьте `.hprof`, описание инцидента, относящиеся к нему логи и контрольную сумму SHA-256. При необходимости
   упакуйте дамп; для анализа архив затем нужно распаковать.
2. Загрузите материалы в согласованную папку Nextcloud с доступом для участников обращения. 
3. Срок хранения и удаление копий определяются регламентом обращения.

```{important}
Дамп может содержать прикладные документы, персональные данные, строки запросов, пароли и токены, если они находились в памяти процесса. Учитывайте это при выборе места хранения и круга доступа. 
Архивирование и изменение имени файла не обезличивают дамп. Отчёты и индексы анализатора также следует хранить в пределах разрешённого контура.
```

## Подготовка ВМ и инструментов

Для анализа используйте 64-разрядную ОС и 64-разрядный JDK. Для описанного рабочего места подходит **JDK 21**.

Установите инструменты из официальных источников:

- [VisualVM](https://visualvm.github.io/download.html) — отдельное приложение для первичного просмотра `.hprof`;
  устанавливается отдельно от JDK 21.
- [Eclipse Memory Analyzer (MAT)](https://eclipse.dev/mat/download/) — отдельное приложение для исследования
  удерживаемой памяти и формирования отчётов. Полная среда разработки Eclipse не нужна. Для MAT 1.17 требуется Java 21
  или выше; для другой выбранной версии проверьте её требования.
- Текстовый редактор, например VS Code, — для логов, описания инцидента и текстовых результатов.

Проверьте доступную Java:

```bash
java -version
```

Диск ВМ должен вмещать исходный файл, рабочую копию, индексы и отчёты. При распаковке также учитывайте место под архив.
Быстрый локальный диск предпочтительнее анализа непосредственно на сетевом NFS.

### Память самого анализатора

У MAT есть собственный лимит Java-кучи. Если при открытии дампа MAT сообщает `Java heap space`, это может означать
нехватку памяти **анализатору**.

Закройте MAT и измените существующий параметр `-Xmx` в `MemoryAnalyzer.ini`. Например, если ВМ располагает достаточной
свободной RAM:

```text
-vmargs
-Xmx8g
```

Сохраните остальные параметры файла; если блок `-vmargs` уже есть, второй добавлять не нужно. `8g` — пример, а не
обязательное требование для любого дампа. После изменения перезапустите MAT.
Подробности: [настройка памяти MAT](https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/tasks/configure_mat.html).

## Первичный просмотр в VisualVM

1. Запустите VisualVM.
2. Выберите **File → Load** и укажите распакованный `.hprof`. Если фильтр скрывает файл, выберите тип файлов heap dump.
3. Дождитесь окончания загрузки. На больших файлах первичное открытие занимает заметное время.
4. Откройте сводку **Summary**, затем представление объектов **Objects** или классов **Classes**. Названия элементов
   могут отличаться между версиями.
5. Отсортируйте классы по занятому объёму памяти, затем по числу экземпляров. Зафиксируйте первые 10–20 строк.
6. Выберите интересующий класс и перейдите к его экземплярам. Посмотрите размер, поля и ссылки на выбранный объект.

Параметры запуска описаны в [документации VisualVM](https://visualvm.github.io/docs/command-line-options.html).

## Подробный анализ в Eclipse Memory Analyzer

### Открытие и первый отчёт

1. Запустите **Memory Analyzer**.
2. Выберите **File → Open Heap Dump** и откройте рабочую копию `.hprof`.
3. Дождитесь разбора файла и создания индексов. У пользователя должны быть права записи в рабочий каталог.
4. Если программа предлагает выбрать отчёт, укажите **Leak Suspects Report**. Если предложение не появилось, откройте
   **Leak Suspects** из раздела отчётов или меню **Run Expert System Test**.
5. Сохраните сведения о найденных кандидатах: класс или объект, удерживаемый объём, долю кучи и цепочку удержания.

**Leak Suspects** выделяет возможные места накопления памяти. Это подсказки для проверки, а не подтверждение утечки.
Крупный штатный кэш или выполняющийся большой отчёт также могут попасть в список. Порядок запуска приведён
в [документации отчёта MAT](https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/tasks/runningleaksuspectreport.html).

### Как читать размеры памяти

| Показатель          | Что означает                                                                                                                                                        | Как использовать                                      |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|
| Objects / Instances | Количество экземпляров класса.                                                                                                                                      | Искать массовое накопление объектов.                  |
| Shallow Heap        | Память самого объекта, без объектов, на которые он ссылается. Для строки класса в гистограмме — сумма размеров его экземпляров.                                     | Понять, сколько непосредственно занимают эти объекты. |
| Retained Heap       | Память, которая могла бы освободиться, если выбранный объект стал бы недостижим и сборщик мусора удалил бы его вместе с объектами, удерживаемыми только через него. | Найти владельца большого объёма данных.               |

Например, объект очереди может сам занимать мало памяти, но удерживать множество заданий и их данных. Важен не только
размер очереди как объекта, но и объём удерживаемых ею объектов. Значения retained heap у родителя и его потомков нельзя
складывать: они могут включать одну и ту же память. Определения приведены
в [Shallow vs. Retained Heap](https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/concepts/shallowretainedheap.html).

### Histogram: какие объекты накопились

Откройте **Histogram** из сводки **Overview**. Начните с сортировки по **Shallow Heap** и **Objects**. Найдите крупные
группы объектов, затем переходите к экземплярам и их владельцам через контекстное меню.

Для первичной проверки используйте следующие ориентиры. Это направления исследования, а не готовые диагнозы:

| Наблюдение                                       | Что проверить                                                                     |
|--------------------------------------------------|-----------------------------------------------------------------------------------|
| Много `byte[]` или `char[]`                      | Буферы, содержимое файлов, строки и результаты обработки; кто удерживает массивы. |
| Большие коллекции и массивы `Object[]`           | Списки результатов, очереди, кэши; ожидаем ли такой объём при текущей операции.   |
| Много объектов прикладного класса                | С каким отчётом, импортом, сеансом или заданием они связаны.                      |
| Объекты завершённой операции остаются доступными | Нет ли ссылки из долгоживущего кэша, сеанса, потока или общей коллекции.          |

### Dominator Tree: кто удерживает память

Откройте **Dominator Tree** и отсортируйте строки по **Retained Heap**. Раскрывайте крупнейшие узлы, пока не найдёте
понятный прикладной объект: например, контейнер результатов, очередь заданий или кэш.

Дерево показывает зависимость удержания памяти. Его линии не обязательно являются непосредственными ссылками между
полями объектов. Для проверки реальных ссылок используйте просмотр объектов и пути к GC roots. Объяснение структуры
дерева: [Dominator Tree](https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/concepts/dominatortree.html).

Запишите полное имя класса, размер удерживаемой памяти и назначение найденного объекта, если оно известно. Не требуется
самостоятельно расшифровывать все внутренние классы платформы: сохраните цепочку и передайте её разработчикам.

### Path to GC Roots: почему объект не удаляется

Для подозрительного экземпляра откройте контекстное меню **Path to GC Roots**. GC roots — исходные точки, от которых JVM
определяет достижимость объектов, например ссылки из работающих потоков или статических полей.

Для первого просмотра выберите вариант, исключающий слабые, мягкие и фантомные ссылки, если он доступен. Он помогает
искать цепочки сильных ссылок. Сохраните выбранный режим в результатах анализа: разные режимы могут показывать разные
пути.

Проследите путь до владельца ссылки: потока, сеанса, статического поля, кэша или коллекции. Если путь заканчивается на
выполняющемся задании, уточните, должно ли оно ещё работать. Если операция завершена, выясните, почему её объекты всё
ещё доступны.
Подробности: [Path to GC Roots](https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/reference/inspections/path_to_gc_roots.html).

## Сравнение нескольких дампов

Сравнивайте снимки одного компонента с одинаковой версией приложения и сопоставимой нагрузкой. Снимок сразу после
запуска и снимок после массового импорта будут различаться даже у исправного приложения.

Для каждого снимка составьте таблицу: время, операция, занятая куча, крупнейшие классы, число их экземпляров и
крупнейшие удерживающие объекты. Ищите устойчивый рост одной группы объектов и сохранение ссылок после завершения
работы. Подтверждайте наблюдение графиком памяти после GC и данными о нагрузке.

Не сопоставляйте экземпляры по адресу объекта между разными снимками: адрес может изменяться. Сравнивайте назначение
владельца, классы, количество экземпляров и объёмы. Разница в общем размере `.hprof` не является доказательством утечки.

При расхождении чисел между анализаторами проверьте настройки обработки недостижимых объектов: MAT по умолчанию
исключает их при разборе. Не смешивайте результаты с разными настройками в одной сравнительной таблице.

## Типовые проблемы при открытии

| Симптом                                   | Действия                                                                                                                                                                                 |
|-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Анализатор не запускается                 | Проверьте требования выбранной версии, разрядность и используемый JDK. Для VisualVM можно явно указать `--jdkhome`.                                                                      |
| MAT сообщает `Java heap space`            | Проверьте свободную RAM и `-Xmx` самого MAT. Увеличьте лимит или перенесите анализ на ВМ с большим объёмом памяти.                                                                       |
| Подготовка идёт долго                     | Проверьте активность процесса, свободный диск и использование RAM. На крупном дампе построение индексов может быть длительным; не запускайте повторный анализ того же файла параллельно. |
| Ошибка чтения или неожиданный конец файла | Сверьте SHA-256 с исходником, проверьте завершение снятия дампа и распаковки. Файл `.hprof.tmp` может быть неполным.                                                                     |
| Не удаётся создать индексы                | Проверьте права записи и свободное место в рабочем каталоге.                                                                                                                             |
| Leak Suspects не нашёл проблему           | Изучите Histogram и Dominator Tree. Причина может находиться вне Java-кучи или требовать сравнения нескольких состояний.                                                                 |
| Крупнейшие объекты — штатный кэш          | Сопоставьте объём с настройками и нагрузкой. Крупный кэш сам по себе не доказывает утечку.                                                                                               |
| Под завершился с `OOMKilled`, дампа нет   | Проверьте события Kubernetes, лимиты и метрики памяти. Отсутствие heap dump в этом случае ожидаемо; вернитесь к разделу автоматического снятия.                                          |

