| mono-profilers(1) | General Commands Manual | mono-profilers(1) |
نام (NAME)
mono-profilers - ماژول‌های پروفایلر همراه Mono
خلاصه دستور (SYNOPSIS)
mono --profile=log[:option,...] program.exe [args]...
mono --profile=coverage[:option,...] program.exe [args]...
mono --profile=aot[:option,...] program.exe [args]...
توضیحات (DESCRIPTION)
پروژه Mono همراه با چند ماژول پروفایلر (تحلیل‌گر کارایی) عرضه می‌شود که اغلب سناریوهای رایج ارزیابی کارایی را پوشش می‌دهند. این صفحه هر یک از آن‌ها را در بخش‌های زیر شرح می‌دهد.
پروفایلر لاگ (LOG PROFILER)
پروفایلر log، پروفایلر همه‌منظوره سنجش کارایی در Mono است. این ابزار می‌تواند طیف گسترده‌ای از داده‌ها را گردآوری کند که توسط ابزارهایی مانند mprof-report(1) یا Xamarin Profiler قابل تحلیل هستند.
به‌طور پیش‌فرض، پروفایلر log خروجی خود را در output.mlpd می‌نویسد. برای مشاهده مستندات مربوط به قالب فایل پروفایلر log، به فایل mono/profiler/log.h در درخت منبع Mono مراجعه کنید.
اجرای پیش‌فرض پروفایلر log تنها داده‌های پایه‌ای را گردآوری می‌کند: رویدادهای بارگذاری و تخلیه فراداده (Metadata)، رویدادهای شروع و پایان ریسه‌ها (Thread)، نمونه‌های شمارنده کارایی (Performance counter)، پرتاب استثناها (Exception throw) و غیره. بیشتر کاربران مایل به فعال‌سازی برخی از قابلیت‌های سنگین‌تر هستند؛ مانند ثبت تخصیص‌های GC، نمونه‌برداری آماری، تصویربرداری از حافظه هِیپ (heapshots)، یا ابزارگذاری ورود و خروج متدها. زیربخش گزینه‌ها (OPTIONS) را ببینید.
توجه داشته باشید که در اکثر سناریوهای واقعی، پروفایلر log حجم عظیمی از داده‌ها را ضبط خواهد کرد. این امر می‌تواند منجر به فایل‌های گزارش بسیار حجیم شود. (گزینه‌های zip و report می‌توانند در مدیریت این موضوع کمک کنند.)
گزینه‌ها (OPTIONS)
پروفایلر log از گزینه‌های زیر پشتیبانی می‌کند:
- help
- دستورالعمل‌های نحوه استفاده را نمایش می‌دهد.
- output=[+|#||]file
- داده‌های لاگ را در file می‌نویسد. اصلاح‌کننده‌های اختیاری عبارتند از:
- +
- شناسه فرایند (PID) برنامه به نام فایل پیوست می‌شود. برای مثال، اگر PID برابر 1234 باشد، مقدار output=+out.mlpd خروجی را در out.mlpd.1234 می‌نویسد.
- #
- مقدار file به عنوان شماره توصیف‌کننده فایل (File descriptor) پردازش شده و با fdopen(3) باز می‌شود. این حالت عمدتاً در سناریوهای تعبیه‌شده (embedding) مفید است.
- |
- مقدار file به عنوان نام یک برنامه در نظر گرفته می‌شود. این برنامه با popen(3) اجرا شده و داده‌های لاگ به ورودی استاندارد آن هدایت (pipe) می‌شوند.
- report
- به جای نوشتن داده‌های لاگ در یک فایل، مستقیماً گزارش تولید می‌کند. اگر این گزینه همراه با گزینه output استفاده شود، گزارش به جای داده‌های خام لاگ در فایل مشخص‌شده نوشته خواهد شد.
- zip
- فایل خروجی را با استفاده از gzip(1) فشرده می‌کند.
- port=port
- از port برای گوش دادن به اتصالات سرور فرمان استفاده می‌کند. زیربخش سرور فرمان (Command server) را ببینید.
- nodefaults
- سازگاری با نسخه‌های پیش از Mono 5.6 را غیرفعال می‌کند. به‌طور خاص، این گزینه رویدادهای استثنا و نمونه‌برداری از شمارنده کارایی را به‌طور پیش‌فرض غیرفعال می‌سازد. همچنین باعث می‌شود هنگام فعال بودن heapshotها، رویدادهای جابجایی GC به‌طور پیش‌فرض فعال نشوند. برای استفاده از این گزینه، باید اولین گزینه‌ای باشد که به پروفایلر log داده می‌شود.
- این گزینه در نسخه‌های آینده پروفایلر log به عنوان پیش‌فرض در نظر گرفته خواهد شد.
- [no]event
- فعال یا غیرفعال کردن گردآوری داده‌ها برای رویداد event، که می‌تواند یکی از موارد زیر باشد:
- exception
- رویدادهای پرتاب استثنا و ارزیابی بندها (catch، finally و غیره). به‌طور پیش‌فرض فعال است مگر اینکه از nodefaults استفاده شود.
- monitor
- رویدادهای رقابت بر سر قفل، تصاحب و آزادسازی مانتیور (Monitor lock).
- gc
- رویدادهای شروع، پیشرفت، توقف و تغییر اندازه زباله‌روب (GC).
- gcalloc
- رویدادهای تخصیص حافظه GC.
- gcmove
- رویدادهای جابجایی اشیاء در GC.
- gcroot
- رویدادهای گزارش ریشه GC (یا GC root). در صورت فعال بودن در هر دوره بازیافت حافظه ایجاد می‌شوند، مگر اینکه nodefaults استفاده شود که در این صورت تنها هنگام heapshotها تولید خواهند شد.
- gchandle
- رویدادهای ایجاد و حذف دسته‌های GC (یا GC handle).
- finalization
- رویدادهای نهایی‌سازی اشیاء (Object finalization).
- counter
- رویدادهای نمونه‌برداری از شمارنده‌های کارایی. به‌طور پیش‌فرض فعال است مگر اینکه از nodefaults استفاده شود.
- jit
- رویدادهای بافر کد JIT.
- alloc
- نام مستعار برای gc، gcalloc و gcmove.
- legacy
- نام مستعار برای exception، monitor، gc، gcmove، gcroot، gchandle، finalization و counter.
- sample[-real][=freq]
- فعال‌سازی نمونه‌برداری آماری. حالت پیش‌فرض، نمونه‌برداری با بسامد ۱۰۰ هرتز (100 Hz) است، اما می‌توان از freq برای بازنویسی این مقدار استفاده کرد.
- به‌طور پیش‌فرض، نمونه‌برداری بر اساس زمان پردازش (process time) انجام می‌شود (یعنی هر چه فرایند کار بیشتری انجام دهد، نمونه‌های بیشتری جمع‌آوری می‌شود). نسخه -real به جای آن از زمان واقعی ساعت دیواری (wall clock time) استفاده می‌کند. زمان واقعی برای برنامه‌هایی که درگیر عملیات ورودی/خروجی (I/O-bound) هستند مناسب‌تر است.
- maxsamples=num
- تعداد رویدادهای نمونه قابل استفاده مجدد را به num تخصیص محدود می‌کند. مقدار صفر به معنای عدم وجود محدودیت است. به‌طور پیش‌فرض، مقدار این تنظیم بر اساس تعداد هسته‌های پردازنده (CPU) تعیین می‌شود. دستکاری این مقدار ممکن است برای برنامه‌هایی با تعداد نامتعارف و بسیار زیادی از ریسه‌ها لازم باشد.
- calls
- فعال‌سازی ابزارگذاری ورود و خروج متدها. این گزینه جایگزینی برای نمونه‌برداری آماری در زمان نیاز به اطلاعات دقیق‌تر است. توجه داشته باشید که این حالت بسیار سنگین است و می‌تواند سرعت اجرای اغلب برنامه‌ها را به شدت کاهش دهد.
- callspec=spec
- ابزارگذاری ورود و خروج متدها را به متدهایی محدود می‌کند که با الگوی فراخوانی (call spec) مشخص‌شده مطابقت داشته باشند. این ساختار از همان نحو گزینه --trace در mono(1) استفاده می‌کند؛ برای اطلاعات بیشتر به آن صفحه مراجعه کنید.
- calldepth=num
- گردآوری رویدادهای ورود و خروج متد را به عمق فراخوانی num محدود می‌کند.
- maxframes=num
- ردیابی پشته (backtrace) در رویدادهای مختلف (از جمله نمونه‌های آماری) را به num فریم محدود می‌کند.
- heapshot[=mode]
- فعال‌سازی تصویربرداری از حافظه هِیپ (heap snapshots). در صورت ارائه، mode می‌تواند یکی از مقادیر زیر باشد:
- ondemand
- تنها زمانی اقدام به تهیه heapshot می‌کند که فرمانی از طریق سرور فرمان دریافت شود یا از طریق کتابخانه مدیریت‌شده (managed library) تحریک گردد.
- numgc
- به ازای هر num بار بازیافت حافظه در نسل اصلی (major generation)، یک heapshot تهیه می‌کند.
- numms
- در زمان بازیافت حافظه در نسل اصلی، چنانچه num میلی‌ثانیه از آخرین heapshot گذشته باشد، یک heapshot جدید تهیه می‌کند.
- اگر mode تعیین نشود، به ازای هر بار بازیافت حافظه در نسل اصلی، یک heapshot انجام خواهد شد..TP heapshot-on-shutdown علاوه بر هرگونه تنظیمات دیگر heapshot، هنگام خاموش‌شدن زمان‌اجرا (runtime shutdown) نیز یک heapshot تهیه می‌کند.
- debug
- اطلاعات تفصیلی اشکال‌زدایی را چاپ می‌کند. بیشتر کاربران نباید از این گزینه استفاده کنند.
سرور فرمان (Command server)
پروفایلر لاگ (log profiler) شامل یک سرور فرمان ساده است که در حال حاضر تنها برای آغاز دستی heapshotها استفاده می‌شود (معمولاً هنگام استفاده از حالت برحسب تقاضا (on-demand)، اما با سایر حالت‌ها نیز قابل استفاده است). یک پورت تصادفی برای گوش دادن به اتصالات استفاده خواهد شد، مگر اینکه از گزینه port استفاده شود. برای ایجاد یک heapshot، یک اتصال TCP به سرور فرمان باز کرده و رشته زبان C با مقدار "heapshot\n" را ارسال کنید.
سرور فرمان از چندین اتصال هم‌زمان پشتیبانی می‌کند.
کتابخانه مدیریت‌شده (Managed library)
پروفایلر لاگ به همراه یک کتابخانه مدیریت‌شده به نام Mono.Profiler.Log ارائه می‌شود. این کتابخانه امکان خواندن آسان فایل‌های لاگ را در کد مدیریت‌شده (مانند #C) و همچنین تعامل با پروفایلر در زمان اجرا (run-time) فراهم می‌کند.
با قابلیت خواندن آسان فایل‌های لاگ، کاربران می‌توانند انواع تحلیل‌های جالب توجهی را بنویسند که ممکن است توسط ابزارهای استاندارد (مانند mprof-report(1)) ارائه نشده باشند.
کلاس LogProfiler به کاربران اجازه می‌دهد تنظیمات پروفایلر را در زمان اجرا مجدداً پیکربندی کنند. برای مثال، انواع خاصی از رویدادها را می‌توان فعال یا غیرفعال کرد، حالت و بسامد heapshotها و نمونه‌برداری (sampling) را تغییر داد، و غیره. همچنین می‌توان heapshotها را به صورت دستی آغاز کرد.
برای استفاده از این کتابخانه، کافی است هنگام کامپایل کردن کد خود، -r:Mono.Profiler.Log را اضافه کنید.
مثال (EXAMPLE)
جمع‌آوری داده‌های تخصیص حافظه GC و نمونه‌برداری برای یک برنامه، و سپس تولید یک گزارش:
mono --profile=log:alloc,sample program.exe mprof-report output.mlpd
تهیه یک heapshot به ازای هر ۵ بار بازیافت حافظه (collection) و تولید مستقیم گزارش:
mono --profile=log:heapshot=5gc,report program.exe
پروفایلر پوشش کد (COVERAGE PROFILER)
پروفایلر پوشش کد (code coverage profiler) اطلاعاتی را درباره دفعات اجرای مسیرهای مختلف کد جمع‌آوری می‌کند. این کار با سنجش‌پذیر کردن (instrumenting) کد کامپایل‌شده توسط JIT در تمامی نقاط توالی (sequence points) انجام می‌شود. هنگام خروج برنامه، پروفایلر پوشش تمام اطلاعات شمارش دفعات اجرا را جمع‌آوری کرده و در یک فایل XML خروجی می‌دهد. کاربرد اصلی پروفایلر پوشش در آزمون واحد (unit testing) است: با اجرای مجموعه‌های آزمون واحد همراه با پروفایلر پوشش، می‌توان مشخص کرد که آیا آزمون‌های واحد واقعاً تمام کدی را که باید، پوشش می‌دهند یا خیر.
به طور پیش‌فرض، پروفایلر پوشش خروجی خود را در coverage.xml می‌نویسد. برای مستندات مربوط به ساختار (schema)، به فایل mono/profiler/coverage.c در درخت سورس Mono مراجعه کنید.
لطفاً توجه داشته باشید که پروفایلر پوشش در حال حاضر از سنجش‌پذیر کردن کدهای کامپایل‌شده با روش AOT پشتیبانی نمی‌کند. هنگام جمع‌آوری داده‌های پوشش، ممکن است بخواهید Mono را با گزینه -O=-aot اجرا کنید تا بارگذاری کدهای کامپایل‌شده با AOT غیرفعال شود.
گزینه‌ها (OPTIONS)
پروفایلر پوشش از گزینه‌های زیر پشتیبانی می‌کند:
- help
- چاپ دستورالعمل‌های استفاده.
- output=[+|#||]file
- نوشتن داده‌های پوشش در file. تغییردهنده‌های اختیاری عبارتند از:
- +
- شناسه فرایند (PID) برنامه به انتهای نام فایل اضافه می‌شود. برای مثال، اگر PID برابر با 1234 باشد، output=+cov.xml خروجی را در cov.xml.1234 می‌نویسد.
- #
- file به عنوان یک شماره توصیف‌گر فایل (file descriptor) در نظر گرفته می‌شود که با fdopen(3) باز می‌شود. این قابلیت عمدتاً در سناریوهای تعبیه‌شده (embedding) کاربرد دارد.
- |
- با file مانند نام یک برنامه رفتار می‌شود. این برنامه با popen(3) اجرا شده و داده‌های پوشش به ورودی استاندارد آن هدایت (pipe) خواهند شد.
- covfilter-file=file
- ارائه یک فایل فیلتر پوشش. این گزینه می‌تواند چندین بار مشخص شود. زیربخش فایل‌های فیلتر (Filter files) را ببینید..SS "فایل‌های فیلتر (Filter files)" از فایل‌های فیلتر می‌توان برای انتخاب اینکه چه نوع‌هایی (types) باید برای ابزارگذاری پوشش (coverage instrumentation) در نظر گرفته شوند، استفاده کرد. یک فایل فیلتر از مجموعه‌ای از خطوط به شکل زیر تشکیل شده است:
+|-[image_name]type_name_prefix
در اینجا، image_name چیزی شبیه به mscorlib است. type_name_prefix می‌تواند مانند System.Int32 برای یک نوع خاص، یا System.App برای انتخاب تمامی نوع‌هایی باشد که در فضای‌نام System با App آغاز می‌شوند.
خطوطی که با + آغاز می‌شوند نشان می‌دهند که یک نوع باید برای پوشش ابزارگذاری شود، در حالی که خطوط شروع‌شده با - خلاف آن را مشخص می‌کنند. خطوط شروع‌شده با +، صرف‌نظر از ترتیبی که در آن ظاهر شده‌اند، همواره خطوط شروع‌شده با - را نادیده گرفته و جایگزین (override) می‌کنند.
خطوطی که با هیچ‌کدام از این دو نویسه آغاز نمی‌شوند نادیده گرفته خواهند شد. از این قابلیت می‌توان برای نوشتن کامنت‌ها استفاده کرد. برای مثال، این یک فایل معتبر است:
# Ignore coverage in network-related code, except HTTP client code. -[MyProgram]MyProgram.Net +[MyProgram]MyProgram.Net.Http.HttpClient
مثال (EXAMPLE)
داده‌های پوشش برای یک برنامه را می‌توان به این صورت جمع‌آوری کرد:
mono -O=-aot --profile=coverage:output=cov.xml program.exe
اکنون فایل cov.xml حاوی داده‌های پوشش خواهد بود.
پروفایلر AOT (AOT PROFILER)
پروفایلر AOT نمونه‌سازی‌های جنریک (generic instantiations) مورد استفاده برنامه را ثبت کرده و این اطلاعات را در یک فایل مشخص ذخیره می‌کند. سپس کامپایلر AOT می‌تواند از این داده‌ها برای کامپایل پیش‌هنگام (ahead of time) آن نمونه‌سازی‌های جنریک استفاده کند تا زمان راه‌اندازی برنامه کاهش یابد.
به‌طور پیش‌فرض، پروفایلر AOT خروجی خود را در output.aotprofile می‌نویسد. برای مشاهده مستندات مربوط به قالب فایل پروفایلر AOT، به فایل mono/profiler/aot.h در درخت کد منبع Mono مراجعه کنید.
گزینه‌ها (OPTIONS)
پروفایلر AOT از گزینه‌های زیر پشتیبانی می‌کند:
- duration=num
- تنها num ثانیه از زمان اجرا را پروفایل کرده و سپس داده‌ها را می‌نویسد.
- help
- دستورالعمل‌های نحوه استفاده را چاپ می‌کند.
- output=[+|#||]file
- داده‌های خروجی را در file می‌نویسد. تغییردهنده‌های اختیاری عبارت‌اند از:
- +
- شناسه فرایند (PID) برنامه به انتهای نام فایل اضافه می‌شود. برای مثال، اگر PID برابر 1234 باشد، output=+out.aotprofile خروجی را در out.aotprofile.1234 می‌نویسد.
- #
- file به عنوان یک شماره توصیف‌گر فایل (file descriptor) تفسیر شده که با fdopen(3) باز می‌شود. این حالت عمدتاً در سناریوهای تعبیه‌شده (embedding) کاربرد دارد.
- |
- با file به عنوان نام یک برنامه رفتار می‌شود. برنامه با popen(3) اجرا شده و داده‌های گزارش (log) به ورودی استاندارد آن هدایت (pipe) خواهند شد.
- verbose
- اطلاعات دقیق اشکال‌زدایی را چاپ می‌کند. بیشتر کاربران نباید از این گزینه استفاده کنند..SS "مثال (EXAMPLE)" یک پروفایل را می‌توان به این صورت جمع‌آوری و استفاده کرد:
mono --profile=aot:output=program.aotprofile program.exe mono --aot=profile=program.aotprofile program.exe mono program.exe