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

trace-cmd-set - تنظیم یک پارامتر پیکربندی در ردیاب داخلی لینوکس Ftrace

trace-cmd set [OPTIONS] [command]

دستور trace-cmd(1) set یک پارامتر پیکربندی از ردیاب هسته لینوکس Ftrace را تنظیم می‌کند. دستور command مشخص‌شده پس از تنظیم وضعیت ftrace اجرا خواهد شد. وضعیت پیکربندی‌شده ftrace را می‌توان با استفاده از دستور trace-cmd-reset(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 نیز باشد. بدین ترتیب که "*stat*" تمام
رویدادها (یا زیرسیستم‌هایی) را که نویسه‌های "stat" در نامشان وجود دارد انتخاب
می‌کند.
کلیدواژه 'all' می‌تواند برای فعال کردن همه رویدادها استفاده شود.

-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

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

-f filter

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

-R trigger

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

-v

این گزینه اثر گزینه‌های مشخص‌شده پس از خود در خط فرمان را معکوس می‌کند. این گزینه بر موارد زیر تأثیر می‌گذارد:
 -e: باعث می‌شود تمام رویدادهای مشخص‌شده ردگیری نشوند. این قابلیت برای
       انتخاب یک زیرسیستم جهت ردگیری، اما مستثنی کردن رویدادهای گوناگون، کاربردی است.
       برای مثال: "-e sched -v -e "*stat*"" تمام رویدادهای زیرسیستم sched
       را به جز آن‌هایی که "stat" در نامشان دارند فعال می‌کند.
 -B: نمونه (instance) مشخص‌شده ftrace را حذف می‌کند. هیچ گزینه
       پیکربندی مرتبط با این نمونه نباید در خط فرمان وجود داشته باشد.
       برای مثال: "-v -B bar -B foo" نمونه bar را حذف کرده و یک نمونه
       جدید foo ایجاد می‌کند.
نکته: گزینه -v برگرفته از شیوه‌ای است که grep(1) تطابق‌های پس از خود را
معکوس می‌سازد.

-P pid

فقط شناسه‌های فرایند (PID) مشخص‌شده را فیلتر می‌کند. استفاده از -P به شما امکان می‌دهد تنها رویدادهایی را که توسط فرایند مربوطه ایجاد شده‌اند ردگیری کنید. -c
همراه با -P برای ردگیری فرزندان فرآیند نیز استفاده می‌شود (اگر هسته از آن پشتیبانی کند).

--user

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

-C clock

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

-l function-name

این گزینه ردگیرهای function و function_graph را تنها به ردگیری نام تابع داده‌شده محدود می‌کند. برای ردگیری بیش از یک تابع، می‌توان بیش از یک -l را در خط فرمان مشخص کرد. استفادهٔ محدود از عبارات عمومی (glob expressions) نیز مجاز است. این موارد عبارتند از: match* تنها برای پالایش توابعی که با match آغاز می‌شوند. *match تنها برای پالایش توابعی که با match پایان می‌یابند. *match\* تنها برای پالایش توابعی که حاوی match هستند.

-g function-name

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

-n function-name

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

-d

برخی افزونه‌های ردگیر، ردگیر function را به طور پیش‌فرض فعال می‌کنند؛ مانند ردگیرهای latency. این گزینه از فعال شدن ردگیر function در زمان راه‌اندازی جلوگیری می‌کند.

-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 را غیرفعال خواهد کرد.

-b size

این گزینه اندازهٔ بافر حلقه‌ای (ring buffer) را روی size کیلوبایت تنظیم می‌کند. از آنجا که بافر حلقه‌ای Ftrace به ازای هر CPU است، این اندازه، اندازهٔ بافر حلقه‌ای هر CPU درون هسته است. استفاده از "-b 10000"; روی ماشینی با ۴ پردازنده، اندازهٔ کل بافر Ftrace را به ۴۰ مگابایت می‌رساند.

-B buffer-name

اگر هسته از چندین بافر پشتیبانی کند، این گزینه بافری با نام داده‌شده اضافه می‌کند. اگر نام بافر از قبل وجود داشته باشد، آن بافر تنها بازنشانی می‌شود. 
پس از اعلام نام یک بافر، تمام رویدادهایی که بعد از آن اضافه شوند با آن
بافر مرتبط خواهند شد. اگر بافری مشخص نشود، یا رویدادی قبل از نام بافر
مشخص شود، با بافر اصلی (سطح بالا) مرتبط خواهد شد.
trace-cmd set -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 set -p function -M c -B events13 -e all -M 5
اگر -M مشخص نشود، ماسک بدون تغییر باقی می‌ماند. برای فعال‌سازی همهٔ پردازنده‌ها (CPUs)، مقدار '-1' را ارسال کنید.

-i

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

-q | --quiet

از نمایش خروجی عادی، به‌جز در صورت بروز خطا، جلوگیری می‌کند.

--max-graph-depth depth

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

--cmdlines-size size

تعداد ورودی‌هایی را که فایل ردگیری هسته "saved_cmdlines" می‌تواند در بر داشته باشد، تعیین می‌کند. این فایل یک بافر حلقه‌ای (circular buffer) است که نگاشت بین cmdlineها و PIDها را ذخیره می‌کند. در صورت پر شدن، منجر به cmdlineهای حل‌نشده ("<...>") در ردگیری می‌شود. مقدار پیش‌فرض هسته 128 است.

--module module

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

--stderr

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

--fork

اگر دستوری مشخص شده باشد، trace-cmd منتظر پایان یافتن آن دستور می‌ماند، مگر این‌که گزینهٔ --fork مشخص شده باشد. در این حالت، دستور را منشعب (fork) کرده و فوراً بازمی‌گردد.

--verbose[=level]

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

فعال‌سازی همه رویدادها برای ردیابی:

# trace-cmd set -e all

تنظیم ردیاب تابع:

# trace-cmd set -p function

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)

نوشته‌شده توسط Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com[1]>

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

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

1.
tz.stoyanov@gmail.com
mailto:tz.stoyanov@gmail.com
03/09/2026 libtracefs