-B MODE

تنظیم حالت بافر خروجی (قابل اعمال بر خروجی ترمینال و فایل -o).

مقادیر معتبر عبارتند از:

-c COMMAND

اجرای COMMAND به عنوان یک فرآیند فرزند. هنگامی که فرزند خاتمه یابد bpftrace نیز متوقف خواهد شد، گویی 'exit()' فراخوانی شده باشد. اگر bpftrace پیش از فرآیند فرزند خاتمه یابد، فرآیند فرزند با یک سیگنال SIGTERM متوقف خواهد شد. در صورت استفاده، پروب‌های 'USDT' تنها به فرآیند فرزند متصل خواهند شد. برای جلوگیری از شرایط رقابتی (race condition) در زمان استفاده از 'USDTs'، فرآیند فرزند پس از 'execve' با استفاده از 'ptrace(2)' متوقف شده و پس از اتصال تمام پروب‌های 'USDT' به کار خود ادامه می‌دهد. فرآیند فرزند با همان مجوزهای خود bpftrace (معمولاً کاربر ریشه root) اجرا می‌شود.

مگر در مواردی که مشخص شده باشد، bpftrace هیچ فیلترگذاری ضمنی انجام نمی‌دهد. بنابراین، اگر فقط به رویدادهای درون COMMAND علاقه‌مند هستید، ممکن است بخواهید بر اساس PID فرآیند فرزند فیلتر کنید. مقدار PID فرزند از طریق متغیر توکار 'cpid' در دسترس برنامه‌ها قرار دارد. به عنوان مثال، می‌توانید گزاره فیلتر /pid == cpid/ را به پروب‌های دارای بافت فضای کاربری اضافه کنید.

-d STAGE

فعال‌سازی حالت اشکال‌زدایی (دیباگ). برای جزئیات بیشتر به بخش «گزینه‌های تفصیلی» (Debug Output) مراجعه کنید.

--debuginfo DIR[:DIR]

افزودن دایرکتوری DIR به مسیر جستجو برای اطلاعات اشکال‌زدایی DWARF. مسیرها می‌توانند مطلق یا نسبی نسبت به مکان باینری ردیابی‌شده باشند. مسیرهای چندگانه را می‌توان با جدا کردن آن‌ها با دونقطه (:) یا با تکرار این گزینه مشخص کرد؛ به عنوان مثال --debuginfo=/bin/debug:./lib/debug:.. و --debuginfo=/bin/debug --debuginfo=./lib/debug به ترتیب. فایل‌های اشکال‌زدایی در این مسیرها در صورت در دسترس بودن بر اساس شناسه ساخت (build ID) تطبیق داده می‌شوند؛ برای فعال کردن اعتبارسنجی CRC32 در صورت نیاز، پیشوند + را به مسیر اضافه کنید. فایل‌هایی که تطبیق ندارند نادیده گرفته می‌شوند. به طور پیش‌فرض، bpftrace مسیرهای استاندارد اشکال‌زدایی را جستجو می‌کند، از جمله .debug به صورت نسبی نسبت به باینری ردیابی‌شده و /usr/lib/debug؛ همچنین ممکن است از سرورهای debuginfod در دسترس نیز استعلام بگیرد.

فرمت اشکال‌زدایی تفکیک‌شده (.dwo، .dwp) هنوز برای این گزینه پشتیبانی نمی‌شود، اما همچنان با مسیر پیش‌فرض باینری پروب کار می‌کند.

--dry-run

خاتمه دادن به اجرا بلافاصله پس از اتصال تمام پروب‌ها. برای آزمایش این که اسکریپت می‌تواند بدون اجرای واقعی، تجزیه، بارگذاری و متصل شود بسیار مفید است.

-e PROGRAM

اجرای PROGRAM به جای خواندن برنامه از یک فایل یا ورودی استاندارد (stdin).

-f FORMAT

تنظیم قالب خروجی.

مقادیر معتبر عبارتند از:

خروجی JSON با NDJSON و JSON Lines سازگار است، به این معنی که هر خط از خروجی جریانی یک بلوک داده مجزا از JSON معتبر است.

--fmt FILENAME

چاپ قالب استاندارد برای فایل bpftrace با نام FILENAME.

-h, --help

چاپ خلاصه راهنما.

-I DIR

افزودن دایرکتوری DIR به مسیر جستجوی هدرهای C. این گزینه می‌تواند چندین بار استفاده شود. برای جزئیات بیشتر به بخش «گزینه‌های پیش‌پردازنده» مراجعه کنید.

--include FILENAME

افزودن FILENAME به عنوان یک include برای پیش‌پردازنده. این کار معادل قرار دادن '#include FILENAME' در بالای برنامه است. این گزینه می‌تواند چندین بار استفاده شود. برای جزئیات بیشتر به بخش «گزینه‌های پیش‌پردازنده» مراجعه کنید.

--info

چاپ اطلاعات تفصیلی درباره قابلیت‌های پشتیبانی‌شده توسط هسته و نسخه ساخت bpftrace.

-k

این فلگ هشدارهای زمان اجرا را برای خطاهای ناشی از توابع کمکی BPF مربوط به 'probe_read_*' و جستجوی نگاشت (map lookup) فعال می‌کند. هنگام وقوع خطا، bpftrace خطایی حاوی مکان در کد مبدا و کد خطا را ثبت خواهد کرد:

stdin:48-57: WARNING: Failed to probe_read_user_str: Bad address (-14)
u:lib.so:"fn(char const*)" { printf("arg0:%s\n", str(arg0));}
                                                 ~~~~~~~~~

-l [SEARCH|FILENAME]

فهرست کردن تمام پروب‌هایی که با الگوی SEARCH مطابقت دارند. اگر الگو حذف شود، تمام پروب‌ها فهرست می‌شوند. این الگو به همان شیوه پروب‌ها از نویسه‌های عام (wildcard) پشتیبانی می‌کند. به عنوان مثال، '-l kprobe:*file*' تمام پروب‌های 'kprobes' با عبارت 'file' در نام را فهرست می‌کند. این گزینه می‌تواند به همراه یک برنامه استفاده شود که تمام پروب‌های موجود در آن برنامه را فهرست می‌کند. برای جزئیات بیشتر به بخش «فهرست کردن پروب‌ها» مراجعه کنید.

--no-feature feature,feature,...

غیرفعال کردن استفاده از قابلیت‌های شناسایی‌شده، مقادیر معتبر عبارتند از:

--no-warnings

نادیده گرفتن تمام پیام‌های هشدار ایجاد شده توسط bpftrace.

--probe-filter REGEX

اتصال و اجرای تنها پروب‌هایی که نام آن‌ها با عبارت باقاعده REGEX مطابقت دارد. پروب‌هایی که مطابقت ندارند در هسته بارگذاری نمی‌شوند. پروب‌های ویژه (BEGIN و END) تحت تأثیر این فیلتر قرار نمی‌گیرند. اگر هیچ پروبی مطابقت نداشته باشد، bpftrace با یک خطا خارج می‌شود.

--traceable-functions FILENAME

مشخص کردن فایل حاوی فهرست توابع هسته با قابلیت ردیابی. اگر تعیین نشود، دستور bpftrace از مسیر /sys/kernel/tracing/available_filter_functions استفاده می‌کند که به ftrace پویا وابسته است. قالب آن مشابه available_filter_functions است: هر خط یا "symbol" است یا "symbol [module]".

-o FILENAME

نوشتن خروجی ردیابی bpftrace در FILENAME به جای خروجی استاندارد (stdout). این خروجی شامل خروجی فرآیند فرزند (گزینه -c) نمی‌شود. خطاها همچنان در خروجی خطای استاندارد (stderr) نوشته می‌شوند.

-p PID

اتصال به فرآیند با شناسه PID یا فیلتر کردن اقدامات بر اساس آن. اگر فرآیند خاتمه یابد، bpftrace نیز خاتمه می‌یابد. هنگام استفاده از پروب‌های USDT، uprobes، uretprobes، سخت‌افزاری (hardware)، نرم‌افزاری (software)، profile، interval یا watchpoint، آن‌ها فقط به این فرآیند متصل خواهند شد. برای همه پروب‌های دیگر، به جز begin/end، مقدار pid مانند یک گزاره فیلتر عمل می‌کند تا رویدادهایی که از آن pid نیستند فیلتر شوند. برای فهرست کردن uprobes/uretprobes، هدف را به '*' تنظیم کنید تا فضای آدرس فرآیند برای یافتن نمادها جستجو شود.

-q

حالت بی‌صدا (جلوگیری از چاپ پیام‌های اضافی).

--unsafe

برخی فراخوانی‌ها، مانند 'system'، به دلیل احتمال ایجاد عوارض جانبی خطرناک ('system("rm -rf")') به عنوان ناامن علامت‌گذاری شده و به طور پیش‌فرض غیرفعال هستند. این فلگ اجازه استفاده از آن‌ها را می‌دهد.

علاوه بر این، سخت‌گیری بررسی‌های kprobe/kretprobe را کاهش می‌دهد. این گزینه می‌تواند برای پروب کردن توابعی که bpftrace آن‌ها را غیرقابل ردیابی گزارش می‌کند به کار رود، اما در صورتی که هسته برای مجاز دانستن پروب توابع notrace پیکربندی شده باشد، پشتیبانی می‌شوند.

--usdt-file-activation

فعال‌سازی سمافورهای usdt بر اساس مسیر فایل.

-V, --version

چاپ اطلاعات نسخه bpftrace.

-v

فعال‌سازی پیام‌های مشروح (verbose). برای جزئیات بیشتر به بخش «خروجی مشروح» مراجعه کنید.

گزینه‌های برنامه (Program Options)

شما همچنین می‌توانید گزینه‌های سفارشی را از طریق پارامترهای مکانی یا نام‌دار به خود برنامه یا اسکریپت bpftrace ارسال کنید. پارامترهای مکانی می‌توانند قبل یا بعد از خط تیره دوگانه (--) قرار گیرند، اما پارامترهای نام‌دار تنها می‌توانند بعد از خط تیره دوگانه بیایند؛ مانند:

# bpftrace -e 'begin { print(($1, $2, getopt("aa", 1), getopt("bb"))); }' p1 -- --aa=20 --bb p2
// (p1, p2, 20, true) is printed

یا

# bpftrace myscript.bt -- p1 --aa=20 --bb p2

در این مثال‌ها دو پارامتر مکانی (p1، p2) و دو پارامتر نام‌دار (aa که روی 20 تنظیم شده، و bb که روی true تنظیم شده) وجود دارد. پارامترهای نام‌دار برنامه برای تعیین مقدار خود به علامت = نیاز دارند، مگر اینکه از نوع بولی باشند (مانند 'bb' در بالا). درباره نحوه دسترسی به پارامترهای مکانی و نام‌دار در اینجا https://github.com/bpftrace/bpftrace/blob/master/docs/language.md#command-line-parameters بخوانید.

متغیرهای پیکربندی (Config Variables)

برخی رفتارها فقط از طریق متغیرهای پیکربندی قابل کنترل هستند که در اینجا در دسترس هستند https://github.com/bpftrace/bpftrace/blob/master/docs/language.md#config-variables. این متغیرها را می‌توان مستقیماً در اسکریپت (پیش از هر پروب) از طریق بلوک پیکربندی، یا از طریق متغیر محیطی معادل آن‌ها تنظیم کرد که با حروف بزرگ و پیشوند BPFTRACE_ هستند؛ برای مثال متغیر محیطی stack_mode برابر با BPFTRACE_STACK_MODE خواهد بود.

متغیرهای محیطی (Environment Variables)

این متغیرها بخشی از مجموعه استاندارد متغیرهای پیکربندی بالا نیستند و فقط می‌توان آن‌ها را به عنوان متغیرهای محیطی تنظیم کرد.

BPFTRACE_BTF

پیش‌فرض: None

مسیر فایل BTF. به طور پیش‌فرض، bpftrace چندین مکان را برای یافتن فایل BTF جستجو می‌کند. برای جزئیات بیشتر به src/btf.cpp مراجعه کنید.

BPFTRACE_KERNEL_BUILD

پیش‌فرض: /lib/modules/$(uname -r)

فقط با BPFTRACE_KERNEL_SOURCE استفاده می‌شود در صورتی که ساخت هسته لینوکس خارج از درخت منبع (out-of-tree) باشد.

BPFTRACE_KERNEL_SOURCE

پیش‌فرض: /lib/modules/$(uname -r)

دستور bpftrace برای برخی قابلیت‌ها به هدرهای هسته نیاز دارد که در این دایرکتوری جستجو می‌شوند.

BPFTRACE_VMLINUX

پیش‌فرض: None

این متغیر مسیر vmlinux مورد استفاده برای تفکیک نمادهای هسته هنگام اتصال kprobe به یک آفست را مشخص می‌کند. اگر این مقدار داده نشود، bpftrace مسیر vmlinux را از مکان‌های از پیش تعریف‌شده جستجو می‌کند. برای جزئیات بیشتر به src/attached_probe.cpp:find_vmlinux() مراجعه کنید.

BPFTRACE_COLOR

پیش‌فرض: auto

رنگی‌سازی خروجی لاگ bpftrace. مقادیر معتبر auto، always و never هستند.

خروجی اشکال‌زدایی (Debug Output)

گزینه -d STAGE خروجی اشکال‌زدایی تولید می‌کند. این گزینه خروجی مرحله اجرای bpftrace مشخص‌شده توسط آرگومان STAGE را چاپ می‌کند. این گزینه می‌تواند چندین بار (با نام مراحل مختلف) استفاده شود و مقدار ویژه all خروجی تمام مراحل پشتیبانی‌شده را چاپ می‌کند. این گزینه همچنین می‌تواند چند مرحله را در یک بار فراخوانی با مقادیر جدا شده با کاما دریافت کند.

توجه: این قابلیت در درجه اول برای توسعه‌دهندگان bpftrace استفاده می‌شود.

گزینه‌های پشتیبانی‌شده عبارتند از:

فهرست کردن پروب‌ها (Listing Probes)

فهرست کردن پروب‌ها روشی برای کشف پروب‌های پشتیبانی‌شده در سیستم فعلی است. فهرست‌کردن از همان نحو اتصال معمولی پشتیبانی می‌کند و همچنین می‌تواند با -e یا آرگومان‌های نام فایل ترکیب شود تا تمام پروب‌هایی را که یک برنامه به آن‌ها متصل می‌شود مشاهده کرد.

# bpftrace -l 'kprobe:*'
# bpftrace -l 't:syscalls:*openat*
# bpftrace -l 'kprobe:tcp*,trace
# bpftrace -l 'k:*socket*,tracepoint:syscalls:*tcp*'
# bpftrace -l -e 'tracepoint:xdp:mem_* { exit(); }'
# bpftrace -l my_script.bt
# bpftrace -lv 'enum cpu_usage_stat'

فلگ پرجزئیات (-v) می‌تواند برای بررسی آرگومان‌ها (args) در ارائه‌دهندگانی که از آن پشتیبانی می‌کنند مشخص شود:

# bpftrace -l 'fexit:tcp_reset,tracepoint:syscalls:sys_enter_openat' -v
fexit:tcp_reset
    struct sock * sk
    struct sk_buff * skb
tracepoint:syscalls:sys_enter_openat
    int __syscall_nr
    int dfd
    const char * filename
    int flags
    umode_t mode
# bpftrace -l 'uprobe:/bin/bash:rl_set_prompt' -v    # works only if /bin/bash has DWARF
uprobe:/bin/bash:rl_set_prompt
    const char *prompt
# bpftrace -lv 'struct css_task_iter'
struct css_task_iter {
        struct cgroup_subsys *ss;
        unsigned int flags;
        struct list_head *cset_pos;
        struct list_head *cset_head;
        struct list_head *tcset_pos;
        struct list_head *tcset_head;
        struct list_head *task_pos;
        struct list_head *cur_tasks_head;
        struct css_set *cur_cset;
        struct css_set *cur_dcset;
        struct task_struct *cur_task;
        struct list_head iters_node;
};

گزینه‌های پیش‌پردازنده (Preprocessor Options)

گزینه -I می‌تواند برای افزودن دایرکتوری‌ها به فهرست دایرکتوری‌هایی که bpftrace برای جستجوی هدرها استفاده می‌کند به کار رود. می‌تواند چندین بار تعریف شود.

# cat program.bt
#include <foo.h>
begin { @ = FOO }
# bpftrace program.bt
definitions.h:1:10: fatal error: 'foo.h' file not found
# /tmp/include
foo.h
# bpftrace -I /tmp/include program.bt
Attached 1 probe

گزینه --include می‌تواند برای گنجاندن هدرها به صورت پیش‌فرض استفاده شود. می‌تواند چندین بار تعریف شود. هدرها به همان ترتیبی که تعریف شده‌اند اضافه می‌شوند، و قبل از هر include دیگری در برنامه در حال اجرا اضافه خواهند شد.

# bpftrace --include linux/path.h --include linux/dcache.h \
    -e 'kprobe:vfs_open { printf("open path: %s\n", str(((struct path *)arg0).dentry.d_name.name)); }'
Attached 1 probe
open path: .com.google.Chrome.ASsbu2
open path: .com.google.Chrome.gimc10
open path: .com.google.Chrome.R1234s

خروجی مشروح (Verbose Output)

گزینه -v اطلاعات بیشتری درباره برنامه هنگام اجرای آن چاپ می‌کند:

# bpftrace -v -e 'tracepoint:syscalls:sys_enter_nanosleep { printf("%s is sleeping.\n", comm); }'
AST node count: 7
Attached 1 probe
load tracepoint:syscalls:sys_enter_nanosleep, with BTF, with func_infos: Success
Program ID: 111
Attaching tracepoint:syscalls:sys_enter_nanosleep
iscsid is sleeping.
iscsid is sleeping.
[...]