TRACE-CMD-RECORD(1) libtracefs Manual TRACE-CMD-RECORD(1)

trace-cmd-record - ضبط ردگیری از ردیاب داخلی لینوکس Ftrace

trace-cmd record [OPTIONS] [command]

دستور trace-cmd(1) record ردیاب هستهٔ لینوکس Ftrace را برای ضبط افزونه‌ها یا رویدادهای مشخص‌شده‌ای که در حین اجرای command رخ می‌دهند، تنظیم می‌کند. اگر دستوری مشخص نشود، ضبط تا زمانی که کاربر کلیدهای Ctrl-C را بزند ادامه خواهد یافت.

دستور record از ابزار trace-cmd ردیاب Ftrace را برای شروع ردگیری رویدادها یا افزونه‌های گوناگونی که در خط فرمان تعیین شده‌اند، پیکربندی می‌کند. سپس تعدادی فرآیند ردگیری (یکی به ازای هر CPU) ایجاد می‌کند که ضبط داده‌ها را مستقیماً از بافر حلقوی هسته درون فایل‌های موقت آغاز می‌نمایند. پس از تکمیل دستور (یا فشرده شدن کلیدهای Ctrl-C)، تمام فایل‌ها درون یک فایل trace.dat ترکیب می‌شوند که بعداً قابل خواندن خواهد بود (به trace-cmd-report(1) مراجعه کنید).

-p tracer

یک ردیاب (tracer) را مشخص می‌کند. ردیاب‌ها معمولاً کارهایی فراتر از صرفاً ردگیری یک رویداد انجام می‌دهند. ردیاب‌های متداول عبارتند از: function، function_graph، preemptirqsoff، irqsoff، preemptoff و wakeup. ردیاب باید توسط هستهٔ در حال اجرا پشتیبانی شود. برای مشاهدهٔ فهرستی از ردیاب‌های موجود، به trace-cmd-list(1) مراجعه کنید.

-e event

رویدادی را برای ردگیری تعیین می‌کند. نقاط ردگیری ایستای (static trace points) متعددی به هستهٔ لینوکس اضافه شده‌اند. این نقاط بر اساس زیرسیستم گروه‌بندی شده‌اند و می‌توانید تمام رویدادهای یک زیرسیستم داده‌شده را فعال کنید یا رویدادهای خاصی را برای فعال شدن مشخص نمایید. event دارای قالب "subsystem:event-name" است. شما همچنین می‌توانید صرفاً زیرسیستم را بدون :event-name یا نام رویداد را بدون "subsystem:" مشخص کنید. استفاده از «-e sched_switch» رویداد "sched_switch" را فعال می‌کند، در حالی که «-e sched» تمام رویدادهای زیرسیستم "sched" را فعال خواهد کرد.
مقدار 'event' همچنین می‌تواند حاوی الگوهای عمومی (glob expressions) باشد؛ بدین معنا که "*stat*" تمام
رویدادها (یا زیرسیستم‌هایی) را که عبارت "stat" در نامشان وجود دارد انتخاب
خواهد کرد.
کلیدواژهٔ 'all' می‌تواند برای فعال‌سازی همهٔ رویدادها استفاده شود.

-a

هر رویدادی که در حال ضبط است، فایل قالب خروجی‌اش درون فایل خروجی ذخیره می‌شود تا بعداً بتوان آن را نمایش داد. اما اگر رویدادهای دیگری بدون اطلاع trace-cmd در ردگیری فعال شده باشند، قالب آن رویدادها ذخیره نخواهد شد و trace-cmd report قادر به نمایش آن‌ها نخواهد بود. در چنین حالتی، گزینهٔ -a را مشخص کنید تا قالب مربوط به تمام رویدادهای موجود در سیستم ذخیره شود.

-T

ردگیری پشته (stacktrace) را روی هر رویداد فعال می‌کند. به عنوان مثال:
          <idle>-0     [003] 58549.289091: sched_switch:         kworker/0:1:0 [120] R ==> trace-cmd:2603 [120]
          <idle>-0     [003] 58549.289092: kernel_stack:         <stack trace>
=> schedule (ffffffff814b260e)
=> cpu_idle (ffffffff8100a38c)
=> start_secondary (ffffffff814ab828)

--func-stack

ردگیری پشته را روی همهٔ توابع فعال می‌کند. توجه داشته باشید که این گزینه فقط برای ردیاب افزونه‌ای "function" کاربرد دارد و تنها زمانی اعمال می‌شود که گزینهٔ -l استفاده شده و در محدود کردن توابع موفق عمل کند. اگر ردیاب توابع فیلتر نشود و ردگیری پشته فعال گردد، ممکن است سیستم دچار قفل‌شدگی حین اجرا (live lock) شود.

-f filter

فیلتری برای رویداد قبلی مشخص می‌کند. این گزینه باید حتماً پس از یک -e قرار گیرد. این کار تعیین می‌کند که چه رویدادهایی بر اساس محتوای رویداد ضبط شوند. فیلترسازی مستقیماً به هسته منتقل می‌شود، بنابراین فیلترهای مجاز ممکن است به نسخهٔ هستهٔ شما بستگی داشته باشد. اساساً، این گزینه به شما اجازه می‌دهد تا با استفاده از نمادگذاری زبان C بررسی کنید که آیا رویداد باید پردازش شود یا خیر.
==, >=, <=, >, <, &, |, && و ||
موارد بالا معمولاً برای مقایسهٔ فیلدها بی‌خطر و قابل استفاده هستند.

--no-filter

رشته‌های اجرایی (threads) مربوط به trace-cmd را فیلتر نمی‌کند. به‌طور پیش‌فرض، این رشته‌ها فیلتر می‌شوند تا توسط رویدادها ردگیری نشوند. این گزینه باعث می‌شود که رشته‌های اجرایی trace-cmd نیز ردگیری شوند.

-R trigger

یک راه‌انداز (trigger) برای رویداد پیشین مشخص می‌کند. این گزینه باید حتماً بعد از یک -e بیاید. این کار راه‌انداز داده‌شده را به رویداد مربوطه اضافه می‌کند. برای اینکه فقط راه‌انداز فعال شود و نه خود رویداد، رویداد را پس از گزینهٔ -v قرار دهید.
برای اطلاعات بیشتر دربارهٔ راه‌اندازها، به Documentation/trace/events.txt در
کد منبع هستهٔ لینوکس مراجعه کنید.

-v

باعث می‌شود تمام رویدادهایی که پس از آن در خط فرمان مشخص می‌شوند ردگیری نشوند. این گزینه برای انتخاب یک زیرسیستم جهت ردگیری و در عین حال کنار گذاشتن رویدادهای خاصی از آن مفید است. برای مثال: «-e sched -v -e "*stat\*"» تمام رویدادهای زیرسیستم sched را به جز آن‌هایی که نامشان حاوی "stat" است فعال خواهد کرد.
نکته: گزینهٔ *-v* از شیوهٔ معکوس کردن تطابق‌ها در grep(1) برگرفته شده است.
-F
این گزینه تنها فایل اجرایی داده‌شده در خط فرمان را فیلتر می‌کند. اگر هیچ دستوری مشخص نشود، خود را فیلتر خواهد کرد (که کاملاً بی‌معنی است). استفاده از -F به شما امکان می‌دهد فقط رویدادهایی را ردگیری کنید که توسط دستور داده‌شده ایجاد می‌شوند.

-P pid

مشابه -F است، اما به شما امکان می‌دهد شناسه فرایند (pid) را برای ردگیری تعیین کنید.

-c

همراه با -F (یا -P در صورت پشتیبانی هسته) استفاده می‌شود تا فرزندان فرایند نیز ردگیری شوند.

--user

اجرای command مشخص‌شده در قالب کاربر داده‌شده.

-C clock

تنظیم ساعت ردگیری روی "clock".
برای مشاهده ساعت‌های در دسترس، دستور trace-cmd(1) list -C را اجرا کنید.

-o output-file

به‌طور پیش‌فرض، دستور trace-cmd report یک فایل trace.dat ایجاد می‌کند. با استفاده از گزینه -o می‌توانید فایل متفاوتی را برای نوشتن تعیین کنید.

-l function-name

این گزینه ردیاب‌های function و function_graph را محدود می‌کند تا تنها نام تابع داده‌شده را ردگیری کنند. می‌توان بیش از یک گزینه -l را در خط فرمان برای ردگیری چندین تابع مشخص کرد. این گزینه هم از تجزیه کامل regex(3) و هم از تجزیه پایه glob پشتیبانی می‌کند. اگر فیلتر تنها شامل نویسه‌های الفبایی-عددی، _، *، ? و . باشد، به‌صورت یک glob پایه تجزیه خواهد شد. برای اجبار به تجزیه به‌صورت regex، عبارت فیلتر را با ^ شروع کرده یا به $ ختم کنید تا به‌صورت یک regex تجزیه شود.

-g function-name

این گزینه برای پلاگین function_graph است. این گزینه تابع مشخص‌شده را نمودار (graph) می‌کند؛ یعنی تنها این تابع و تمام توابعی که توسط آن فراخوانی می‌شوند را ردگیری خواهد کرد. می‌توانید بیش از یک -g در خط فرمان مشخص کنید.

-n function-name

این گزینه اثری معکوس -l دارد. تابعی که با گزینه -n مشخص شود ردگیری نخواهد شد. این گزینه اولویت دارد؛ به این معنی که اگر یک تابع یکسان را هم برای -n و هم برای -l تعیین کنید، ردگیری نخواهد شد.

-d

برخی از پلاگین‌های ردیاب مانند ردیاب‌های تأخیر (latency tracers)، ردیاب تابع را به‌طور پیش‌فرض فعال می‌کنند. این گزینه از فعال شدن ردیاب تابع در هنگام راه‌اندازی جلوگیری می‌کند.

-D

گزینه -d تلاش خواهد کرد تا از گزینه function-trace برای غیرفعال کردن ردیاب تابع (در صورت وجود) استفاده کند، در غیر این صورت به فایل proc در مسیر /proc/sys/kernel/ftrace_enabled رجوع می‌کند، اما اگر گزینه function-trace در دسترس باشد تغییری در آن ایجاد نخواهد کرد. گزینه -D هم فایل proc مربوط به ftrace_enabled و هم گزینه function-trace را در صورت وجود غیرفعال خواهد کرد.
توجه داشته باشید که این کار ردگیری توابع را برای همه کاربران، از جمله کاربران
خارج از ردیاب‌های ftrace (مانند stack_tracer، perf و غیره) غیرفعال می‌کند.

-O option

ابزار Ftrace گزینه‌های گوناگونی دارد که می‌توان آن‌ها را فعال یا غیرفعال کرد. این گزینه امکان تنظیم آن‌ها را فراهم می‌کند. افزودن متن no به ابتدای یک گزینه آن را غیرفعال می‌کند؛ برای نمونه: «-O nograph-time» گزینه «graph-time» در Ftrace را غیرفعال خواهد کرد.

-s interval

فرایندهایی که trace-cmd برای ضبط از بافر حلقه‌ای ایجاد می‌کند، برای انجام ضبط باید بیدار شوند. تنظیم interval روی صفر باعث می‌شود این فرایندها با هر بار نوشته شدن داده جدید در بافر بیدار شوند. اما از آنجا که Ftrace در حال ثبت فعالیت‌های هسته است، به خواب رفتن دوباره این فرایندها ممکن است باعث ایجاد رویدادهای جدیدی در بافر حلقه‌ای شود که مجدداً فرایند را بیدار می‌کند. این امر بی‌جهت داده‌های اضافی به بافر حلقه‌ای می‌افزاید.
واحد سنجش 'interval' میکروثانیه است. مقدار پیش‌فرض روی 1000 (۱ میلی‌ثانیه) تنظیم شده است.
این مدت زمانی است که هر فرایند ضبط پیش از بیدار شدن برای ثبت هرگونه داده جدید
نوشته‌شده در بافر حلقه‌ای، می‌خوابد.

-r priority

اولویت اجرای رشته‌های ضبط ردگیری. در یک سیستم شلوغ، ممکن است رشته‌های ضبط ردگیری دچار قحطی منابع شده و رویدادها از دست بروند. این گزینه اولویت آن رشته‌ها را به اولویت بلادرنگ (FIFO) افزایش می‌دهد. با این حال از این گزینه با احتیاط استفاده کنید، زیرا می‌تواند رفتار سیستمی را که در حال ردگیری است تغییر دهد.

-b size

این گزینه اندازه بافر حلقه‌ای را روی size کیلوبایت تنظیم می‌کند. از آنجا که بافر حلقه‌ای Ftrace به ازای هر CPU مجزا است، این اندازه برابر با اندازه بافر حلقه‌ای اختصاصی هر CPU در هسته خواهد بود. استفاده از «-b 10000» روی سیستمی با ۴ پردازنده (CPU)، مجموع اندازه بافر Ftrace را به ۴۰ مگابایت می‌رساند.

--subbuf-size

بافر حلقه‌ای ردگیری هسته لینوکس به چندین زیربافر (sub-buffer) تقسیم شده است. این زیربافرها معمولاً به اندازه «page-size» معماری هستند (۴۰۹۶ برای x86). اندازه یک رویداد تنها می‌تواند حداکثر به اندازه بخش داده یک زیربافر باشد، اما در بیشتر موارد مشکلی ایجاد نمی‌کند. با این حال، مدت زمانی که نویسنده صرف جابه‌جایی از یک زیربافر به زیربافر بعدی می‌کند، سربار بیشتری نسبت به افزودن رویدادها در داخل خود زیربافر دارد. افزایش اندازه آن نه تنها اجازه ثبت رویدادهای بزرگ‌تر را می‌دهد (اگرچه این مورد به ندرت مسئله‌ساز است)، بلکه سرعت خود فرایند ردگیری را نیز افزایش می‌دهد.
نکته منفی زیربافرهای بزرگ‌تر این است که یک «خواندن» (read) از بافر حلقه‌ای،
اندازه زیربافر را از بافر حلقه‌ای بیرون کشیده و آن را با یک زیربافر جدید
جایگزین می‌کند. این ممکن است اثر واقعی نداشته باشد، اما شاید رفتار را
اندکی تغییر دهد. یا شاید هم تغییر ندهد!

-B buffer-name

اگر هسته از چند بافر پشتیبانی کند، این گزینه یک بافر با نام داده‌شده اضافه می‌کند. اگر بافری با این نام از پیش وجود داشته باشد، آن بافر صرفاً بازنشانی می‌شود و در پایان اجرای دستور record حذف نخواهد شد. اما اگر بافر به تازگی ایجاد شده باشد، در پایان اجرا حذف خواهد شد (مگر اینکه گزینه -k تنظیم شده باشد، یا از دستور start استفاده شده باشد)..sp
پس از ذکر نام یک بافر، تمام رویدادهایی که پس از آن اضافه می‌شوند به آن
بافر مرتبط خواهند شد. اگر هیچ بافری مشخص نشود، یا رویدادی قبل از نام یک
بافر تعیین گردد، به بافر اصلی (سطح بالا یا toplevel) مرتبط خواهد شد.
trace-cmd record -e sched -B block -e block -B time -e timer sleep 1
دستور بالا تمام رویدادهای sched را در بافر اصلی فعال می‌کند. سپس یک نمونهٔ
بافر به نام 'block' ایجاد کرده و تمام رویدادهای block را درون آن بافر فعال
می‌نماید. یک نمونه بافر 'time' ایجاد شده و تمام رویدادهای timer برای آن
رویداد فعال خواهند شد.

-m size

حداکثر اندازه بر حسب کیلوبایت که بافر هر CPU می‌تواند داشته باشد. توجه داشته باشید که به دلیل گرد کردن بر اساس اندازهٔ صفحه (page size)، ممکن است این عدد کاملاً دقیق نباشد. همچنین، این کار با جابه‌جایی میان دو بافر با نصف اندازهٔ ارائه‌شده انجام می‌شود؛ بنابراین خروجی ممکن است به اندازهٔ داده‌شده نباشد، حتی اگر مقدار بسیار بیشتری نوشته شده باشد.
برای جلوگیری از اتمام فضای دیسک در اجراهای طولانی، از این گزینه استفاده کنید.

-M cpumask

تنظیم cpumask برای ردیابی. این گزینه تنها بر آخرین نمونهٔ بافر ارائه‌شده تأثیر می‌گذارد. اگر پیش از هر نمونهٔ بافری مشخص شود، بر بافر اصلی تأثیر می‌گذارد. مقدار ارائه‌شده باید یک عدد در مبنای شانزده (hex) باشد.
trace-cmd record -p function -M c -B events13 -e all -M 5
اگر -M مشخص نشود، ماسک بدون تغییر باقی می‌ماند. برای فعال‌سازی همهٔ
CPUها، مقدار '-1' را ارسال کنید.

-k

به‌طور پیش‌فرض، هنگامی که کار trace-cmd با ردیابی تمام می‌شود، بافرها را بازنشانی کرده و تمام ردیابی‌هایی را که فعال کرده بود غیرفعال می‌کند. این گزینه مانع از غیرفعال‌سازی ردیاب و بازنشانی بافر توسط trace-cmd می‌شود. این گزینه برای اشکال‌زدایی trace-cmd کاربردی است.
نکته: معمولاً trace-cmd پروندهٔ "tracing_on" را به همان وضعیتی که پیش از
فراخوانی آن بود برمی‌گرداند. این گزینه مقدار آن پرونده را روی صفر باقی می‌گذارد.

-K

به‌طور پیش‌فرض، پیش از اینکه trace-cmd ضبط را آغاز کند، بافرها را بازنشانی کرده و رویدادها، تریگرها و موارد مشابه را پاک می‌کند. این گزینه مانع از انجام این کار توسط trace-cmd می‌شود. این گزینه شبیه به trace-cmd set است اما همچنان داده‌ها را ضبط می‌کند.

-i

به‌طور پیش‌فرض، اگر رویدادی ذکر شود که trace-cmd آن را پیدا نکند، با یک خطا خارج خواهد شد. این گزینه رویدادهایی را که در خط فرمان ذکر شده‌اند اما در سیستم یافت نمی‌شوند، نادیده می‌گیرد.

-N host:port

اگر ماشین دیگری در حال اجرای "trace-cmd listen" باشد، این گزینه برای ارسال داده‌ها با بسته‌های UDP به آن ماشین استفاده می‌شود. به‌جای نوشتن در یک پرونده خروجی، داده‌ها به یک سیستم راه دور فرستاده می‌شوند. این قابلیت برای ماشین‌های تعبیه‌شده با فضای ذخیره‌سازی کم یا داشتن یک ماشین واحد که تمام داده‌ها را در یک مخزن نگهداری می‌کند، ایده‌آل است.
نکته: این گزینه با افزونه‌های ردیاب تأخیر (latency tracer) پشتیبانی نمی‌شود:
  wakeup, wakeup_rt, irqsoff, preemptoff and preemptirqsoff

-V cid:port

اگر ضبط بر روی یک ماشین مجازی مهمان (guest VM) انجام شود و میزبان نیز در حال اجرای trace-cmd listen با گزینهٔ -V باشد، یا اگر ضبط بر روی میزبان در حال انجام باشد و یک مهمان در حال اجرای trace-cmd listen با گزینهٔ -V باشد، به شنونده متصل شوید (مشابه اتصال با گزینهٔ -N از طریق شبکه). این گزینه در ارتباط با افزونه‌های ردیاب تأخیر، دارای محدودیت‌های مشابه با گزینهٔ -N بالاست.

-t

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

-q | --quiet

برای استفاده در زمان ضبط یک برنامه کاربردی. خروجی استاندارد را (به‌جز خطاها) فرومی‌نشاند تا فقط خروجی برنامه نمایش داده شود.

--date

با گزینهٔ --date، ابزار "trace-cmd" پس از پایان ضبط، برچسب‌های زمانی (timestamps) را در بافر ردیابی می‌نویسد. سپس برچسب زمانی را به gettimeofday نگاشت می‌کند که این امر امکان دریافت خروجی بر اساس زمان تقویمی واقعی (wall time) را از برچسب‌های زمانی، هنگام خواندن پروندهٔ ایجادشدهٔ trace.dat فراهم می‌سازد.

--max-graph-depth depth

حداکثر عمقی را تعیین می‌کند که ردیاب function_graph در داخل یک تابع ردیابی خواهد کرد. مقدار یک تنها نشان می‌دهد که فضای کاربری در چه نقطه‌ای وارد هسته می‌شود، اما هیچ‌یک از توابع فراخوانی‌شده درون هسته را نشان نمی‌دهد. مقدار پیش‌فرض صفر است که به معنای بدون محدودیت می‌باشد.

--cmdlines-size size

تعداد مدخل‌هایی را تنظیم می‌کند که پروندهٔ ردیابی هسته "saved_cmdlines" می‌تواند در خود داشته باشد. این پرونده یک بافر چرخشی است که نگاشت میان خطوط فرمان (cmdlines) و شناسه‌های فرآیند (PIDs) را ذخیره می‌کند. در صورت پر شدن، منجر به خطوط فرمان تفکیک‌نشده ("<...>") در ردیابی خواهد شد. مقدار پیش‌فرض هسته ۱۲۸ است.

--module module

پالایش نام یک ماژول در ردیابی تابع. این گزینه معادل اضافه کردن :mod:module پس از تمام توابع دیگری است که پالایش می‌شوند. اگر فیلتر تابع دیگری مشخص نشده باشد، تمام توابع ماژول‌ها در فیلتر قرار می‌گیرند.
'--module snd'  معادل است با  '-l :mod:snd'
'--module snd -l "*jack*"' معادل '-l "*jack*:mod:snd"' است
'--module snd -n "*"' معادل '-n :mod:snd' است

--proc-map

نقشه آدرس فرآیندهای ردیابی‌شده را در فایل trace.dat ذخیره می‌کند. فرآیندهای ردیابی‌شده را می‌توان با استفاده از گزینه -P، یا به عنوان یک command داده‌شده مشخص کرد.

--profile

با گزینه --profile، دستور "trace-cmd" ردیابی‌ای را فعال می‌کند که می‌تواند همراه با گزینه --profile در trace-cmd-report(1) استفاده شود. اگر ردیاب -p تنظیم نشده باشد و عمق function graph توسط هسته پشتیبانی شود، ردیاب function_graph با عمق یک فعال خواهد شد (فقط نشان می‌دهد فضای کاربری در کجا وارد هسته می‌شود). این گزینه همچنین نقاط ردیابی (tracepoints) مختلفی را همراه با ردیابی پشته فعال می‌کند تا گزارش بتواند نشان دهد وظایف (tasks) در کجا طولانی‌ترین زمان مسدود شده‌اند.
برای جزئیات بیشتر و مثال‌ها به trace-cmd-profile(1) مراجعه کنید.

-G

رویدادهای وقفه (نرم‌افزاری و سخت‌افزاری) را به صورت سراسری (مرتبط با CPU به جای وظایف) تنظیم می‌کند. فقط برای --profile کار می‌کند.

-H event-hooks

تطبیق رویداد سفارشی را برای پیوند دادن هر دو رویداد به یکدیگر اضافه می‌کند. هنگامی که همراه با --profile استفاده نشود، این پارامتر را ذخیره می‌کند و این مورد توسط trace-cmd report --profile نیز استفاده خواهد شد؛ یعنی:
trace-cmd record -H hrtimer_expire_entry,hrtimer/hrtimer_expire_exit,hrtimer,sp
trace-cmd report --profile
زمان‌های hrtimer_expire_entry و hrtimer_expire_ext را پروفایل خواهد کرد.
برای قالب به trace-cmd-profile(1) مراجعه کنید.

-S

(فقط برای --profile) تنها ردیاب یا رویدادهای مشخص‌شده در خط فرمان را فعال می‌کند. با این گزینه، ردیاب function_graph و هیچ رویدادی (مانند sched_switch) فعال نخواهد شد، مگر اینکه صراحتاً در خط فرمان تعیین شده باشند (یعنی -p function -e sched_switch -e sched_wakeup)

--temp directory

هنگامی که trace-cmd در حال ضبط ردیابی است، داده‌های مربوط به هر CPU را در یک فایل جداگانه برای هر پردازنده ذخیره می‌کند. در پایان ردیابی، این فایل‌ها به فایل نهایی trace.dat الحاق می‌شوند. اگر فایل نهایی روی یک سیستم فایل شبکه‌ای باشد، ممکن است کپی کردن این فایل‌های موقت در همان مکان مناسب نباشد. از --temp می‌توان برای تعیین مکانی که این فایل‌های موقت باید در آن ایجاد شوند به trace-cmd استفاده کرد.

--ts-offset offset

یک آفست (فاصله زمانی) برای برچسب زمانی در فایل trace.dat اضافه می‌کند. این کار یک گزینه offset به فایل trace.dat می‌افزاید به‌طوری‌که اجرای trace-cmd report تمام برچسب‌های زمانی رویدادها را به اندازه آفست مشخص‌شده جابه‌جا می‌کند. این آفست بر حسب واحدهای خام است؛ بدین معنی که اگر برچسب‌های زمانی رویداد بر حسب نانوثانیه باشند، آفست نیز بر حسب نانوثانیه خواهد بود حتی اگر واحدهای نمایش‌داده‌شده بر حسب میکروثانیه باشند.

--tsync-interval

فاصله زمانی حلقه (بر حسب میلی‌ثانیه) را برای همگام‌سازی برچسب‌های زمانی با سیستم‌های مهمان (guests) تنظیم می‌کند: اگر عددی منفی مشخص شود، همگام‌سازی برچسب‌های زمانی غیرفعال می‌شود. اگر 0 مشخص شود، هیچ حلقه‌ای انجام نمی‌شود - آفست برچسب‌های زمانی تنها دو بار محاسبه می‌شود: در آغاز و در پایان ردیابی. همگام‌سازی برچسب‌های زمانی با مهمان‌ها تنها در صورت وجود پشتیبانی از VSOCK کار می‌کند.

--tsc2nsec

ساعت جاری را با استفاده از ضریب (multiplier) و شیفت tsc برگرفته از رابط perf هسته لینوکس، به نانوثانیه تبدیل می‌کند. این گزینه ساعت ردیابی را تغییر نمی‌دهد، بلکه صرفاً فرض می‌کند که ضریب و شیفت tsc برای ساعت انتخاب‌شده قابل اعمال هستند. در صورتی که مطمئن نیستید چه ساعتی را انتخاب کنید، می‌توانید از ساعت "-C tsc2nsec"; استفاده کنید.

--stderr

خروجی را به جای stdout به stderr هدایت می‌کند، اما خروجی دستور اجرا شده تغییر نخواهد کرد. این گزینه زمانی مفید است که می‌خواهید خروجی دستور در حال اجرا را پایش کنید، اما خروجی trace-cmd را نبینید.

--poll

انتظار برای در دسترس قرار گرفتن داده‌ها در بافرهای حلقه‌ای (ring-buffers) ردیابی ممکن است موجب برانگیختن وقفه بین پردازنده‌ای (IPI) شود. این امر ممکن است هنگام ردیابی سیستم‌های بلادرنگ (real-time) یا با تأخیر کم، نویز ردیابی غیرقابل‌قبولی ایجاد کند. گزینه poll برنامه trace-cmd را وادار می‌کند تا از O_NONBLOCK استفاده کند. ردها با انتظار فعال (busy waiting) استخراج می‌شوند که پردازنده‌ها را به شدت درگیر خواهد کرد، بنابراین تنها در مواقع نیاز واقعی از آن استفاده کنید.

--name

یک نام مشخص برای عامل (agent) جاری در حال پردازش تعیین می‌کند. پس از -A برای نام‌گذاری مهمان تحت ردیابی استفاده می‌شود. هنگام استفاده از شناسه vsocket به جای نام مهمان کاربرد دارد.

--verbose[=level]

سطح ثبت گزارش (log level) را تعیین می‌کند. سطوح پشتیبانی‌شده عبارتند از "none"، "critical"، "error"، "warning"، "info"، "debug"، "all" یا شناسه‌های آن‌ها "0"، "1"، "2"، "3"، "4"، "5"، "6". تنظیم سطح گزارش روی یک مقدار مشخص، تمام گزارش‌ها از آن سطح و سطوح قبلی را فعال می‌کند. در صورت مشخص نشدن، سطح پیش‌فرض "info" خواهد بود.
مثال: فعال‌سازی تمام لاگ‌های critical، error و warning
trace-cmd record --verbose=warning

--file-version

نسخه مورد نظر برای فایل خروجی. نسخه‌های پشتیبانی‌شده 6 یا 7 هستند.

--compression

فشرده‌سازی فایل خروجی ردیابی، یکی از این رشته‌ها می‌تواند ارسال شود:
'any'  - انتخاب خودکار بهترین الگوریتم فشرده‌سازی موجود
'none' - فایل ردگیری را فشرده نمی‌کند
'name' - نام الگوریتم‌های فشرده‌سازی مورد نظر. الگوریتم‌های موجود را می‌توان با این دستور فهرست کرد:
trace-cmd list -c

--proxy vsocket

برای دسترسی به agent از یک پروکسی vsocket استفاده می‌کند. عملکردی مشابه -A (برای یک agent) دارد اما اتصال پروکسی را به agent می‌فرستد. انتظار می‌رود روی یک مهمان با دسترسی ویژه اجرا شود که میزبان از آن آگاه است (همان‌طور که با cid در گزینهٔ -P برای agent مشخص شده است).

--daemonize پس از شروع ضبط، trace-cmd را در پس‌زمینه به‌عنوان یک دیمن اجرا می‌کند. در طول ضبط، یک pidfile در /var/run/trace-cmd-record.pid حاوی pid مربوط به trace-cmd ایجاد می‌کند.

روش پایه‌ای برای ردگیری همهٔ رویدادها:

# trace-cmd record -e all ls > /dev/null
# trace-cmd report
      trace-cmd-13541 [003] 106260.693809: filemap_fault: address=0x128122 offset=0xce
      trace-cmd-13543 [001] 106260.693809: kmalloc: call_site=81128dd4 ptr=0xffff88003dd83800 bytes_req=768 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_ZERO
             ls-13545 [002] 106260.693809: kfree: call_site=810a7abb ptr=0x0
             ls-13545 [002] 106260.693818: sys_exit_write:       0x1

برای استفاده از ردگیر تابع (function tracer) به‌همراه ردگیری sched switch:

# trace-cmd record -p function -e sched_switch ls > /dev/null
# trace-cmd report
             ls-13587 [002] 106467.860310: function: hrtick_start_fair <-- pick_next_task_fair
             ls-13587 [002] 106467.860313: sched_switch: prev_comm=trace-cmd prev_pid=13587 prev_prio=120 prev_state=R ==> next_comm=trace-cmd next_pid=13583 next_prio=120
      trace-cmd-13585 [001] 106467.860314: function: native_set_pte_at <-- __do_fault
      trace-cmd-13586 [003] 106467.860314: function:             up_read <-- do_page_fault
             ls-13587 [002] 106467.860317: function:             __phys_addr <-- schedule
      trace-cmd-13585 [001] 106467.860318: function: _raw_spin_unlock <-- __do_fault
             ls-13587 [002] 106467.860320: function: native_load_sp0 <-- __switch_to
      trace-cmd-13586 [003] 106467.860322: function: down_read_trylock <-- do_page_fault

در اینجا یک روش مناسب برای یافتن وقفه‌هایی با بیشترین تأخیر آمده است:

# trace-cmd record -p function_graph -e irq_handler_entry  -l do_IRQ sleep 10
# trace-cmd report
         <idle>-0     [000] 157412.933969: funcgraph_entry:                  |  do_IRQ() {
         <idle>-0     [000] 157412.933974: irq_handler_entry:    irq=48 name=eth0
         <idle>-0     [000] 157412.934004: funcgraph_exit:       + 36.358 us |  }
         <idle>-0     [000] 157413.895004: funcgraph_entry:                  |  do_IRQ() {
         <idle>-0     [000] 157413.895011: irq_handler_entry:    irq=48 name=eth0
         <idle>-0     [000] 157413.895026: funcgraph_exit:                        + 24.014 us |  }
         <idle>-0     [000] 157415.891762: funcgraph_entry:                  |  do_IRQ() {
         <idle>-0     [000] 157415.891769: irq_handler_entry:    irq=48 name=eth0
         <idle>-0     [000] 157415.891784: funcgraph_exit:       + 22.928 us |  }
         <idle>-0     [000] 157415.934869: funcgraph_entry:                  |  do_IRQ() {
         <idle>-0     [000] 157415.934874: irq_handler_entry:    irq=48 name=eth0
         <idle>-0     [000] 157415.934906: funcgraph_exit:       + 37.512 us |  }
         <idle>-0     [000] 157417.888373: funcgraph_entry:                  |  do_IRQ() {
         <idle>-0     [000] 157417.888381: irq_handler_entry:    irq=48 name=eth0
         <idle>-0     [000] 157417.888398: funcgraph_exit:       + 25.943 us |  }

نمونه‌ای از پروفایل:

 # trace-cmd record --profile sleep 1
 # trace-cmd report --profile --comm sleep
task: sleep-21611
  Event: sched_switch:R (1) Total: 99442 Avg: 99442 Max: 99442 Min:99442
     <stack> 1 total:99442 min:99442 max:99442 avg=99442
       => ftrace_raw_event_sched_switch (0xffffffff8105f812)
       => __schedule (0xffffffff8150810a)
       => preempt_schedule (0xffffffff8150842e)
       => ___preempt_schedule (0xffffffff81273354)
       => cpu_stop_queue_work (0xffffffff810b03c5)
       => stop_one_cpu (0xffffffff810b063b)
       => sched_exec (0xffffffff8106136d)
       => do_execve_common.isra.27 (0xffffffff81148c89)
       => do_execve (0xffffffff811490b0)
       => SyS_execve (0xffffffff811492c4)
       => return_to_handler (0xffffffff8150e3c8)
       => stub_execve (0xffffffff8150c699)
  Event: sched_switch:S (1) Total: 1000506680 Avg: 1000506680 Max: 1000506680 Min:1000506680
     <stack> 1 total:1000506680 min:1000506680 max:1000506680 avg=1000506680
       => ftrace_raw_event_sched_switch (0xffffffff8105f812)
       => __schedule (0xffffffff8150810a)
       => schedule (0xffffffff815084b8)
       => do_nanosleep (0xffffffff8150b22c)
       => hrtimer_nanosleep (0xffffffff8108d647)
       => SyS_nanosleep (0xffffffff8108d72c)
       => return_to_handler (0xffffffff8150e3c8)
       => tracesys_phase2 (0xffffffff8150c304)
  Event: sched_wakeup:21611 (1) Total: 30326 Avg: 30326 Max: 30326 Min:30326
     <stack> 1 total:30326 min:30326 max:30326 avg=30326
       => ftrace_raw_event_sched_wakeup_template (0xffffffff8105f653)
       => ttwu_do_wakeup (0xffffffff810606eb)
       => ttwu_do_activate.constprop.124 (0xffffffff810607c8)
       => try_to_wake_up (0xffffffff8106340a)

نمونه‌ای از استفاده از --daemonize همراه با ردگیری مهمان/میزبان:

$ sudo trace-cmd record --daemonize -p nop -e 'sched:sched_process_exec' -A guest -p nop -e net &&
> ping -c 1 10.20.1.2 &&
> sudo start-stop-daemon --stop --signal INT --retry 20 --pidfile /var/run/trace-cmd-record.pid &&
> sudo trace-cmd report -i trace.dat -i trace-guest.dat | head
Negotiated kvm time sync protocol with guest guest
Send SIGINT to pid 3071371 to stop recording
PING 10.20.1.2 (10.20.1.2) 56(84) bytes of data.
64 bytes from 10.20.1.2: icmp_seq=1 ttl=64 time=0.134 ms
--- 10.20.1.2 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.134/0.134/0.134/0.000 ms
CPU0 data recorded at offset=0x14f000
    229 bytes in size (4096 uncompressed)
....
      trace.dat: cpus=28
trace-guest.dat: cpus=1
      trace.dat:           ping-3071450 [013] 1196830.834258: sched_process_exec:     filename=/bin/ping pid=3071450 old_pid=3071450
trace-guest.dat:           <idle>-0     [000] 1196830.835990: napi_gro_receive_entry: dev=eth1 napi_id=0x2002 queue_mapping=1 skbaddr=0xffff95d051a5c400 vlan_tagged=0 vlan_proto=0x0000 vlan_tci=0x0000 protocol=0x0800 ip_summed=0 hash=0x00000000 l4_hash=0 len=84 data_len=0 truesize=768 mac_header_valid=1 mac_header=-14 nr_frags=0 gso_size=0 gso_type=0
trace-guest.dat:           <idle>-0     [000] 1196830.835997: napi_gro_receive_exit:  ret=3
trace-guest.dat:           <idle>-0     [000] 1196830.835998: netif_receive_skb:      dev=eth1 skbaddr=0xffff95d051a5c400x len=84
trace-guest.dat:           <idle>-0     [000] 1196830.836021: net_dev_queue:          dev=eth1 skbaddr=0xffff95d051a5c700x len=98
trace-guest.dat:           <idle>-0     [000] 1196830.836024: net_dev_start_xmit:     dev=eth1 queue_mapping=0 skbaddr=0xffff95d051a5c700 vlan_tagged=0 vlan_proto=0x0000 vlan_tci=0x0000 protocol=0x0800 ip_summed=0 len=98 data_len=0 network_offset=14 transport_offset_valid=1 transport_offset=34 tx_flags=0 gso_size=0 gso_segs=0 gso_type=0
trace-guest.dat:           <idle>-0     [000] 1196830.836069: net_dev_xmit:           dev=eth1 skbaddr=0xffff95d051a5c700 len=98 rc=0
      trace.dat:           sudo-3071451 [015] 1196830.838262: sched_process_exec:     filename=/usr/bin/sudo pid=3071451 old_pid=3071451

trace-cmd(1), trace-cmd-report(1), trace-cmd-start(1), trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1), trace-cmd-profile(1)

نوشته‌شده توسط Steven Rostedt، <rostedt@goodmis.org[1]>

https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git

حق نشر (C) 2010 متعلق به Red Hat, Inc. استفاده آزاد از این نرم‌افزار تحت شرایط «پروانه عمومی همگانی گنو» (GPL) مجاز است.

1.
rostedt@goodmis.org
mailto:rostedt@goodmis.org
03/09/2026 libtracefs