microsoft/procdump-for-linuxLinux-версия утилиты ProcDump Sysinternals
# ProcDump [](https://dev.azure.com/sysinternals/Tools/_build/latest?definitionId=341&branchName=master)
ProcDump — это переосмысление для Linux и Mac классического инструмента ProcDump из набора утилит Sysinternals для Windows. ProcDump предоставляет удобный способ для разработчиков Linux и Mac создавать дампы ядра своих приложений на основе триггеров производительности. ProcDump для Linux и Mac является частью [Sysinternals](https://sysinternals.com).
# Установка и использование
## Требования
* Минимальная ОС Linux:
* Red Hat Enterprise Linux / CentOS 7
* Fedora 29
* Ubuntu 16.04 LTS
* `gdb` >= 7.6.1
* Минимальная ОС Mac: Sierra
## Установка ProcDump
Инструкции по установке см. [здесь](https://github.com/microsoft/procdump-for-linux/blob/master/INSTALL.md).
## Сборка
Инструкции по сборке см. [здесь](https://github.com/microsoft/procdump-for-linux/blob/master/BUILD.md).
## Использование
**КРИТИЧЕСКОЕ ИЗМЕНЕНИЕ** С выпуском ProcDump 1.3 ключи теперь согласованы с версией ProcDump для Windows.
Обратите внимание, что [версия для Mac](https://github.com/microsoft/ProcDump-for-Mac) в настоящее время имеет ограниченный набор триггеров.
```
Capture Usage:
procdump [-n Count]
[-s Seconds]
[-c|-cl CPU_Usage]
[-m|-ml Commit_Usage1[,Commit_Usage2...]]
[-gcm [<GCGeneration>: | LOH: | POH:]Memory_Usage1[,Memory_Usage2...]]
[-gcgen Generation]
[-restrack [nodump]]
[-sr Sample_Rate]
[-tc Thread_Threshold]
[-fc FileDescriptor_Threshold]
[-sig Signal_Number1[,Signal_Number2...]]
[-e]
[-f Include_Filter,...]
[-fx Exclude_Filter]
[-mc Custom_Dump_Mask]
[-pf Polling_Frequency]
[-o]
[-log syslog|stdout]
{
{{[-w] Process_Name | [-pgid] PID} [Dump_File | Dump_Folder]}
}
Options:
-n Количество дампов для записи перед выходом.
-s Последовательные секунды перед записью дампа (по умолчанию 10).
-c Порог использования CPU, выше которого создавать дамп процесса.
-cl Порог использования CPU, ниже которого создавать дамп процесса.
-m Порог(и) использования памяти (МБ), выше которого создавать дампы.
-ml Порог(и) использования памяти (МБ), ниже которого создавать дампы.
-gcm [.NET] Порог(и) использования памяти GC (МБ), выше которого создавать дампы для указанного поколения или кучи (по умолчанию общее использование .NET памяти).
-gcgen [.NET] Создавать дамп при начале и завершении сборки мусора указанного поколения.
-restrack Включить отслеживание утечек памяти (семейство API malloc). Если используется без других триггеров, используйте 't' для ручного захвата отчета restrack. При использовании с другими триггерами опция 'nodump' может быть использована для предотвращения генерации дампа и создания только отчетов restrack.
-sr Частота выборки при использовании -restrack.
-tc Порог количества потоков, выше которого создавать дамп процесса.
-fc Порог количества файловых дескрипторов, выше которого создавать дамп процесса.
-sig Разделенный запятыми список номеров сигналов, при которых любой сигнал приводит к дампу процесса.
-e [.NET] Создавать дамп, когда процесс сталкивается с исключением.
-f Фильтр (включение) по содержимому .NET исключений (разделено запятыми). Поддерживаются подстановочные знаки (*).
-fx Фильтр (исключение) по содержимому стеков вызовов -restrack. Поддерживаются подстановочные знаки (*).
-mc Пользовательская маска дампа ядра (в hex), указывающая, какая память должна быть включена в дамп ядра. См. 'man core' (/proc/[pid]/coredump_filter) для доступных опций.
-pf Частота опроса.
-o Перезаписать существующий файл дампа.
-log Записывает расширенную трассировку ProcDump в указанный выходной поток (syslog или stdout).
-w Ожидать запуска указанного процесса, если он не запущен.
-pgid Указанный ID процесса относится к ID группы процессов.
```
### Отслеживание ресурсов
Ключ -restrack активирует отслеживание ресурсов, позволяя мониторить и сообщать о любых выделениях ресурсов, которые не были освобождены на момент создания дампа ядра. Результаты сохраняются в файл с расширением '.restrack'. В настоящее время отслеживаются следующие функции выделения/освобождения ресурсов:
Выделение:
* malloc
* calloc
* realloc
* reallocarray
* mmap
Освобождение:
* free
* munmap
Версия для Mac в настоящее время не реализует отслеживание ресурсов.
### Примеры
> Следующие примеры нацелены на процесс с pid == 1234
Следующая команда создаст дамп ядра немедленно.
```
sudo procdump 1234
```
Следующая команда создаст 3 дампа ядра с интервалом в 10 секунд.
```
sudo procdump -n 3 1234
```
Следующая команда создаст 3 дампа ядра с интервалом в 5 секунд.
```
sudo procdump -n 3 -s 5 1234
```
Следующая команда будет создавать дамп ядра каждый раз, когда использование CPU процесса >= 65%, до 3 раз, с интервалом не менее 10 секунд между дампами.
```
sudo procdump -c 65 -n 3 1234
```
Следующая команда будет создавать дамп ядра каждый раз, когда использование CPU процесса >= 65%, до 3 раз, с интервалом не менее 5 секунд между дампами.
```
sudo procdump -c 65 -n 3 -s 5 1234
```
Следующая команда создаст дамп ядра, когда использование CPU выходит за пределы диапазона [10, 65].
```
sudo procdump -cl 10 -c 65 1234
```
Следующая команда создаст дамп ядра, когда использование CPU >= 65% или использование памяти >= 100 МБ.
```
sudo procdump -c 65 -m 100 1234
```
Следующая команда создаст дамп ядра, когда использование памяти >= 100 МБ, а затем еще один дамп, когда использование памяти >= 200 МБ.
```
sudo procdump -m 100,200 1234
```
Следующая команда создаст отчет об утечке памяти (без дампов) каждый раз, когда пользователь нажимает 't':
```
sudo procdump -restrack 1234
```
Следующая команда создаст 3 отчета об утечке памяти (без дампов) с интервалом в 5 секунд:
```
sudo procdump -n 3 -s 5 -restrack nodump 1234
```
Следующая команда создаст дамп ядра и отчет об утечке памяти, когда использование памяти >= 100 МБ.
```
sudo procdump -m 100 -restrack 1234
```
Следующая команда создаст отчет об утечке памяти (без дампов), когда использование памяти >= 100 МБ.
```
sudo procdump -m 100 -restrack nodump 1234
```
Следующая команда создаст дамп ядра и отчет об утечке памяти, когда использование памяти >= 100 МБ, выполняя выборку каждого 10-го выделения памяти.
```
sudo procdump -m 100 -restrack -sr 10 1234
```
Следующая команда создаст дамп ядра и отчет об утечке памяти, когда использование памяти >= 100 МБ, исключая все стеки вызовов, содержащие фреймы со строкой "cache":
```
sudo procdump -m 100 -restrack -fx *cache* 1234
```
Следующая команда создаст дамп ядра, когда общее использование .NET памяти >= 100 МБ, а затем еще один дамп, когда использование памяти >= 200 МБ.
```
sudo procdump -gcm 100,200 1234
```
Следующая команда создаст дамп ядра, когда использование .NET памяти для поколения 1 >= 1 МБ, а затем еще один дамп, когда использование памяти >= 2 МБ.
```
sudo procdump -gcm 1:1,2 1234
```
Следующая команда создаст дамп ядра, когда использование памяти кучи больших объектов .NET >= 100 МБ, а затем еще один дамп, когда использование памяти >= 200 МБ.
```
sudo procdump -gcm LOH:100,200 1234
```
Следующая команда создаст дамп ядра в начале и в конце сборки мусора поколения 1 .NET.
```
sudo procdump -gcgen 1
```
Следующая команда создаст дамп ядра в каталоге `/tmp` немедленно.
```
sudo procdump 1234 /tmp
```
Следующая команда создаст дамп ядра в текущем каталоге с именем dump_0.1234. Если используется -n, файлы будут называться dump_0.1234, dump_1.1234 и так далее.
```
sudo procdump 1234 dump
```
Следующая команда создаст дамп ядра при возникновении SIGSEGV.
```
sudo procdump -sig 11 1234
```
Следующая команда создаст дамп ядра при возникновении SIGSEGV, где дамп ядра будет содержать только анонимные закрытые отображения.
```
sudo procdump -mc 1 -sig 11 1234
```
Следующая команда создаст дамп ядра, когда целевое .NET приложение генерирует исключение System.InvalidOperationException.
```
sudo procdump -e -f System.InvalidOperationException 1234
```
Фильтр включения поддерживает частичное совпадение и подстановочные знаки, поэтому следующая команда также создаст дамп ядра для System.InvalidOperationException:
```
sudo procdump -e -f InvalidOperation 1234
```
или
```
sudo procdump -e -f "*Invali*Operation*" 1234
```
> Все опции также можно использовать с `-w`, чтобы ожидать любой процесс с заданным именем.
Следующая команда ожидает процесс с именем `my_application` и создает дамп ядра немедленно, когда он найден.
```
sudo procdump -w my_application
```
## Текущие ограничения
* В настоящее время работает только на Linux с ядром версии 3.5+ или macOS Sierra+.
* Нет полной функциональной совместимости с версией ProcDump для Windows, в частности, отсутствует функция поддержания активности и пользовательские счетчики производительности.
# Обратная связь
* Задайте вопрос на StackOverflow (пометьте тегом ProcDumpForLinux)
* Запросите новую функцию на GitHub
* Голосуйте за популярные запросы функций
* Сообщите об ошибке в GitHub Issues
# Участие в разработке
Если вы заинтересованы в исправлении ошибок и внесении прямого вклада в код, пожалуйста, ознакомьтесь с [документом "Как внести вклад"](https://github.com/microsoft/procdump-for-linux/blob/master/CONTRIBUTING.md), который охватывает следующее:
* Как собрать и запустить из исходных кодов
* Рабочий процесс разработки, включая отладку и выполнение тестов
* Правила оформления кода
* Отправка pull request'ов
Пожалуйста, также ознакомьтесь с нашим [Кодексом поведения](https://github.com/microsoft/procdump-for-linux/blob/master/CODE_OF_CONDUCT.md).
# Лицензия
© Microsoft Corporation. Все права защищены.
Лицензировано под лицензией MIT.
ProcDump для Linux:
* Клонирует, компилирует и статически линкуется с libbpf (https://github.com/libbpf/libbpf)
* Копирует исходный код разрешения символов из BCC (https://github.com/iovisor/bcc)
* Использует eBPF