Аргументы¶

Аргументы pid и cpu позволяют задать отслеживаемый процесс и ЦП:

pid == 0 и cpu == -1

Это позволяет измерять вызывающий процесс/нить на любом ЦП.

pid == 0 и cpu >= 0

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

pid > 0 и cpu == -1

Это позволяет измерять указанный процесс/нить на любом ЦП.

pid > 0 и cpu >= 0

Это позволяет измерять указанный процесс/нить только, когда выполнение происходит на указанном ЦП.

pid == -1 и cpu >= 0

This measures all processes/threads on the specified CPU. This requires CAP_PERFMON (since Linux 5.8) or CAP_SYS_ADMIN capability or a /proc/sys/kernel/perf_event_paranoid value of less than 1.

pid == -1 и cpu == -1

Это некорректные значения и будет возвращена ошибка.

When pid is greater than zero, permission to perform this system call is governed by CAP_PERFMON (since Linux 5.9) and a ptrace access mode PTRACE_MODE_READ_REALCREDS check on older Linux versions; see ptrace(2).

The group_fd argument allows event groups to be created. An event group has one event which is the group leader. The leader is created first, with group_fd = -1. The rest of the group members are created with subsequent perf_event_open() calls with group_fd being set to the file descriptor of the group leader. (A single event on its own is created with group_fd = -1 and is considered to be a group with only 1 member.) An event group is scheduled onto the CPU as a unit: it will be put onto the CPU only if all of the events in the group can be put onto the CPU. This means that the values of the member events can be meaningfully compared—added, divided (to get ratios), and so on—with each other, since they have counted events for the same set of executed instructions.

Аргумент flags формируется с помощью объединения логической операцией ИЛИ нуля или более следующих значений:

PERF_FLAG_FD_CLOEXEC (начиная с Linux 3.14)

Этот флаг включает флаг close-on-exec на созданном файловом дескрипторе события, то есть файловый дескриптор автоматически закрывается при execve(2). Установка флага close-on-exec при создании, а не в процессе работы с помощью fcntl(2), позволяет избежать потенциальной состязательности, когда вызывающая нить вызывает perf_event_open() и fcntl(2) одновременно с запуском другой нитью вызовов fork(2) и execve(2).

PERF_FLAG_FD_NO_GROUP

Этот флаг указывает событию игнорировать параметр group_fd, если не выполняется настройка перенаправления вывода с помощью флага PERF_FLAG_FD_OUTPUT.

PERF_FLAG_FD_OUTPUT (не работает, начиная с Linux 2.6.35)

Этот флаг переключает вывод измерений с буфера mmap в событие, указанное group_fd.

PERF_FLAG_PID_CGROUP (начиная с Linux 2.6.39)

Этот флаг включает поконтейнерное системное слежение. Контейнер — это абстракция, которая изолирует набор ресурсов для их точного расходования (ЦП, память и т. п.). В этом режиме событие измеряется только, если нить выполняется в отслеживаемом ЦП, принадлежащем назначенному контейнеру (cgroup). Значение cgroup задаётся переданным файловым дескриптором, открываемом в его каталоге в файловой системе cgroupfs. Например, если отслеживаемая cgroup называется test, то файловый дескриптор для /dev/cgroup/test (предполагается, что cgroupfs смонтирована в /dev/cgroup) должен передаваться как параметр pid. Слежение за cgroup доступно только для системных событий и поэтому требуется дополнительных прав.

Структура perf_event_attr предоставляет подробную информацию о создаваемом событии.

struct perf_event_attr {


    __u32 type;         /* тип события */


    __u32 size;         /* размер структуры атрибутов */


    __u64 config;       /* настройки для типа */


    union {


        __u64 sample_period;    /* период выборки */


        __u64 sample_freq;      /* частота выборки */


    };


    __u64 sample_type;  /* значения, включённые в измерение */


    __u64 read_format;  /* значения, возвращаемые при чтении */


    __u64 disabled       : 1,   /* off by default */


          inherit        : 1,   /* children inherit it */


          pinned         : 1,   /* must always be on PMU */


          exclusive      : 1,   /* only group on PMU */


          exclude_user   : 1,   /* don't count user */


          exclude_kernel : 1,   /* don't count kernel */


          exclude_hv     : 1,   /* don't count hypervisor */


          exclude_idle   : 1,   /* don't count when idle */


          mmap           : 1,   /* include mmap data */


          comm           : 1,   /* include comm data */


          freq           : 1,   /* use freq, not period */


          inherit_stat   : 1,   /* per task counts */


          enable_on_exec : 1,   /* next exec enables */


          task           : 1,   /* trace fork/exit */


          watermark      : 1,   /* wakeup_watermark */


          precise_ip     : 2,   /* skid constraint */


          mmap_data      : 1,   /* non-exec mmap data */


          sample_id_all  : 1,   /* sample_type all events */


          exclude_host   : 1,   /* don't count in host */


          exclude_guest  : 1,   /* don't count in guest */


          exclude_callchain_kernel : 1,


                                /* exclude kernel callchains */


          exclude_callchain_user   : 1,


                                /* exclude user callchains */


          mmap2          :  1,  /* include mmap with inode data */


          comm_exec      :  1,  /* flag comm events that are


                                   due to exec */


          use_clockid    :  1,  /* use clockid for time fields */


          context_switch :  1,  /* context switch data */


          write_backward :  1,  /* Write ring buffer from end


                                   to beginning */


          namespaces     :  1,  /* include namespaces data */


          ksymbol        :  1,  /* include ksymbol events */


          bpf_event      :  1,  /* include bpf events */


          aux_output     :  1,  /* generate AUX records


                                   instead of events */


          cgroup         :  1,  /* include cgroup events */


          text_poke      :  1,  /* include text poke events */


          build_id       :  1,  /* use build id in mmap2 events */


          inherit_thread :  1,  /* children only inherit */


                                /* if cloned with CLONE_THREAD */


          remove_on_exec :  1,  /* event is removed from task


                                   on exec */


          sigtrap        :  1,  /* send synchronous SIGTRAP


                                   on event */


          __reserved_1   : 26;


    union {


        __u32 wakeup_events;    /* пробуждаться каждые n событий */


        __u32 wakeup_watermark; /* байт до пробуждения */


    };


    __u32     bp_type;          /* тип точки останова */


    union {


        __u64 bp_addr;          /* адрес точки останова */


        __u64 kprobe_func;      /* для perf_kprobe */


        __u64 uprobe_path;      /* для perf_uprobe */


        __u64 config1;          /* расширение of config */


    };


    union {


        __u64 bp_len;           /* breakpoint length */


        __u64 kprobe_addr;      /* with kprobe_func == NULL */


        __u64 probe_offset;     /* for perf_[k,u]probe */


        __u64 config2;          /* extension of config1 */


    };


    __u64 branch_sample_type;   /* enum perf_branch_sample_type */


    __u64 sample_regs_user;     /* user regs to dump on samples */


    __u32 sample_stack_user;    /* size of stack to dump on


                                   samples */


    __s32 clockid;              /* clock to use for time fields */


    __u64 sample_regs_intr;     /* regs to dump on samples */


    __u32 aux_watermark;        /* aux bytes before wakeup */


    __u16 sample_max_stack;     /* max frames in callchain */


    __u16 __reserved_2;         /* align to u64 */


    __u32 aux_sample_size;      /* max aux sample size */


    __u32 __reserved_3;         /* align to u64 */


    __u64 sig_data;             /* user data for sigtrap */
};

Описание полей структуры perf_event_attr:

type

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

size

Размер структуры perf_event_attr совместимости. Присвоение значения sizeof(struct perf_event_attr) позволяет ядру видеть размер структуры во время компиляции.

Соответствующее определение PERF_ATTR_SIZE_VER0 равно 64; это размер первой опубликованной структуры. Значение PERF_ATTR_SIZE_VER1 равно 72, соответствует добавленным в Linux 2.6.33 точкам останова. Значение PERF_ATTR_SIZE_VER2 равно 80, соответствует добавленным в Linux 3.4 ветвям замеров. Значение PERF_ATTR_SIZE_VER3 равно 96, соответствует добавленным в Linux 3.7 полям sample_regs_user и sample_stack_user. Значение PERF_ATTR_SIZE_VER4 равно 104, соответствует добавленному в Linux 3.19 полю sample_regs_intr. Значение PERF_ATTR_SIZE_VER5 равно 112, соответствует добавленному в in Linux 4.1 полю aux_watermark.

config

Здесь указывается требуемое событие в сочетании с полем type. Поля config1 и config2 также учитываются, если 64 бит недостаточно для полного описания события. Кодирование значения этих полей зависит от события.

Есть несколько способов присвоения значения полю config, которые зависят от значения описанного ранее поля type. Содержимое различных возможных настроек config выделяется по type.

Если type равно PERF_TYPE_HARDWARE, то измеряется одно из общих аппаратных событий ЦП. Не все из них доступны на всех платформах. В config может быть одно из следующих значений:

Если значение type равно PERF_TYPE_SOFTWARE, то измеряются программные события, предоставляемые ядром. Значением config может быть одно из следующих:

config = (perf_hw_cache_id) |


         (perf_hw_cache_op_id << 8) |


         (perf_hw_cache_op_result_id << 16);

kprobe_func, uprobe_path, kprobe_addr и probe_offset

Эти поля описывают kprobe/uprobe в динамических PMU kprobe и uprobe. Для kprobe: используйте kprobe_func и probe_offset, или используйте kprobe_addr и оставьте kprobe_func равным NULL. Для uprobe: используйте uprobe_path и probe_offset.

sample_period, sample_freq

«Измеряющее» событие генерирует уведомление о переполнении каждые N событий, где N указывается в sample_period. У измеряющего события sample_period > 0. Если происходит переполнение, то запрашиваемые данные записываются в буфер mmap. В поле sample_type указывается какие данные записываются при каждом переполнении.

Если вы хотите использовать частоту, а не период, то можно использовать sample_freq. В этом случае установите флаг freq. Ядро откорректирует период измерений, чтобы попытаться достигнуть желаемой частоты. Частота измеряется в тактах таймера.

sample_type

Различными битами этого поля определяется какие значения включать в измерение. Они будут записаны в кольцевой буфер, который доступен в пользовательском пространстве через mmap(2). Порядок сохраняемых значений описан в разделе «Разбивка MMAP» ниже; он не совпадает с порядком enum perf_event_sample_format.

union perf_sample_weight {


    u64  full;           /* PERF_SAMPLE_WEIGHT */


    struct {             /* PERF_SAMPLE_WEIGHT_STRUCT */


        u32  var1_dw;


        u16  var2_w;


        u16  var3_w;


    };
};

read_format

В этом поле задаётся формат данных, возвращаемых read(2) из файлового дескриптора perf_event_open().

disabled

Битом disabled определяется, будет ли счётчик изначально включен или выключен. Если выключен, то событие может быть включено позже с помощью ioctl(2), prctl(2) или enable_on_exec.

Обычно, при создании группы событий значение disabled лидера группы устанавливается в 1, а у любого дочернего события disabled устанавливается в 0. Несмотря на disabled равное 0, дочерние события не запускаются до тех пор, пока не включится лидер группы.

inherit

Битом inherit задаётся, должен ли этот счётчик событий считать события дочерних задач, кроме указанной задачи. Это применяется только к новым потомкам, а не к существующим на момент создания счётчика (и не к новым потомкам существующих потомков).

Наследование не работает с некоторыми комбинациями значений read_format, например с PERF_FORMAT_GROUP.

pinned

Битом pinned определяется, что счётчик должен всегда быть на ЦП, если это возможно. Применяется только к аппаратным счётчикам и только для лидеров группы. Если прикреплённый счётчик невозможно поместить на ЦП (например, потому что кончились аппаратные счётчики или возник конфликт с другим событием), то счётчик переводится в состояние «ошибки», в котором чтение возвращает конец файла (т. е., read(2) возвращает 0) до тех пор, пока счётчик не будет включен или выключен.

exclusive

Битом exclusive определяется, что когда эта группа счётчиков на ЦП, то должна быть только одна группа использующая счётчики ЦП. В будущем, это может позволить следящим программам поддерживать возможности PMU, необходимые для автономной работы без нарушения других аппаратных счётчиков.

Заметим, что многие неожиданные ситуации могут не позволить событиям с битом exclusive даже выполниться. К ним относятся выполнение любых пользовательских системных измерений, а также использование ядром счётчиков производительности (включая обычно включённый интерфейс NMI Watchdog Timer).

exclude_user

Если этот бит установлен, то счётчик не учитывает события, происходящие в пользовательском пространстве.

exclude_kernel

Если этот бит установлен, то счётчик не учитывает события, происходящие в пространстве ядра.

exclude_hv

Если этот бит установлен, то счётчик не учитывает события, происходящие в гипервизоре. В основном для PMU, имеющего для этого возможности (такие как POWER). На большинстве машин необходима дополнительная поддержка для измерений гипервизора.

exclude_idle

Если установлен, то счётчик не учитывает когда ЦП выполняет задачу простоя. Хотя сейчас вы и можете включить его для любого типа события, он игнорируется во всех кроме программных событий.

mmap

Бит mmap включает генерацию измерений PERF_RECORD_MMAP для каждого вызова mmap(2) с установленными битом PROT_EXEC. Это позволяет инструментам замечать новый исполняемый код, отображённый в программу (например, общие динамические библиотеки) так, чтобы адреса можно было отобразить обратно в первоначальный код.

comm

Битом comm включается слежение за именем команды процесса, изменяемого системными вызовами execve(2) и prctl(PR_SET_NAME), а также через запись в /proc/self/comm. Если флаг comm_exec также установлен (работает, начиная с Linux 3.16), то можно использовать вспомогательный флаг PERF_RECORD_MISC_COMM_EXEC, чтобы отличить использование execve(2) от остальных.

freq

Если этот бит установлен, то задания интервала измерения используется sample_frequency, а не sample_period.

inherit_stat

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

enable_on_exec

Если этот бит установлен, то счётчик автоматически включается после вызова execve(2).

task

Если этот бит установлен, то в кольцевой буфер включаются уведомления fork/exit.

watermark

Если установлен, то выдаётся уведомление о переполнении при пересечении границы wakeup_watermark. В противном случае, уведомления о переполнении выдаются после wakeup_events измерений.

precise_ip (начиная с Linux 2.6.35)

Управляет размером ската (skid). Скат — количество инструкций, выполняемое между возникновением интересующего события и когда ядро способно остановиться и записать событие. Чем меньше скат тем лучше: это приближает события к инструкциям, от которых они возникли, но часто значение ограничивается аппаратурой.

Возможными значениями этого поля могут быть:

mmap_data (начиная с Linux 2.6.36)

Противоположно полю mmap. Включает генерацию измерений PERF_RECORD_MMAP для вызовов mmap(2), у которых не установлен бит PROT_EXEC (например, у данных и общей памяти SysV).

sample_id_all (начиная с Linux 2.6.38)

Если установлен, то TID, TIME, ID, STREAM_ID и ЦП могут дополнительно включаться в не-PERF_RECORD_SAMPLE, если выбран соответствующий sample_type.

Если указан PERF_SAMPLE_IDENTIFIER, то дополнительно включается значение ID в качестве последнего значения для облегчения разбора потока записей. Это может привести к появлению значения id дважды.

Состав описывается следующей псевдо-структурой:

struct sample_id {


    { u32 pid, tid; } /* если есть PERF_SAMPLE_TID */


    { u64 time;     } /* если есть PERF_SAMPLE_TIME */


    { u64 id;       } /* если есть PERF_SAMPLE_ID */


    { u64 stream_id;} /* если есть PERF_SAMPLE_STREAM_ID */


    { u32 cpu, res; } /* если есть PERF_SAMPLE_CPU */


    { u64 id;       } /* если есть PERF_SAMPLE_IDENTIFIER */
};
    

exclude_host (начиная с Linux 3.2)

При проведении измерений, которые включают процессы, запускающие экземпляры VM (т. е. выполняют I ioctl(2) KVM_RUN), измеряются только события, возникающие внутри гостевого экземпляра. Имеет смысл только вне гостевых машин; эта настройка не изменяет счётчики, собираемые внутри гостей. В настоящее время работает только на x86.

exclude_guest (начиная с Linux 3.2)

При проведении измерений, которые включают процессы, запускающие экземпляры VM (т. е. выполняют I ioctl(2) KVM_RUN), не измеряются события, возникающие внутри гостевого экземпляра. Имеет смысл только вне гостевых машин; эта настройка не изменяет счётчики, собираемые внутри гостей. В настоящее время работает только на x86.

exclude_callchain_kernel (начиная с Linux 3.7)

Не включать цепочку вызовов ядра.

exclude_callchain_user (начиная с Linux 3.7)

Не включать цепочку вызовов пользовательского пространства.

mmap2 (начиная с Linux 3.16)

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

comm_exec (начиная с Linux 3.16)

Флаг определения свойств, не изменяет поведение ядра. Если флаг установлен, то когда включён comm, будет устанавливаться флаг PERF_RECORD_MISC_COMM_EXEC в поле misc заголовка записи comm, если сообщается о событии переименования, вызванного вызовом execve(2). Это позволяет инструментам различать различные тип переименования процесса.

use_clockid (начиная с Linux 4.1)

Через clockid позволяет выбрать внутренние часы Linux, используемые для генерации меток времени. Это может облегчить соответствие времён измерений с метками времени, сгенерированными другими инструментами.

context_switch (начиная с Linux 4.3)

Включает генерацию записей PERF_RECORD_SWITCH при переключении контекста. Также включает генерацию записей PERF_RECORD_SWITCH_CPU_WIDE при измерении в режиме CPU-wide. Данная возможность дополняет существующие точки трассировки и программные события для измерения переключений контекста. Преимущество этого метода в том, что он даёт полную информацию даже при ограничительных настройках perf_event_paranoid.

write_backward (начиная с Linux 4.6)

This causes the ring buffer to be written from the end to the beginning. This is to support reading from overwritable ring buffer.

namespaces (начиная с Linux 4.11)

This enables the generation of PERF_RECORD_NAMESPACES records when a task enters a new namespace. Each namespace has a combination of device and inode numbers.

ksymbol (начиная с Linux 5.0)

This enables the generation of PERF_RECORD_KSYMBOL records when new kernel symbols are registered or unregistered. This is analyzing dynamic kernel functions like eBPF.

bpf_event (начиная с Linux 5.0)

This enables the generation of PERF_RECORD_BPF_EVENT records when an eBPF program is loaded or unloaded.

aux_output (since Linux 5.4)

This allows normal (non-AUX) events to generate data for AUX events if the hardware supports it.

cgroup (начиная с Linux 5.7)

This enables the generation of PERF_RECORD_CGROUP records when a new cgroup is created (and activated).

text_poke (начиная с Linux 5.8)

This enables the generation of PERF_RECORD_TEXT_POKE records when there's a change to the kernel text (i.e., self-modifying code).

build_id (since Linux 5.12)

This changes the contents in the PERF_RECORD_MMAP2 to have a build-id instead of device and inode numbers.

inherit_thread (since Linux 5.13)

This disables the inheritance of the event to a child process. Only new threads in the same process (which is cloned with CLONE_THREAD) will inherit the event.

remove_on_exec (since Linux 5.13)

This closes the event when it starts a new process image by execve(2).

sigtrap (since Linux 5.13)

This enables synchronous signal delivery of SIGTRAP on event overflow.

wakeup_events, wakeup_watermark

Это объединение задаёт как много измерений (wakeup_events) или байт (wakeup_watermark) должно произойти до уведомления о переполнении. Используемое поле выбирается битом флага watermark.

В wakeup_events подсчитываются только записи с типом PERF_RECORD_SAMPLE. Для приёма уведомления о переполнении всех типов PERF_RECORD выберите watermark и присвойте wakeup_watermark значение 1.

До Linux 3.0 установка wakeup_events в 0 приводила к выключению уведомления о переполнении; новые ядра считают 0 как 1.

bp_type (начиная с Linux 2.6.33)

Задаёт тип точки останова. Может быть:

bp_addr (начиная с Linux 2.6.33)

Адрес точки останова. Для точек останова выполнения это адрес памяти интересующей инструкции; для точек останова чтения и записи это адрес памяти интересующего расположения в памяти.

config1 (начиная с Linux 2.6.39)

Значение config1 используется для задания событий, которым нужен дополнительный регистр или не хватает обычного поля config. Это поле используется в Linux 3.3 и новее для неструктурированного OFFCORE_EVENTS на архитектурах Nehalem/Westmere/SandyBridge.

bp_len (начиная с Linux 2.6.33)

В bp_len содержится длина точки измеряемой останова, если значение type равно PERF_TYPE_BREAKPOINT. Можно указывать HW_BREAKPOINT_LEN_1, HW_BREAKPOINT_LEN_2, HW_BREAKPOINT_LEN_4 и HW_BREAKPOINT_LEN_8. Для точки останова выполнения присвойте sizeof(long).

config2 (начиная с Linux 2.6.39)

Поле config2 — дальнейшее расширение поля config1.

branch_sample_type (начиная с Linux 3.4)

Если установлен PERF_SAMPLE_BRANCH_STACK, то ветви будут включаться в запись ветви.

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

sample_regs_user (начиная с Linux 3.7)

Данной битовой маской задаётся набор битов пользовательских регистров ЦП, которые сохраняются в измерениях. Значения битов в битовой маске зависят от архитектуры и описаны в заголовочном файле ядра arch/ARCH/include/uapi/asm/perf_regs.h.

sample_stack_user (начиная с Linux 3.7)

Задаёт размер сохраняемого пользовательского стека, если указан PERF_SAMPLE_STACK_USER.

clockid (начиная с Linux 4.1)

Если установлен use_clockid, то этим полем выбирается внутренний таймер Linux, используемый для меток времени.Доступные таймеры определены в linux/time.h; в настоящее время поддерживаются CLOCK_MONOTONIC, CLOCK_MONOTONIC_RAW, CLOCK_REALTIME, CLOCK_BOOTTIME и CLOCK_TAI.

aux_watermark (начиная с Linux 4.1)

Определяет какое количество данных требуется для запуска измерения PERF_RECORD_AUX.

sample_max_stack (начиная с Linux 4.8)

Если sample_type содержит PERF_SAMPLE_CALLCHAIN, то в этом поле задаётся количество выводимых кадров стека при генерации цепочки вызовов.

aux_sample_size (since Linux 5.5)

When PERF_SAMPLE_AUX flag is set, specify the desired size of AUX data. Note that it can get smaller data than the specified size.

sig_data (since Linux 5.13)

This data will be copied to user's signal handler (through si_perf in the siginfo_t) to disambiguate which event triggered the signal.

Чтение результатов¶

После открытия файлового дескриптора с помощью perf_event_open(), значения событий доступны на чтение. События задаются вв поле read_format структуры attr в момент открытия.

Если вы попытаетесь выполнить чтение в буфер недостаточного размера, то результатом будет ошибка ENOSPC.

Вот компоновка данных, возвращаемых чтением:

•

Если указан PERF_FORMAT_GROUP для разрешения чтения всех событий в группе за раз:

struct read_format {


    u64 nr;            /* The number of events */


    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */


    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */


    struct {


        u64 value;     /* The value of the event */


        u64 id;        /* if PERF_FORMAT_ID */


        u64 lost;      /* if PERF_FORMAT_LOST */


    } values[nr];
};
    

•

Если PERF_FORMAT_GROUP не указан:

struct read_format {


    u64 value;         /* The value of the event */


    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */


    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */


    u64 id;            /* if PERF_FORMAT_ID */


    u64 lost;          /* if PERF_FORMAT_LOST */
};
    

Значения полей:

nr

Количество событий в этом файловом дескрипторе. Доступно только, если указан PERF_FORMAT_GROUP.

time_enabled, time_running

Полное время события с момента включения и выполнения. Обычно, эти значения одинаковы. Если событий больше, чем доступно счётчиков слотов в PMU, то возникает мультиплексирование. В этом случае события выполняются только часть времени и значения time_enabled и time running можно использовать для градации рассчитанного значения в счётчике.

value

Целое беззнаковое 64-битное значение, содержащее счётчик-результат.

id

Глобально уникальное значение данного события; присутствует только, если в read_format указан PERF_FORMAT_ID.

lost

The number of lost samples of this event; only present if PERF_FORMAT_LOST was specified in read_format.

Разбивка MMAP¶

При использовании perf_event_open() в режиме измерений, асинхронные события (такие как переполнение счётчика или слежение за PROT_EXEC mmap) протоколируются в кольцевой буфер. Этот кольцевой буфер создаётся и доступен через mmap(2).

The mmap size should be 1+2^n pages, where the first page is a metadata page (struct perf_event_mmap_page) that contains various bits of information such as where the ring-buffer head is.

Before Linux 2.6.39, there is a bug that means you must allocate an mmap ring buffer when sampling even if you do not plan to access it.

Структура первой страницы метаданных mmap:

struct perf_event_mmap_page {


    __u32 version;        /* номер версии структуры */


    __u32 compat_version; /* наименьшая совместимая версия */


    __u32 lock;           /* seqlock для синхронизации */


    __u32 index;          /* идентификатор аппаратного счётчика */


    __s64 offset;         /* добавляется к значению аппаратного


                             счётчика */


    __u64 time_enabled;   /* время активности события */


    __u64 time_running;   /* время события на ЦП */


    union {


        __u64   capabilities;


        struct {


            __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,


                  cap_bit0_is_deprecated : 1,


                  cap_user_rdpmc         : 1,


                  cap_user_time          : 1,


                  cap_user_time_zero     : 1,


        };


    };


    __u16 pmc_width;


    __u16 time_shift;


    __u32 time_mult;


    __u64 time_offset;


    __u64 __reserved[120];   /* дополнение до 1 k */


    __u64 data_head;         /* заголовок в секции данных */


    __u64 data_tail;         /* хвост, записываемый из


                                пользовательского пространства */


    __u64 data_offset;       /* начало буфера */


    __u64 data_size;         /* размер буфера данных */


    __u64 aux_head;


    __u64 aux_tail;


    __u64 aux_offset;


    __u64 aux_size;
}

В следующем списке поля структуры perf_event_mmap_page описаны более подробно:

version

Номер версии этой структуры.

compat_version

Наименьший номер версии, совместимой с данной структурой.

lock

Значение seqlock для синхронизации.

index

Уникальный идентификатор аппаратного счётчика.

offset

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

time_enabled

Время активности события.

time_running

Время выполнения события.

cap_usr_time / cap_usr_rdpmc / cap_bit0 (начиная с Linux 3.4)

С Linux 3.4 по Linux 3.11 был дефект в определении cap_usr_time и cap_usr_rdpmc. В обоих биты указывали на одно место, поэтому было невозможно узнать что на самом деле установлено: cap_usr_time или cap_usr_rdpmc.

Начиная с Linux 3.12, они были переименованы в cap_bit0 и вместо них вы должны использовать поля cap_user_time и cap_user_rdpmc.

cap_bit0_is_deprecated (начиная с Linux 3.12)

Если установлен, то этот бит показывает, что ядро поддерживает правильно разделённые биты cap_user_time и cap_user_rdpmc.

Если не установлен, то это означает используется старое ядро, в котором cap_usr_time и cap_usr_rdpmc отражают один и тот же бит, и оба свойства нужно использовать с осторожностью.

cap_user_rdpmc (начиная с Linux 3.12)

Если есть аппаратная поддержка чтения счётчиков производительности из пользовательского пространства без системного вызова (инструкция «rdpmc» в x86), то для чтения можно использовать следующий код:

u32 seq, time_mult, time_shift, idx, width;
u64 count, enabled, running;
u64 cyc, time_offset;
do {


    seq = pc->lock;


    barrier();


    enabled = pc->time_enabled;


    running = pc->time_running;


    if (pc->cap_usr_time && enabled != running) {


        cyc = rdtsc();


        time_offset = pc->time_offset;


        time_mult   = pc->time_mult;


        time_shift  = pc->time_shift;


    }


    idx = pc->index;


    count = pc->offset;


    if (pc->cap_usr_rdpmc && idx) {


        width = pc->pmc_width;


        count += rdpmc(idx - 1);


    }


    barrier();
} while (pc->lock != seq);
    

cap_user_time (начиная с Linux 3.12)

Этот бит указывает на наличие аппаратного, неизменяемого, неостанавливаемого счётчика временных меток (TSC на x86).

cap_user_time_zero (начиная с Linux 3.12)

Указывает на наличие time_zero, который позволяет отображать значения временных меток в аппаратные часы.

pmc_width

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

pmc <<= 64 - pmc_width;
pmc >>= 64 - pmc_width; // сдвиг знака вправо
count += pmc;
    

time_shift, time_mult, time_offset

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

u64 quot, rem;
u64 delta;
quot  = cyc >> time_shift;
rem   = cyc & (((u64)1 << time_shift) - 1);
delta = time_offset + quot * time_mult +


        ((rem * time_mult) >> time_shift);
    

Где time_offset, time_mult, time_shift и cyc читаются в цикле seqcount, описанном выше. Затем эта разница может быть добавлена для включения и, возможно, запуска (если idx) для улучшения масштабирования:

enabled += delta;
if (idx)


    running += delta;
quot  = count / running;
rem   = count % running;
count = quot * enabled + (rem * enabled) / running;
    

time_zero (начиная с Linux 3.12)

Если установлен cap_usr_time_zero, то аппаратные часы (счётчик временных меток TSC на x86) могут быть вычислены из значений time_zero, time_mult и time_shift:

time = timestamp - time_zero;
quot = time / time_mult;
rem  = time % time_mult;
cyc  = (quot << time_shift) + (rem << time_shift) / time_mult;
    

И наоборот:

quot = cyc >> time_shift;
rem  = cyc & (((u64)1 << time_shift) - 1);
timestamp = time_zero + quot * time_mult +


            ((rem * time_mult) >> time_shift);
    

data_head

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

На платформах с SMP после чтения значения data_head из пользовательского пространства нужно вызвать функцию rmb().

data_tail

Если отображение PROT_WRITE, то значение data_tail будет записываться из пользовательского пространства для отражения последних прочитанных данных. В этом случае ядро не перезаписывает непрочитанные данные.

data_offset (начиная с Linux 4.1)

Содержит смещение расположения начала данных образца perf в буфере mmap.

data_size (начиная с Linux 4.1)

Содержит размер области образца perf в буфере mmap.

aux_head, aux_tail, aux_offset, aux_size (начиная с Linux 4.1)

The AUX region allows mmap(2)-ing a separate sample buffer for high-bandwidth data streams (separate from the main perf sample buffer). An example of a high-bandwidth stream is instruction tracing support, as is found in newer Intel processors.

Для задания области AUX, сначала задайте aux_offset со смещением больше чем data_offset+data_size, а в aux_size нужно указать желаемых размер буфера. Желаемое смещение и размер должны быть выровнены по границе страницы, и размер должен быть степенью двойки. Затем эти значения передаются в mmap для отображения буфера AUX. Страницы буфера AUX учитываются в ограничении ресурса RLIMIT_MEMLOCK (смотрите setrlimit(2)), а также проходят допустимость perf_event_mlock_kb.

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

Указатели кольцевого буфера aux_head и aux_tail работают и подчиняются тем же правилам, которые описаны выше для data_head и data_tail.

Далее приводится раскладка страниц кольцевого буфера размером 2^n.

Если установлен perf_event_attr.sample_id_all, то все типы событий будут иметь выбранные поля sample_type, относящиеся к где/когда (отличительность) происходило событие (TID, TIME, ID, CPU, STREAM_ID), описанные в PERF_RECORD_SAMPLE ниже; они будут спрятаны за perf_event_header и уже имеющимися полями, то есть в записываться в конец полезных данных. Это позволяет читать новый файл perf.data старыми инструментами perf, игнорируя новые необязательные поля.

Значения mmap начинаются с заголовка:

struct perf_event_header {


    __u32   type;


    __u16   misc;


    __u16   size;
};

Далее мы опишем поля perf_event_header более подробно. Для простоты поля с короткими описаниями показаны первыми.

size

Показывает размер записи.

misc

В поле misc содержится дополнительная информация об образце.

По этому значению можно определить режим ЦП, наложив на него маску PERF_RECORD_MISC_CPUMODE_MASK и одно из следующих значений (заметим, что это не битовые маски, можно указывать только одно значение за раз):

type

Значение type — одно из представленных ниже. Значения в соответствующей записи (следующие за заголовком) зависят от выбранного type как описано.

Обработка переполнения¶

Можно задать события, которые будут уведомлять о прохождении порога, указывающие на переполнение. Состояние переполнения можно перехватить, проследив за файловым дескриптором событий с помощью poll(2), select(2) или epoll(7). Или же события переполнения можно перехватить через обработчик сигнала, включив ввод-вывод сигналов о файловом дескрипторе; смотрите описание операций F_SETOWN и F_SETSIG в fcntl(2).

Переполнения генерируются только подсчитывающими событиями (значение sample_period должно быть ненулевым).

Существует два способа генерации уведомлений о переполнении.

Первый: задать значение wakeup_events или wakeup_watermark, которые будут срабатывать после записи определённого количества образцов или байт кольцевой буфер mmap. В этом случае признаком служит POLL_IN.

Второй: использовать ioctl PERF_EVENT_IOC_REFRESH. Данный ioctl добавляется к счётчику, который уменьшается каждый раз при наступлении события переполнения. Если значение не равно 0, то признаком служит POLL_IN, то после того, как счётчик достигнет 0, признаком становится POLL_HUP и определяющее событие отключается.

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

Начиная с Linux 3.18, признак POLL_HUP учитывается, если отслеживаемое событие присоединено к другому процессу и этот процесс существует.

Инструкция rdpmc¶

Начиная с Linux 3.4 на x86, вы можете использовать инструкцию rdpmc для выполнения чтения с низкой задержкой без входа в ядро. Заметим, что использование rdpmc необязательно быстрее других способов чтения значений события.

Возможность использования этого можно определить по полю cap_usr_rdpmc страницы mmap; документацию по вычислению событий значения можно найти в этом разделе.

Сначала, когда поддержка rdpmc была только включена, любой процесс (не только с активным событием perf) мог использовать инструкцию rdpmc для доступа к счётчикам. Начиная с Linux 4.0 поддержка rdpmc разрешена только, если событие в данный момент включено в контексте процесса. Для возвращению к старому поведению запишите значение 2 в /sys/devices/cpu/rdpmc.

Вызовы ioctl perf_event¶

К файловым дескрипторам perf_event_open() допускаются различные вызовы ioctl:

PERF_EVENT_IOC_ENABLE

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

Если в аргументе ioctl установлен бит PERF_IOC_FLAG_GROUP, то включаются все события в группе, даже если указанное событие не лидер группы (но смотрите ДЕФЕКТЫ).

PERF_EVENT_IOC_DISABLE

Отключает определённый счётчик или группу событий, указанный в аргументе файлового дескриптора.

Включение или отключение лидера группы включает или выключает всю группу; то есть пока отключён лидер группы, не считается ни один из счётчиков. Включение или выключение члена группы (не лидера) влияет только на этот счётчик; выключение не лидера останавливает его счётчик и не влияет на другие счётчики.

Если в аргументе ioctl установлен бит PERF_IOC_FLAG_GROUP, то выключаются все события в группе, даже если указанное событие не лидер группы (но смотрите ДЕФЕКТЫ).

PERF_EVENT_IOC_REFRESH

Не унаследованные счётчики переполнения могут использовать это для установки счётчика количества переполнений, после чего он выключается (значение задаётся в аргументе). Последующие вызовы этого ioctl добавляют значение аргумента в текущий счётчик. При каждом переполнении будет возникать уведомление о переполнении с установленным POLL_IN пока счётчик не достигнет 0; когда это произойдёт, посылается уведомление с установленным POLL_HUP и событие выключается. Для значения 0 в аргументе поведение не определено.

PERF_EVENT_IOC_RESET

Сбрасывает (в ноль) счётчик событий, указанный в аргументе файлового дескриптора. Сбрасывается только счётчики; невозможно обнулить мультиплексирующее значение time_enabled или time_running.

Если в аргументе ioctl установлен бит PERF_IOC_FLAG_GROUP, то сбрасываются все события в группе, даже если указанное событие не лидер группы (но смотрите ДЕФЕКТЫ).

PERF_EVENT_IOC_PERIOD

Обновляет период переполнения события.

Начиная с Linux 3.7 (на ARM) и Linux 3.14 (на всех остальных архитектурах), новый период начинает действовать немедленно. В старых ядрах новый период не работает пока не возникнет следующее переполнение.

Аргумент представляет собой указатель на 64-битное значение, содержащее желаемый новый период.

До Linux 2.6.36 данный ioctl всегда завершался с ошибкой из-за дефекта в ядре.

PERF_EVENT_IOC_SET_OUTPUT

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

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

PERF_EVENT_IOC_SET_FILTER (начиная с Linux 2.6.33)

Добавить фильтр ftrace в это событие.

В аргументе указывается указатель на желаемый фильтр ftrace.

PERF_EVENT_IOC_ID (начиная с Linux 3.12)

Возвращает значение идентификатора события для заданного файлового дескриптора события.

Аргументом является указатель на 64-битное беззнаковое целое число, в которое будет сохранён результат.

PERF_EVENT_IOC_SET_BPF (начиная с Linux 4.1)

This allows attaching a Berkeley Packet Filter (BPF) program to an existing kprobe tracepoint event. You need CAP_PERFMON (since Linux 5.8) or CAP_SYS_ADMIN privileges to use this ioctl.

Аргументом является файловый дескриптор программы BPF, который был создан ранее системным вызовом bpf(2).

PERF_EVENT_IOC_PAUSE_OUTPUT (начиная с Linux 4.7)

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

Аргументом является беззнаковое 32-битное целое. Ненулевое значение приостанавливает кольцевой буфер, а нулевое — возобновляет работу кольцевого буфера.

PERF_EVENT_MODIFY_ATTRIBUTES (начиная с Linux 4.17)

Позволяет изменить существующее событие без накладных расходов на закрытие и повторное открытие нового события. В настоящее время поддерживается только для событий точек останова (breakpoint).

В аргументе содержится указатель на структуру perf_event_attr с обновлёнными данными события.

PERF_EVENT_IOC_QUERY_BPF (начиная с Linux 4.16)

This allows querying which Berkeley Packet Filter (BPF) programs are attached to an existing kprobe tracepoint. You can only attach one BPF program per event, but you can have multiple events attached to a tracepoint. Querying this value on one tracepoint event returns the ID of all BPF programs in all events attached to the tracepoint. You need CAP_PERFMON (since Linux 5.8) or CAP_SYS_ADMIN privileges to use this ioctl.

В аргументе содержится указатель на структуру

struct perf_event_query_bpf {


    __u32    ids_len;


    __u32    prog_cnt;


    __u32    ids[0];
};
    

Значение поля ids_len показывает сколько идентификаторов могут поместиться в массив ids. Значение prog_cnt заполняется ядром и показывает количество присоединённых программ BPF. Массив ids заполняется идентификаторами каждой присоединённой программы BPF. Если имеет больше программ, чем влезает в массив, то ядро вернёт ENOSPC и ids_len укажет количество идентификаторов программ, которые были успешно скопированы.

Использование prctl(2)¶

Процесс может включить или выключить все группы, в данный момент, открытых событий (с помощью операций prctl(2) PR_TASK_PERF_EVENTS_ENABLE и PR_TASK_PERF_EVENTS_DISABLE). Это применимо только к событиям созданным локально вызывающим процессом. Это не применимо к событиям, созданным другими процессами, присоединёнными к вызывающему процессу, или к унаследованным от родительского процесса событиям. При этом включаются или выключаются только лидеры групп, а не члены групп.

Файлы настройки perf_event¶

Файлы в /proc/sys/kernel/

Файлы в /sys/bus/event_source/devices/