eBPF с нуля: как это работает и зачем бэкендеру

Программы в ядре Linux на cilium/ebpf (Go) и bpftrace против нагрузки, которая сама знает свой счёт: tracepoint, kprobe, fentry, uprobe и uretprobe считают одно и то же событие — и где Go-программа ломает uprobe; карты под конкуренцией — гонка в hash, per-CPU, потери ring buffer; что verifier принимает и отклоняет на двенадцати программах; CO-RE на поле task_struct, переименованном между версиями ядра

Ещё недавно, чтобы вмешаться в работу ядра Linux — посчитать пакеты, перехватить системный вызов, снять профиль, — приходилось писать модуль ядра: рискованно, непереносимо, одна ошибка роняет машину. eBPF устроен иначе: в ядро загружается небольшая программа, ядро проверяет её до запуска и исполняет на нужном событии — без модуля, без пересборки ядра, без перезагрузки.

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

Статья рассчитана на тех, кто знаком с Linux, процессами и системными вызовами и читает C и Go: «с нуля» здесь — про eBPF, а не про ядро.

Открывающая статья серии «eBPF на практике». Дальше — наблюдаемость через eBPF и eBPF в сети.

Ретрофутуристский инженерный лист: механизм в разрезе — шестерни, валы и центральный барабан. Слева механическая рука опускает оранжевый модуль-датчик к аккуратному проёму в корпусе; перед проёмом стоит рамка проверки с рядом измерительных щупов и горящей зелёной лампой. Внутри механизма уже стоят три таких датчика — на шестерне, на валу и на барабане; от них тонкие провода сходятся в одну коробку, и один кабель выходит наружу к табло с тремя стрелочными приборами

В статье

Стенд

Один контейнер: Go 1.27 и библиотека cilium/ebpf 0.22 — программы на C собирает её генератор bpf2go, загружает и цепляет код на Go без cgo. Рядом clang 19, libbpf 1.5, bpftool 7.5 и bpftrace 0.23. Контейнер привилегированный и делит пространство PID с ядром: программа отбирает события по PID нагрузки. Права на загрузку зависят от типа программы: трассировке нужны CAP_BPF и CAP_PERFMON, сетевым программам — CAP_BPF и CAP_NET_ADMIN; CAP_SYS_ADMIN в ряде проверок их заменяет. Ядро — VM Docker Desktop: Linux 7.0 на aarch64, с BTF.

Нагрузка cmd/load стартует, печатает свой PID и ждёт. Загрузчик в это время загружает программу с этим PID, цепляет её и только потом даёт старт — ни одно событие нагрузки не проходит мимо программы. В конце нагрузка печатает, сколько событий сделала, и это эталон.

Программа в ядре вместо модуля

модуль ядра eBPF-программа
проверка перед запуском нет — ошибка в коде роняет ядро verifier доказывает, что программа завершится и не выйдет за свою память
сборка под конкретную версию ядра один объект на разные ядра (CO-RE и BTF)
загрузка и выгрузка insmod, риск для всей машины системный вызов bpf, программа живёт, пока на неё есть ссылка
что может всё только то, что разрешают точка подключения и помощники ядра

Последняя строка — цена: программа живёт в песочнице, и границы песочницы ниже видны на счёте.

Строка про выгрузку требует уточнения. Загруженная программа, карта и подключение — объекты ядра, которые держатся, пока на них есть ссылка: файловый дескриптор у процесса, link (подключение программы к точке) или закрепление (pinning) в файловой системе bpffs. Загрузчик стенда держит всё дескрипторами — завершился, и программа исчезла. Но программа, закреплённая в bpffs, переживает свой загрузчик: так работают Cilium и другие агенты, которые обновляются без разрыва сетевого пути.

От исходника до события путь такой:

flowchart LR C["программа на C"] -->|"clang"| ELF["ELF-объект
байт-код и BTF"] ELF -->|"загрузчик
cilium/ebpf"| V["verifier"] V -->|"принята"| JIT["JIT
в машинный код"] JIT --> L["подключение
к точке"] L --> E["событие в ядре"] E --> P["программа"] P --> M["карта"] M -->|"чтение"| U["пользовательская
программа"]

flowchart LR
    C["программа на C"] -->|"clang"| ELF["ELF-объект
байт-код и BTF"] ELF -->|"загрузчик
cilium/ebpf"| V["verifier"] V -->|"принята"| JIT["JIT
в машинный код"] JIT --> L["подключение
к точке"] L --> E["событие в ядре"] E --> P["программа"] P --> M["карта"] M -->|"чтение"| U["пользовательская
программа"]

На стенде весь путь — одна команда: python3 scripts/run-hooks.py tracepoint собирает программу, загружает её, запускает нагрузку и сверяет счёт.

Куда цепляется программа

Программа срабатывает на событии ядра или процесса. Точки разные по стабильности и цене:

  • tracepoint — точка трассировки, которую ядро объявило само: обычно меньше зависит от деталей реализации, чем kprobe, но в стабильный ABI ядра не входит (BPF Design Q&A);
  • kprobe — вход в любую функцию ядра: гибко, но функцию могут переименовать или встроить;
  • fentry — то же, но через трамплин с типизированными аргументами по BTF: дешевле kprobe;
  • uprobe / uretprobe — вход и выход функции в программе пользователя.

Постановка. Одна программа на всех точках — прибавить 1, если событие пришло от нагрузки:

// bpf/hooks.c
static __always_inline int hit(__u32 slot)
{
	if ((bpf_get_current_pid_tgid() >> 32) != target_tgid)
		return 0;
	__u64 *v = bpf_map_lookup_elem(&counts, &slot);
	if (v)
		__sync_fetch_and_add(v, 1);
	return 0;
}
точка подключения событие нагрузки событий насчитано
tracepoint syscalls:sys_enter_openat открытие файла 10000 10000
kprobe do_sys_openat2 открытие файла 10000 10000
fentry do_sys_openat2 открытие файла 10000 10000
uprobe main.targetFunc вызов листовой Go-функции 10000 10000
uretprobe main.targetFunc вызов листовой Go-функции 10000 10000
uprobe main.targetGrow вызов функции, растящей стек 10000 по 2 на вызов
uretprobe main.targetGrow вызов функции, растящей стек 10000 нагрузка упала

Контроль сошёлся: tracepoint насчитал ровно столько открытий, сколько сделала нагрузка.

Точки ядра совпали с нагрузкой все три. uprobe и uretprobe на простой Go-функции — тоже. Две последние строки — особенность Go, о которой знают по падениям в проде:

$ python3 scripts/run-hooks.py uprobe-grow
{"variant": "uprobe-grow", "outcome": "mismatch", "detail": "нагрузка 10000, насчитано 20000 — по 2 срабатывания на вызов"}
$ python3 scripts/run-hooks.py uretprobe-grow
{"variant": "uretprobe-grow", "outcome": "mismatch", "detail": "нагрузка упала (exit status 2): runtime: unexpected return pc for main.targetGrow called from 0xfffffffff000; насчитано 0"}

Функция targetGrow держит в кадре 12 КБ — больше начального стека горутины (2 КБ, stackMin в рантайме Go). Нагрузка запускается с GODEBUG=adaptivestackstart=0: иначе рантайм со временем начнёт давать новым горутинам стек побольше, и рост в прологе станет редким:

// cmd/load/main.go
func targetGrow(i int) int {
	var pad [12288]byte
	pad[i%len(pad)] = byte(i)
	return int(pad[(i*7)%len(pad)]) + i
}

Пролог любой Go-функции сравнивает указатель стека с границей. Если места не хватает, функция уходит в runtime.morestack: рантайм выделяет стек побольше, копирует в него старый и выполняет функцию с первой инструкции заново. uprobe стоит на первой инструкции — и срабатывает дважды. Изредка выходит и третий раз; правдоподобная причина — вытеснение горутины, которое идёт через ту же проверку в прологе, — поэтому стенд публикует число срабатываний на вызов, а не точный счёт.

uretprobe ломается хуже. Чтобы поймать выход, ядро подменяет адрес возврата на свой трамплин. Рантайм Go, копируя стек, проходит по адресам возврата и находит там адрес, которого нет ни в одной Go-функции, — и аварийно завершает программу. Поэтому инструменты, которые трассируют Go, вместо uretprobe ставят uprobe на инструкции возврата функции.

Карты: как данные покидают ядро

Программа не возвращает данные наружу напрямую. Она пишет в карту — структуру в ядре, которую читает пользовательская программа: hash, массив, per-CPU-варианты, где у каждого процессора своя ячейка, ring buffer для потока событий.

Постановка. Миллион вызовов getppid из восьми потоков, закреплённых за разными процессорами. Одна программа на tracepoint sys_enter_getppid, разные карты:

// bpf/maps.c
int hash_racy(void *ctx)
{
	__u32 k = 0;
	if (!mine())
		return 0;
	__u64 *v = bpf_map_lookup_elem(&hash_counts, &k);
	if (v)
		*v = *v + 1;
	return 0;
}
карта событий насчитано потеряно
hash, прочитать-прибавить-записать 1000000 326234 673766
hash, __sync_fetch_and_add 1000000 1000000 0
per-CPU массив, сумма по CPU 1000000 1000000 0
ring buffer 4 КБ, чтение после 1000000 255 999745
ring buffer 4 КБ, чтение во время 1000000 768781 231219
ring buffer 32 МБ 1000000 1000000 0

Контроль сошёлся: per-CPU массив насчитал ровно миллион; во всех вариантах ring buffer «получено + отказов» равно нагрузке.

Программы на восьми процессорах работают одновременно, и *v = *v + 1 — это чтение, сложение и запись: два процессора читают одно значение, оба записывают своё плюс один, одно прибавление пропадает. В прогоне из таблицы потеряно больше половины; в пробах стенда потери были от половины до двух третей — величина гонки от прогона к прогону своя. Атомарный __sync_fetch_and_add и per-CPU массив, который суммируют уже в пользовательской программе, дают ровно эталон. Per-CPU к тому же не платит за синхронизацию процессоров.

Ring buffer теряет иначе — честно:

$ python3 scripts/run-maps.py ring-small
{"variant": "ring-small", "outcome": "mismatch", "detail": "нагрузка 1000000, насчитано 255, потеряно 999745; отказов reserve 999745, получено + отказов = нагрузке"}
$ python3 scripts/run-maps.py ring-read
{"variant": "ring-read", "outcome": "mismatch", "detail": "нагрузка 1000000, насчитано 768781, потеряно 231219; отказов reserve 231219, получено + отказов = нагрузке"}

Запись в буфер — bpf_ringbuf_reserve, и если места нет, программа получает отказ. В буфер 4 КБ помещается 256 записей по 16 байт (8 байт события и 8 байт заголовка); без чтения во время нагрузки дошло 255 событий, остальное — отказы. Чтение на лету спасает часть, но не всё: читатель в пользовательском пространстве медленнее восьми процессоров. Важное здесь — что программа считает свои отказы: потери видны, а не молчат, как в гонке.

Verifier: что ядро не загрузит

Перед загрузкой ядро проверяет программу статически: проходит по всем путям исполнения и доказывает, что программа завершится, не прочитает чужую память и не разыменует то, что может оказаться NULL. Не доказало — не загрузит.

Постановка. Двенадцать маленьких программ, у каждой в первой строке — ожидаемый вердикт, записанный до запуска. Загрузчик компилирует программу, пробует загрузить и записывает, кто отказал — clang или verifier — и почему.

программа что в ней гипотеза итог
ok указатель из карты проверен на NULL (контроль) примет принята
null_deref указатель из array-карты без проверки на NULL отклонит принята
null_deref_hash указатель из hash-карты без проверки на NULL отклонит отклонена verifier
loop_bounded цикл до 100 примет принята
loop_collapsed цикл до значения из карты, тело — *v += 1 отклонит принята
loop_unbounded цикл до значения из карты, в теле вызов помощника отклонит отклонена verifier
bpf_loop тот же цикл (граница и тело) через bpf_loop примет принята
packet_oob байт пакета без проверки data_end отклонит отклонена verifier
packet_checked байт пакета после проверки data_end примет принята
stack_uninit ключ карты на стеке не инициализирован отклонит принята
stack_big буфер 600 байт на стеке не скомпилирует отклонена clang
gpl_helper GPL-помощник в программе с лицензией Proprietary отклонит отклонена verifier

Контроль сошёлся: заведомо корректная программа принята.

Девять вердиктов совпали с ожиданием, три — нет, и эти три полезнее остальных.

$ python3 scripts/run-verifier.py null_deref
{"variant": "null_deref", "outcome": "mismatch", "detail": "принята"}
$ python3 scripts/run-verifier.py null_deref_hash
{"variant": "null_deref_hash", "outcome": "match", "detail": "отклонена verifier: R0 invalid mem access 'map_value_or_null'"}

Указатель из array-карты без проверки на NULL verifier принял: ключ — константа внутри границ массива, и verifier сам знает, что поиск вернёт ячейку. Тот же код на hash-карте отклонён: там ключа может не быть. Правило «всегда проверяй на NULL» остаётся правильным — но verifier проверяет не правило, а то, что может случиться на самом деле.

$ python3 scripts/run-verifier.py loop_collapsed
{"variant": "loop_collapsed", "outcome": "mismatch", "detail": "принята"}
$ python3 scripts/run-verifier.py loop_unbounded
{"variant": "loop_unbounded", "outcome": "match", "detail": "отклонена verifier: BPF program is too large. Processed 1000001 insn"}

Цикл «прибавить единицу столько раз, сколько записано в карте» verifier принял, потому что цикла не было: clang заменил его одной инструкцией — сдвигом влево, удвоением. Verifier проверяет байт-код после оптимизаций компилятора, а не исходник. Цикл, который свернуть нельзя (в теле вызов помощника), отклонён: verifier исчерпал бюджет проверки — миллион инструкций — и не доказал, что цикл кончится. Это не доказательство бесконечности: verifier отказывает, когда не смог доказать завершение за отведённый бюджет. Для итераций с границей из данных есть помощник bpf_loop: тот же цикл — та же граница из карты, ограниченная сверху одним и тем же LOOP_MAX = 2²⁰, и то же тело — через него принят, потому что число итераций теперь аргумент помощника, а тело — отдельная функция, которую verifier проверяет один раз.

«Принята» — ещё не «работает». У bpf_loop аргумент — 32-битное число итераций, и больше 2²³ помощник откажет при вызове, вернув ошибку; программа, которая не проверяет возврат, тихо опубликует пустой результат. Поэтому граница приводится к LOOP_MAX до сужения типа, код возврата проверяется, и при ошибке результат не записывается. Загрузчик стенда исполняет принятую программу:

$ python3 scripts/run-verifier.py bpf_loop
{"variant": "bpf_loop", "outcome": "match", "detail": "принята; исполнение: n = 100000, итераций 100000, bpf_loop вернул 100000"}

Заданные 100 000 итераций выполнены все, и помощник вернул то же число.

Третье расхождение — чтение неинициализированного ключа на стеке: принято, потому что загрузчик привилегированный. Программам с CAP_BPF и CAP_PERFMON ядро разрешает такое чтение; для непривилегированной загрузки это отказ. Остальное — как ожидалось: чтение пакета без проверки границы, вызов GPL-помощника из программы с другой лицензией. Буфер в 600 байт на стеке до verifier не дошёл: clang отказался компилировать — предел стека eBPF-программы 512 байт.

CO-RE: одна программа на разных ядрах

Программа, которая читает структуру ядра, обращается к полю по смещению. Между версиями ядра поля переставляют, добавляют и переименовывают — смещение, зашитое при компиляции, на другом ядре читает не то. CO-RE (compile once, run everywhere) решает это так: компилятор записывает не смещение, а «поле pid структуры task_struct», а загрузчик при загрузке находит смещение в BTF — описании типов, которое ядро носит с собой.

Постановка. В ядре 5.14 поле task_struct->state переименовали в __state. Программа читает состояние текущей задачи тремя способами: контроль — tgid через CO-RE против PID нагрузки; переносимо — проверить, какое поле есть, при загрузке; как под старые ядра — читать state без проверки.

// bpf/core.c
	if (bpf_core_field_exists(((struct task_struct___old *)t)->state)) {
		put(SLOT_STATE, BPF_CORE_READ((struct task_struct___old *)t, state));
		put(SLOT_BRANCH, 0);
	} else {
		put(SLOT_STATE, BPF_CORE_READ(t, __state));
		put(SLOT_BRANCH, 1);
	}

Контроль сошёлся: tgid, прочитанный через CO-RE, совпал с PID нагрузки.

$ python3 scripts/run-core.py guarded
{"variant": "guarded", "outcome": "match", "detail": "ветка __state, прочитано 0, эталон 0 (TASK_RUNNING)"}
$ python3 scripts/run-core.py old
{"variant": "old", "outcome": "mismatch", "detail": "не загрузилась: bad CO-RE relocation: invalid func unknown#195896080"}

bpf_core_field_exists вычисляется при загрузке: в этом ядре поля state нет, ветка выбрала __state и прочитала 0 — задача выполняется, как и должна, раз программа работает в её контексте. Программа под старые ядра не загрузилась: релокация не нашла поле, cilium/ebpf заменил инструкцию вызовом несуществующей функции, и verifier отказал. Это лучше, чем тихо прочитать мусор по старому смещению, — но работает, только если программа собрана с CO-RE. Ядро в стенде одно, поэтому переносимость показана на переименованном поле, а не на втором ядре.

Чем писать

  • bpftrace — язык однострочников поверх libbpf: зонд, фильтр, действие. Для диагностики «посмотреть прямо сейчас».
  • bcc — Python-обёртки и набор готовых утилит; компилирует программы на машине, где запускает, — нужны заголовки ядра и clang рядом.
  • libbpf — библиотека на C, эталон для CO-RE.
  • cilium/ebpf — чистый Go: загрузка, карты, точки подключения, генератор bpf2go, который встраивает объект программы в Go-бинарь. Для сервиса, который несёт eBPF-логику внутри.

Постановка. Те же события — однострочниками bpftrace:

программа bpftrace событий насчитано
tracepoint:syscalls:sys_enter_openat /pid == PID/ { @n = count(); } 10000 10000
tracepoint:syscalls:sys_enter_getppid /pid == PID/ { @n = count(); } 1000000 1000000
uprobe:/opt/stand/bin/load:main.targetFunc /pid == PID/ { @n = count(); } 10000 10000

Контроль сошёлся: открытий файла bpftrace насчитал ровно столько, сколько сделала нагрузка.

Однострочник bpftrace насчитал ровно миллион и там, где наивный hash терял события: count() в bpftrace хранит счёт в per-CPU карте. Разница между инструментами — не в точности, а в том, где живёт программа: bpftrace — для человека у терминала, cilium/ebpf — для кода, который соберут, проверят и выкатят вместе с сервисом.

Как выбирать

что на стенде что делать
точка подключения tracepoint, kprobe, fentry — ровно эталон tracepoint, если есть; fentry вместо kprobe на ядрах с BTF
uprobe на Go функция, растящая стек, — два срабатывания на вызов считать вызовы не на входе, а по другому признаку; или уметь вычитать повтор
uretprobe на Go рост стека роняет программу uprobe на инструкциях возврата вместо uretprobe
счётчик из нескольких CPU неатомарный инкремент теряет события, сколько — от прогона к прогону своё per-CPU карта или атомарная операция
поток событий ring buffer теряет при переполнении размер под всплеск и счётчик отказов
verifier проверяет байт-код после компилятора и права загрузчика проверять программу загрузкой, а не чтением исходника
переносимость поле, переименованное в 5.14, ломает загрузку без проверки CO-RE и bpf_core_field_exists для полей, которые менялись
инструмент bpftrace и cilium/ebpf точны одинаково bpftrace — диагностика, cilium/ebpf — код в сервисе

Чего эти результаты не значат

  • Одно ядро. Переносимость CO-RE показана на переименованном поле, а не на втором ядре.
  • Ловушки Go зависят от версий ядра и Go. Двойной uprobe воспроизведён на функции, которая растит стек при каждом вызове; в обычном коде это случается реже — и потому незаметнее.
  • Привилегированный загрузчик. Часть вердиктов verifier зависит от прав: непривилегированная загрузка строже.
  • Время не мерилось — только счёт. Цена программ — тема статьи про наблюдаемость.
  • Версии: Go 1.27.1, cilium/ebpf 0.22.0, clang 19, libbpf 1.5.0, bpftool 7.5.0, bpftrace 0.23.2, ядро 7.0.12-linuxkit, aarch64.

Ссылки

Обсуждение в Telegram

Присоединиться →