TRACE-CMD.DAT.V(5) راهنمای libtracefs TRACE-CMD.DAT.V(5)

trace-cmd.dat.v7 - قالب فایل نسخه ۷ ابزار trace-cmd

trace-cmd.dat ignore

ابزار trace-cmd(1) یک فایل «trace.dat» تولید می‌کند. این فایل بسته به اینکه کاربر نام خروجی متفاوتی را مشخص کند می‌تواند هر نام دیگری نیز داشته باشد، اما باید دارای قالب باینری مشخصی باشد. این فایل توسط trace-cmd برای ذخیره ردگیری‌های هسته در آن و امکان استخراج ردگیری در زمانی دیگر مورد استفاده قرار می‌گیرد (نگاه کنید به trace-cmd-report(1)).

سه بایت نخست شامل مقدار جادویی زیر هستند:
0x17 0x08  0x44
۷ بایت بعدی شامل نویسه‌های زیر هستند:
"tracing"
مجموعه بعدی نویسه‌ها شامل یک رشته پایان‌یافته با تهی ('\0')
است که نسخه فایل را در بر دارد:
"7\0"
۱ بایت بعدی شامل پرچم‌های ترتیب بایت (endianness) فایل است:
0 = little endian
1 = big endian
بایت بعدی شامل تعداد بایت‌ها برای هر مقدار "long" است:
4 - 32-bit long values
8 - 64-bit long values
نکته: این اندازه نوع long در فضای کاربری سیستم هدف است، نه
اندازه در فضای هسته.
[ اکنون تمام اعداد بر اساس ترتیب بایت تعریف‌شده در فایل نوشته می‌شوند. ]
۴ بایت بعدی یک کلمه ۳۲ بیتی هستند که اندازه صفحه حافظه
ماشین هدف ردیابی‌شده را تعیین می‌کنند.
سرآیند الگوریتم فشرده‌سازی در ادامه نوشته می‌شود:
   "name\0version\0"
که در آن "name" و "version" رشته‌هایی حاوی نام و نسخه
الگوریتم فشرده‌سازی مورد استفاده برای فشرده‌سازی فایل ردگیری هستند. اگر نام
برابر با "none" باشد، داده‌های درون فایل فشرده نشده‌اند.
۸ بایت بعدی یک عدد صحیح ۶۴ بیتی است؛ آفست درون فایل که
نخستین بخش OPTIONS در آن قرار دارد.
بقیه فایل از بخش‌های مختلفی تشکیل شده است. تنها بخش اجباری
نخستین بخش OPTIONS است و تمامی بخش‌های دیگر اختیاری هستند. مکان و
ترتیب قرارگیری بخش‌ها الزامی و سخت‌گیرانه نیست. هر بخش با یک سرآیند آغاز می‌شود:

<2 bytes> unsigned short integer, ID of the section.
<2 bytes> unsigned short integer, section flags:
  1 = the section is compressed.
<4 bytes> ID of a string, description of the section.
<8 bytes> long long unsigned integer, size of the section in the file.
اگر بخش فشرده شده باشد، مقدار فوق همان اندازه فشرده‌شده است.
بخش باید هنگام خواندن از حالت فشرده خارج شود. قالب توصیف‌شده برای
بخش‌ها به داده‌های غیرفشرده اشاره دارد.

برخی از بخش‌های فایل ممکن است با الگوریتم فشرده‌سازی مشخص‌شده در
سرآیند الگوریتم فشرده‌سازی، فشرده شده باشند. بخش‌های فشرده‌شده دارای یک سرآیند
فشرده‌سازی هستند که پس از سرآیند بخش و دقیقاً پیش از داده‌های فشرده‌شده نوشته می‌شود:
  <4 bytes> unsigned int, size of compressed data in this section.
  <4 bytes> unsigned int, size of uncompressed data.
  <data> binary compressed data, with the specified size.

دو بخش ویژه به نام‌های BUFFER FLYRECORD و BUFFER LATENCY وجود دارند که شامل
داده‌های ردگیری هستند. این بخش‌ها ممکن است با الگوریتم فشرده‌سازی مشخص‌شده در
سرآیند فشرده‌سازی، فشرده شده باشند. معمولاً اندازه این بخش‌ها بسیار حجیم است، به همین دلیل
قالب فشرده‌سازی آن‌ها با سایر بخش‌ها تفاوت دارد. داده‌های ردگیری در تکه‌های مجزا (chunks)
فشرده می‌شوند. اندازه هر تکه در زمان ایجاد فایل مشخص می‌شود. قالب داده‌های
ردگیری فشرده‌شده به صورت زیر است:
   <4 bytes> unsigned int, count of chunks.
   سپس تکه‌های فشرده‌شده به تعداد مشخص‌شده می‌آیند. برای هر تکه:
      <4 bytes> unsigned int, size of compressed data in this chunk.
      <4 bytes> unsigned int, size of uncompressed data, aligned with the trace page size.
      <data> binary compressed data, with the specified size.
این تکه‌ها باید هنگام خواندن از حالت فشرده خارج شوند. قالب توصیف‌شده
برای داده‌های ردگیری به داده‌های غیرفشرده اشاره دارد.

Section ID: 0
این تنها بخش اجباری در فایل است. می‌تواند چندین بخش گزینه‌ها
وجود داشته باشد؛ نخستین بخش در آفست مشخص‌شده دقیقاً پس از سرآیند
الگوریتم فشرده‌سازی قرار دارد. این بخش از چندین گزینه ردگیری تشکیل شده است
که هر گزینه دارای قالب زیر است:
  <2 bytes> unsigned short integer, ID of the option.
  <4 bytes> unsigned integer, size of the option's data.
  <binary data> bytes of the size specified above, data of the option.
گزینه‌های پشتیبانی‌شده توسط فایل ردگیری نسخه ۷:
DONE: id 0, size 8
  این گزینه نشان‌دهنده پایان بخش گزینه‌ها است و همواره به عنوان
  آخرین گزینه نوشته می‌شود. داده‌های گزینه DONE عبارتند از:
     <8 bytes> long long unsigned integer, offset in the trace file where
     the next options section is located. اگر این آفست 0 باشد، یعنی
     هیچ بخش گزینه دیگری وجود ندارد.
DATE: id 1, size vary
  داده‌های گزینه DATE یک رشته اسکی پایان‌یافته با null است که اختلاف زمانی
  بین برچسب‌های زمانی رویدادهای ردگیری و زمان عمومی روز (Generic Time of Day)
  سیستم را نشان می‌دهد.
CPUSTAT: id 2, size vary
  داده‌های گزینه CPUSTAT یک رشته اسکی پایان‌یافته با null است که محتوای فایل
  «per_cpu/cpu<id>/stats» از دایرکتوری ردگیری را شامل می‌شود. برای هر
  پردازنده (CPU) یک گزینه CPUSTAT وجود دارد.
BUFFER: id 3, size vary
  گزینه BUFFER داده‌های ردگیری flyrecord ذخیره‌شده در فایل را که از یک نمونه
  ردگیری جمع‌آوری شده است، توصیف می‌کند. برای هر نمونه ردگیری یک گزینه BUFFER
  وجود دارد. قالب داده‌های BUFFER عبارت است از:
    <8 bytes> long long unsigned integer, offset in the trace file where the
    BUFFER FLYRECORD section is located, containing flyrecord trace data.
    <string> a null terminated ASCII string, name of the trace instance. رشته خالی ""
    به عنوان نام نمونه اصلی (top instance) ذخیره می‌شود.
    <string> a null terminated ASCII string, trace clock used for events timestamps in
    this trace instance.
    <4 bytes> unsigned integer, size of the trace buffer page.
    <4 bytes> unsigned integer, count of the CPUs with trace data.
    به ازای هر CPU از تعداد فوق:
       <4 bytes> unsigned integer, ID of the CPU.
       <8 bytes> long long unsigned integer, offset in the trace file where the trace data
       for this CPU is located.
       <8 bytes> long long unsigned integer, size of the trace data for this CPU.
TRACECLOCK: id 4, size vary
  داده‌های گزینه TRACECLOCK یک رشته اسکی پایان‌یافته با null است که محتوای فایل
  «trace_clock» از دایرکتوری ردگیری را شامل می‌شود.
UNAME: id 5, size vary
  داده‌های گزینه UNAME یک رشته اسکی پایان‌یافته با null است که سیستمی را که
  داده‌های ردگیری از آن جمع‌آوری شده است، مشخص می‌کند. این رشته توسط فراخوان
  سیستمی uname() به دست می‌آید.
HOOK: id 6, size vary
  داده‌های گزینه HOOK یک رشته اسکی پایان‌یافته با null است که قلاب‌های رویداد را توصیف
  می‌کند: تطبیق سفارشی رویدادها برای پیوند دادن هر دو رویداد به یکدیگر.
OFFSET: id 7, size vary
  داده‌های گزینه OFFSET یک رشته اسکی پایان‌یافته با null است که زمان ثابتی را نشان
  می‌دهد که هنگام خواندن به هر برچسب زمانی رویداد اضافه می‌شود.
CPUCOUNT: id 8, size 4
  داده‌های گزینه CPUCOUNT عبارتند از:
    <4 bytes> unsigned integer, number of CPUs in the system.
VERSION: id 9, size vary
  داده‌های گزینه VERSION یک رشته اسکی پایان‌یافته با null است که نسخه برنامه
  trace-cmd استفاده‌شده برای جمع‌آوری این گزارش‌های ردگیری را نشان می‌دهد.
PROCMAPS: id 10, size vary
  داده‌های گزینه PROCMAPS یک رشته اسکی پایان‌یافته با null است که نگاشت حافظه
  هر فرآیند فیلترشده و ردیابی‌شده را نشان می‌دهد. قالب رشته برای هر فرآیند فیلترشده عبارت است از:
    <procss ID> <libraries count> <process command> \n
      <memory start address> <memory end address> <full path of the mapped library file> \n
      ...
       یک خط جداگانه برای هر کتابخانه استفاده‌شده توسط این فرآیند
      ...
    ...
TRACEID: id 11, size 8
  داده‌های گزینه TRACEID یک شناسه یکتا برای این نشست ردگیری است:
    <8 bytes> long long unsigned integer, trace session identifier.
TIME_SHIFT: id 12, size vary
  گزینه TIME_SHIFT اطلاعات همگام‌سازی زمان را که در طول نشست ردگیری میزبان (host)
  و مهمان (guest) جمع‌آوری شده است، ذخیره می‌کند. معمولاً این اطلاعات در فایل ردگیری
  مهمان ذخیره می‌شود. این اطلاعات هنگام نمایش تمام فایل‌های حاصل از این نشست ردگیری،
  برای همگام‌سازی برچسب‌های زمانی رویدادهای مهمان با میزبان به کار می‌روند. قالب داده‌های
  گزینه TIME_SHIFT عبارت است از:
    <8 bytes> long long unsigned integer, trace identifier of the peer (usually the host).
    <4 bytes> unsigned integer, flags specific to the time synchronization protocol, used in this
    trace session.
    <4 bytes> unsigned integer, number of traced CPUs. برای هر CPU، تصحیحات
    برچسب زمانی ثبت می‌شوند:
       <4 bytes> unsigned integer, count of the recorded timestamps corrections for this CPU.
       <array of unsigned long long integers of the above count>, زمان‌هایی که تصحیحات محاسبه شده‌اند
       <array of unsigned long long integers of the above count>, آفست‌های تصحیحات
       <array of unsigned long long integers of the above count>, ضریب مقیاس‌بندی تصحیحات
GUEST: id 13, size vary
  گزینه GUEST اطلاعات مربوط به ماشین‌های مهمان ردیابی‌شده در این نشست ردگیری را
  ذخیره می‌کند. معمولاً این اطلاعات در فایل ردگیری میزبان ذخیره می‌شود. برای هر مهمان
  ردیابی‌شده یک گزینه GUEST جداگانه وجود دارد. این اطلاعات هنگام نمایش تمام فایل‌های این
  نشست ردگیری مورد استفاده قرار می‌گیرند. قالب داده‌های گزینه GUEST عبارت است از:
     <string> a null terminated ASCII string, name of the guest.
     <8 bytes> long long unsigned integer, trace identifier of the guest for this session.
     <4 bytes> unsigned integer, number of guest's CPUs. به ازای هر CPU:
        <4 bytes> unsigned integer, ID of the CPU.
        <4 bytes> unsigned integer, PID of the host task, emulating this guest CPU.
TSC2NSEC: id 14, size 16
  گزینه TSC2NSEC اطلاعات مورد استفاده برای تبدیل برچسب‌های زمانی رویدادهای TSC به نانوثانیه
  را ذخیره می‌کند. قالب داده‌های گزینه TSC2NSEC عبارت است از:
     <4 bytes> unsigned integer, time multiplier.
     <4 bytes> unsigned integer, time shift.
     <8 bytes> unsigned long long integer, time offset.
STRINGS: id 15, size vary
  گزینه STRINGS فهرستی از رشته‌های پایان‌یافته با nul را در خود نگه می‌دارد که حاوی
  نام سایر بخش‌ها هستند.
HEADER_INFO: id 16, size 8
  داده‌های گزینه HEADER_INFO عبارتند از:
    <8 bytes> long long unsigned integer, offset into the trace file where the HEADER INFO
    section is located
FTRACE_EVENTS: id 17, size 8
  داده‌های گزینه FTRACE_EVENTS عبارتند از:
    <8 bytes> long long unsigned integer, offset into the trace file where the
    FTRACE EVENT FORMATS section is located.
EVENT_FORMATS: id 18, size 8
  داده‌های گزینه EVENT_FORMATS عبارتند از:
    <8 bytes> long long unsigned integer, offset into the trace file where the EVENT FORMATS
    section is located.
KALLSYMS: id 19, size 8
  داده‌های گزینه KALLSYMS عبارتند از:
    <8 bytes> long long unsigned integer, offset into the trace file where the KALLSYMS
    section is located.
PRINTK: id 20, size 8
  داده‌های گزینه PRINTK عبارتند از:
    <8 bytes> long long unsigned integer, offset into the trace file where the TRACE_PRINTK
    section is located.
CMDLINES: id 21, size 8
  داده‌های گزینه CMDLINES عبارتند از:
    <8 bytes> long long unsigned integer, offset into the trace file where the
    SAVED COMMAND LINES section is located.
BUFFER_TEXT: id 22, size
  گزینه BUFFER_LAT داده‌های ردگیری تاخیر (latency) ذخیره‌شده در فایل را توصیف
  می‌کند. قالب داده‌های BUFFER_LAT عبارت است از:
    <8 bytes> long long unsigned integer, offset in the trace file where the
    BUFFER LATENCY section is located, containing latency trace data.
    <string> a null terminated ASCII string, name of the trace instance. رشته خالی ""
    به عنوان نام نمونه اصلی ذخیره می‌شود.
    <string> a null terminated ASCII string, trace clock used for events timestamps in
    this trace instance.
BTF_FILE: id 23, size 8
  داده‌های گزینه BTF_FILE عبارتند از:
   داده‌های فشرده‌شده از فایل میزبان /sys/kernel/btf/vmlinux با استفاده از
   الگوریتم فشرده‌سازی تعریف‌شده در سرآیند trace.dat. داده‌های فشرده‌سازی شامل
   اندازه خروجی غیرفشرده هستند.
LAST_BOOT_INFO: id 24, size vary
  داده‌های گزینه LAST_BOOT_INFO شامل محتوای last_boot_info در صورتی که این فایل
   برای یک نمونه وجود داشته باشد، است. این داده‌ها با نام نمونه آغاز می‌شوند که
   به دنبال آن یک دونقطه ":" و سپس محتوای فایل last_boot_info می‌آید. در حال حاضر
   نام نمونه مورد استفاده قرار نمی‌گیرد، اما برای حالتی در آینده در نظر گرفته شده که
   بیش از یک نمونه با این فایل وجود داشته باشد.
MODULES_FILE: id 25, size 8
  داده‌های گزینه MODULES_FILE عبارتند از:
   داده‌های فشرده‌شده از فایل میزبان /proc/modules با استفاده از الگوریتم
   فشرده‌سازی تعریف‌شده در سرآیند trace.dat. داده‌های فشرده‌سازی شامل
   اندازه خروجی غیرفشرده هستند.

Section ID: 16
۱۲ بایت نخست بخش، پس از سرآیند بخش، شامل رشته زیر است:
"header_page\0"
۸ بایت بعدی یک کلمه ۶۴ بیتی شامل اندازه اطلاعات سرآیند
صفحه است که در ادامه ذخیره شده است.
مجموعه داده بعدی به اندازه خوانده‌شده از ۸ بایت قبلی است
و شامل داده‌های بازیابی‌شده از debugfs/tracing/events/header_page می‌باشد.
نکته: اندازه فیلد دوم \fBcommit\fR شامل اندازه نوع long در هسته
هدف است. به عنوان مثال:
field: local_t commit;        offset:8;       \fBsize:8;\fR   signed:1;
نشان می‌دهد که هسته دارای مقادیر ۶۴ بیتی برای long است.
۱۳ بایت بعدی شامل رشته زیر است:
"header_event\0"
۸ بایت بعدی یک کلمه ۶۴ بیتی شامل اندازه اطلاعات سرآیند
رویداد است که در ادامه ذخیره شده است.
مجموعه داده بعدی به اندازه خوانده‌شده از ۸ بایت قبلی است
و شامل داده‌های بازیابی‌شده از debugfs/tracing/events/header_event می‌باشد.
این داده‌ها به ابزار trace-cmd امکان می‌دهند تشخیص دهد آیا
قالب بافر حلقه‌ای (ring buffer) هسته تغییری کرده است یا خیر.

Section ID: 17
بلافاصله پس از سرآیند بخش، اطلاعات مربوط به رویدادهای
خاص Ftrace قرار می‌گیرد. این‌ها رویدادهایی هستند که توسط پلاگین‌های
Ftrace استفاده می‌شوند و از طریق ردیابی رویداد فعال نمی‌گردند.
۴ بایت بعدی شامل یک کلمه ۳۲ بیتی از تعداد فایل‌های قالب رویداد
Ftrace است که در فایل ذخیره شده‌اند.
به تعداد دفعاتی که توسط ۴ بایت قبلی تعیین شده، موارد زیر
تکرار می‌شود:
۸ بایت برای اندازه فایل قالب رویداد Ftrace.
فایل قالب رویداد Ftrace کپی‌شده از ماشین هدف:
debugfs/tracing/events/ftrace/<event>/format

Section ID: 18
بلافاصله پس از سرآیند بخش، اطلاعات مربوط به چیدمان
رویداد قرار می‌گیرد.
۴ بایت بعدی یک کلمه ۳۲ بیتی شامل تعداد سیستم‌های رویدادی (event systems)
است که در فایل ذخیره شده‌اند. این‌ها دایرکتوری‌های موجود در
debugfs/tracing/events به استثنای دایرکتوری \fBftrace\fR هستند.
به تعداد دفعاتی که توسط ۴ بایت قبلی مشخص شده است، موارد
زیر وجود دارد:
یک رشته پایان‌یافته با null شامل نام سیستم.
۴ بایت شامل یک کلمه ۳۲ بیتی که تعداد رویدادهای موجود
درون آن سیستم را مشخص می‌کند.
به تعداد دفعاتی که در ۴ بایت قبلی تعیین شده است، موارد
زیر وجود دارد:
۸ بایت برای اندازه فایل قالب رویداد.
فایل قالب رویداد کپی‌شده از ماشین هدف:
debugfs/tracing/events/<system>/<event>/format

Section ID: 19
بلافاصله پس از سرآیند بخش، اطلاعات نگاشت آدرس‌های
توابع به نام توابع قرار می‌گیرد.
۴ بایت بعدی یک کلمه ۳۲ بیتی شامل اندازه داده‌های حاوی
نگاشت توابع است.
مجموعه داده بعدی به اندازه مشخص‌شده توسط ۴ بایت قبلی است
و شامل اطلاعات حاصل از فایل زیر در ماشین هدف می‌باشد:
/proc/kallsyms

Section ID: 20
اگر توسعه‌دهنده‌ای از trace_printk() در هسته استفاده کرده باشد،
ممکن است رشته قالب در خارج از بافر حلقه‌ای ذخیره شود.
این اطلاعات را می‌توان در این مسیر یافت:
debugfs/tracing/printk_formats
۴ بایت بعدی یک کلمه ۳۲ بیتی شامل اندازه داده‌های حاوی
قالب‌های printk است.
مجموعه داده بعدی به اندازه مشخص‌شده توسط ۴ بایت قبلی است
و شامل اطلاعات استخراج‌شده از debugfs/tracing/printk_formats می‌باشد.

Section ID: 21
بلافاصله پس از سرآیند بخش، اطلاعات نگاشت
شناسه فرآیند (PID) به نام فرآیند قرار می‌گیرد.
۸ بایت بعدی شامل یک کلمه ۶۴ بیتی است که اندازه داده‌های
نگاشت PID به نام فرآیند را در خود نگه می‌دارد.
مجموعه داده بعدی به اندازه مشخص‌شده توسط ۸ بایت قبلی است
و شامل اطلاعات استخراج‌شده از debugfs/tracing/saved_cmdlines می‌باشد.

این بخش شامل داده‌های ردگیری flyrecord است که در یک نمونه ردگیری جمع‌آوری شده‌اند.
داده‌ها به ازای هر CPU ذخیره می‌شوند. هر بخش BUFFER FLYRECORD دارای یک گزینه BUFFER
متناظر است که حاوی اطلاعات مربوط به داده‌های ردگیری ذخیره‌شده CPU می‌باشد. لایه
فاصله‌گذاری (padding) بین سرآیند بخش و داده‌های CPU قرار می‌گیرد تا داده‌های CPU در موقعیتی
هم‌تراز با صفحه (صفحه هدف) در فایل قرار گیرند.
این داده‌ها مستقیماً از بافر حلقه‌ای Ftrace کپی می‌شوند و دارای همان
قالبی هستند که توسط فایل‌های سرآیند رویداد بارگذاری‌شده در فایل قالب
سرآیند تعیین شده است.
ابزار trace-cmd در صورت امکان تلاش خواهد کرد داده‌ها را صفحه به صفحه با
اندازه صفحه هدف \fBmmap(2)\fR کند. در صورت عدم موفقیت در نگاشت حافظه (mmap)، به جای آن
داده‌ها را به صورت معمولی خواهد خواند.

بخش متن بافر (BUFFER TEXT SECTION)

.ft C
  Section ID: 22
  این بخش شامل داده‌های ردگیری تاخیر (latency) است، متن اسکی گرفته‌شده از
  فایل debugfs/tracing/trace ماشین هدف.
بخش رشته‌ها (STRINGS SECTION)
.ft
Section ID: 15
تمام رشته‌های متاداده فایل ردگیری در یک بخش رشته در درون فایل ذخیره می‌شوند. این بخش
شامل فهرستی از رشته‌های اسکی پایان‌یافته با nul است. یک شناسه از رشته در متاداده فایل
استفاده می‌شود که همان آفست رشته واقعی در بخش رشته است. رشته‌ها می‌توانند در چندین
بخش رشته در فایل ذخیره شوند.

Section ID: 23
بلافاصله پس از سرآیند بخش، یک مقدار ۸ بایتی قرار دارد که شامل
یک کلمه ۶۴ بیتی است و اندازه فایل BTF (که ممکن است فشرده باشد) را در خود نگه می‌دارد.
مجموعه داده بعدی به اندازه مشخص‌شده توسط ۸ بایت قبلی است
و شامل اطلاعات حاصل از /sys/kernel/btf/vmlinux می‌باشد.

Section ID: 25
بلافاصله پس از سرآیند بخش، یک مقدار ۸ بایتی قرار دارد که شامل
یک کلمه ۶۴ بیتی است و اندازه فایل ماژول‌ها (که ممکن است فشرده باشد) را در خود نگه می‌دارد.
مجموعه داده بعدی به اندازه مشخص‌شده توسط ۸ بایت قبلی است
و شامل اطلاعات استخراج‌شده از /proc/modules می‌باشد.

trace-cmd(1), trace-cmd-record(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.dat(5)

نوشته‌شده توسط 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