.TH mono-profilers 1
.SH "نام (NAME)"
mono\-profilers \- ماژول‌های پروفایلر همراه Mono
.SH "خلاصه دستور (SYNOPSIS)"
\fBmono\ \-\-profile=log\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]...
.PP
\fBmono\ \-\-profile=coverage\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]...
.PP
\fBmono\ \-\-profile=aot\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]...
.SH "توضیحات (DESCRIPTION)"
پروژه Mono همراه با چند ماژول پروفایلر (تحلیل‌گر کارایی) عرضه می‌شود که اغلب سناریوهای رایج ارزیابی کارایی را پوشش می‌دهند. این صفحه هر یک از آن‌ها را در بخش‌های زیر شرح می‌دهد.
.SH "پروفایلر لاگ (LOG PROFILER)"
پروفایلر log، پروفایلر همه‌منظوره سنجش کارایی در Mono است. این ابزار می‌تواند طیف گسترده‌ای از داده‌ها را گردآوری کند که توسط ابزارهایی مانند \fBmprof\-report\fR(1) یا Xamarin Profiler قابل تحلیل هستند.
.PP
به‌طور پیش‌فرض، پروفایلر log خروجی خود را در \fIoutput.mlpd\fR می‌نویسد. برای مشاهده مستندات مربوط به قالب فایل پروفایلر log، به فایل \fImono/profiler/log.h\fR در درخت منبع Mono مراجعه کنید.
.PP
اجرای پیش‌فرض پروفایلر log تنها داده‌های پایه‌ای را گردآوری می‌کند: رویدادهای بارگذاری و تخلیه فراداده (Metadata)، رویدادهای شروع و پایان ریسه‌ها (Thread)، نمونه‌های شمارنده کارایی (Performance counter)، پرتاب استثناها (Exception throw) و غیره. بیشتر کاربران مایل به فعال‌سازی برخی از قابلیت‌های سنگین‌تر هستند؛ مانند ثبت تخصیص‌های GC، نمونه‌برداری آماری، تصویربرداری از حافظه هِیپ (heapshots)، یا ابزارگذاری ورود و خروج متدها. زیربخش \fBگزینه‌ها (OPTIONS)\fR را ببینید.
.PP
توجه داشته باشید که در اکثر سناریوهای واقعی، پروفایلر log حجم عظیمی از داده‌ها را ضبط خواهد کرد. این امر می‌تواند منجر به فایل‌های گزارش بسیار حجیم شود. (گزینه‌های \fBzip\fR و \fBreport\fR می‌توانند در مدیریت این موضوع کمک کنند.)
.SS "گزینه‌ها (OPTIONS)"
پروفایلر log از گزینه‌های زیر پشتیبانی می‌کند:
.TP
\fBhelp\fR
دستورالعمل‌های نحوه استفاده را نمایش می‌دهد.
.TP
\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR
داده‌های لاگ را در \fIfile\fR می‌نویسد. اصلاح‌کننده‌های اختیاری عبارتند از:
.RS
.ne 8
.TP
\fB+\fR
شناسه فرایند (PID) برنامه به نام فایل پیوست می‌شود. برای مثال، اگر PID برابر \fB1234\fR باشد، مقدار \fBoutput=+out.mlpd\fR خروجی را در \fIout.mlpd.1234\fR می‌نویسد.
.TP
\fB#\fR
مقدار \fIfile\fR به عنوان شماره توصیف‌کننده فایل (File descriptor) پردازش شده و با \fBfdopen\fR(3) باز می‌شود. این حالت عمدتاً در سناریوهای تعبیه‌شده (embedding) مفید است.
.TP
\fB|\fR
مقدار \fIfile\fR به عنوان نام یک برنامه در نظر گرفته می‌شود. این برنامه با \fBpopen\fR(3) اجرا شده و داده‌های لاگ به ورودی استاندارد آن هدایت (pipe) می‌شوند.
.RE
.TP
\fBreport\fR
به جای نوشتن داده‌های لاگ در یک فایل، مستقیماً گزارش تولید می‌کند. اگر این گزینه همراه با گزینه \fBoutput\fR استفاده شود، گزارش به جای داده‌های خام لاگ در فایل مشخص‌شده نوشته خواهد شد.
.TP
\fBzip\fR
فایل خروجی را با استفاده از \fBgzip\fR(1) فشرده می‌کند.
.TP
\fBport\fR=\fIport\fR
از \fIport\fR برای گوش دادن به اتصالات سرور فرمان استفاده می‌کند. زیربخش \fBسرور فرمان (Command server)\fR را ببینید.
.TP
\fBnodefaults\fR
سازگاری با نسخه‌های پیش از Mono 5.6 را غیرفعال می‌کند. به‌طور خاص، این گزینه رویدادهای استثنا و نمونه‌برداری از شمارنده کارایی را به‌طور پیش‌فرض غیرفعال می‌سازد. همچنین باعث می‌شود هنگام فعال بودن heapshotها، رویدادهای جابجایی GC به‌طور پیش‌فرض فعال نشوند. برای استفاده از این گزینه، باید اولین گزینه‌ای باشد که به پروفایلر log داده می‌شود.
.IP
این گزینه در نسخه‌های آینده پروفایلر log به عنوان پیش‌فرض در نظر گرفته خواهد شد.
.TP
[\fBno\fR]\fIevent\fR
فعال یا غیرفعال کردن گردآوری داده‌ها برای رویداد \fIevent\fR، که می‌تواند یکی از موارد زیر باشد:
.RS
.TP
\fBexception\fR
رویدادهای پرتاب استثنا و ارزیابی بندها (\fBcatch\fR، \fBfinally\fR و غیره). به‌طور پیش‌فرض فعال است مگر اینکه از \fBnodefaults\fR استفاده شود.
.TP
\fBmonitor\fR
رویدادهای رقابت بر سر قفل، تصاحب و آزادسازی مانتیور (Monitor lock).
.TP
\fBgc\fR
رویدادهای شروع، پیشرفت، توقف و تغییر اندازه زباله‌روب (GC).
.TP
\fBgcalloc\fR
رویدادهای تخصیص حافظه GC.
.TP
\fBgcmove\fR
رویدادهای جابجایی اشیاء در GC.
.TP
\fBgcroot\fR
رویدادهای گزارش ریشه GC (یا GC root). در صورت فعال بودن در هر دوره بازیافت حافظه ایجاد می‌شوند، مگر اینکه \fBnodefaults\fR استفاده شود که در این صورت تنها هنگام heapshotها تولید خواهند شد.
.TP
\fBgchandle\fR
رویدادهای ایجاد و حذف دسته‌های GC (یا GC handle).
.TP
\fBfinalization\fR
رویدادهای نهایی‌سازی اشیاء (Object finalization).
.TP
\fBcounter\fR
رویدادهای نمونه‌برداری از شمارنده‌های کارایی. به‌طور پیش‌فرض فعال است مگر اینکه از \fBnodefaults\fR استفاده شود.
.TP
\fBjit\fR
رویدادهای بافر کد JIT.
.TP
\fBalloc\fR
نام مستعار برای \fBgc\fR، \fBgcalloc\fR و \fBgcmove\fR.
.TP
\fBlegacy\fR
نام مستعار برای \fBexception\fR، \fBmonitor\fR، \fBgc\fR، \fBgcmove\fR، \fBgcroot\fR، \fBgchandle\fR، \fBfinalization\fR و \fBcounter\fR.
.RE
.TP
\fBsample\fR[\fB\-real\fR][=\fIfreq\fR]
فعال‌سازی نمونه‌برداری آماری. حالت پیش‌فرض، نمونه‌برداری با بسامد ۱۰۰ هرتز (100 Hz) است، اما می‌توان از \fIfreq\fR برای بازنویسی این مقدار استفاده کرد.
.IP
به‌طور پیش‌فرض، نمونه‌برداری بر اساس زمان پردازش (process time) انجام می‌شود (یعنی هر چه فرایند کار بیشتری انجام دهد، نمونه‌های بیشتری جمع‌آوری می‌شود). نسخه \fB-real\fR به جای آن از زمان واقعی ساعت دیواری (wall clock time) استفاده می‌کند. زمان واقعی برای برنامه‌هایی که درگیر عملیات ورودی/خروجی (I/O-bound) هستند مناسب‌تر است.
.TP
\fBmaxsamples\fR=\fInum\fR
تعداد رویدادهای نمونه قابل استفاده مجدد را به \fInum\fR تخصیص محدود می‌کند. مقدار صفر به معنای عدم وجود محدودیت است. به‌طور پیش‌فرض، مقدار این تنظیم بر اساس تعداد هسته‌های پردازنده (CPU) تعیین می‌شود. دستکاری این مقدار ممکن است برای برنامه‌هایی با تعداد نامتعارف و بسیار زیادی از ریسه‌ها لازم باشد.
.TP
\fBcalls\fR
فعال‌سازی ابزارگذاری ورود و خروج متدها. این گزینه جایگزینی برای نمونه‌برداری آماری در زمان نیاز به اطلاعات دقیق‌تر است. توجه داشته باشید که این حالت بسیار سنگین است و می‌تواند سرعت اجرای اغلب برنامه‌ها را به شدت کاهش دهد.
.TP
\fBcallspec\fR=\fIspec\fR
ابزارگذاری ورود و خروج متدها را به متدهایی محدود می‌کند که با الگوی فراخوانی (call spec) مشخص‌شده مطابقت داشته باشند. این ساختار از همان نحو گزینه \fB--trace\fR در \fBmono\fR(1) استفاده می‌کند؛ برای اطلاعات بیشتر به آن صفحه مراجعه کنید.
.TP
\fBcalldepth\fR=\fInum\fR
گردآوری رویدادهای ورود و خروج متد را به عمق فراخوانی \fInum\fR محدود می‌کند.
.TP
\fBmaxframes\fR=\fInum\fR
ردیابی پشته (backtrace) در رویدادهای مختلف (از جمله نمونه‌های آماری) را به \fInum\fR فریم محدود می‌کند.
.TP
\fBheapshot\fR[=\fImode\fR]
فعال‌سازی تصویربرداری از حافظه هِیپ (heap snapshots). در صورت ارائه، \fImode\fR می‌تواند یکی از مقادیر زیر باشد:
.RS
.TP
\fBondemand\fR
تنها زمانی اقدام به تهیه heapshot می‌کند که فرمانی از طریق سرور فرمان دریافت شود یا از طریق کتابخانه مدیریت‌شده (managed library) تحریک گردد.
.TP
\fInum\fR\fBgc\fR
به ازای هر \fInum\fR بار بازیافت حافظه در نسل اصلی (major generation)، یک heapshot تهیه می‌کند.
.TP
\fInum\fR\fBms\fR
در زمان بازیافت حافظه در نسل اصلی، چنانچه \fInum\fR میلی‌ثانیه از آخرین heapshot گذشته باشد، یک heapshot جدید تهیه می‌کند.
.RE
.IP
اگر \fImode\fR تعیین نشود، به ازای هر بار بازیافت حافظه در نسل اصلی، یک heapshot انجام خواهد شد..TP
\fBheapshot-on-shutdown\fR
علاوه بر هرگونه تنظیمات دیگر heapshot، هنگام خاموش‌شدن زمان‌اجرا (runtime shutdown) نیز یک heapshot تهیه می‌کند.
.TP
\fBdebug\fR
اطلاعات تفصیلی اشکال‌زدایی را چاپ می‌کند. بیشتر کاربران نباید از این گزینه استفاده کنند.
.SS "سرور فرمان (Command server)"
پروفایلر لاگ (log profiler) شامل یک سرور فرمان ساده است که در حال حاضر تنها برای آغاز دستی heapshotها استفاده می‌شود (معمولاً هنگام استفاده از حالت برحسب تقاضا (on-demand)، اما با سایر حالت‌ها نیز قابل استفاده است). یک پورت تصادفی برای گوش دادن به اتصالات استفاده خواهد شد، مگر اینکه از گزینه \fBport\fR استفاده شود. برای ایجاد یک heapshot، یک اتصال TCP به سرور فرمان باز کرده و رشته زبان C با مقدار \fB"heapshot\\n"\fR را ارسال کنید.
.PP
سرور فرمان از چندین اتصال هم‌زمان پشتیبانی می‌کند.
.SS "کتابخانه مدیریت‌شده (Managed library)"
پروفایلر لاگ به همراه یک کتابخانه مدیریت‌شده به نام \fBMono.Profiler.Log\fR ارائه می‌شود. این کتابخانه امکان خواندن آسان فایل‌های لاگ را در کد مدیریت‌شده (مانند #C) و همچنین تعامل با پروفایلر در زمان اجرا (run-time) فراهم می‌کند.
.PP
با قابلیت خواندن آسان فایل‌های لاگ، کاربران می‌توانند انواع تحلیل‌های جالب توجهی را بنویسند که ممکن است توسط ابزارهای استاندارد (مانند \fBmprof\-report\fR(1)) ارائه نشده باشند.
.PP
کلاس \fBLogProfiler\fR به کاربران اجازه می‌دهد تنظیمات پروفایلر را در زمان اجرا مجدداً پیکربندی کنند. برای مثال، انواع خاصی از رویدادها را می‌توان فعال یا غیرفعال کرد، حالت و بسامد heapshotها و نمونه‌برداری (sampling) را تغییر داد، و غیره. همچنین می‌توان heapshotها را به صورت دستی آغاز کرد.
.PP
برای استفاده از این کتابخانه، کافی است هنگام کامپایل کردن کد خود، \fB\-r:Mono.Profiler.Log\fR را اضافه کنید.
.SS "مثال (EXAMPLE)"
جمع‌آوری داده‌های تخصیص حافظه GC و نمونه‌برداری برای یک برنامه، و سپس تولید یک گزارش:
.PP
.nf
.RS
mono \-\-profile=log:alloc,sample program.exe
mprof\-report output.mlpd
.RE
.fi
.PP
تهیه یک heapshot به ازای هر ۵ بار بازیافت حافظه (collection) و تولید مستقیم گزارش:
.PP
.nf
.RS
mono \-\-profile=log:heapshot=5gc,report program.exe
.RE
.fi
.PP
.SH "پروفایلر پوشش کد (COVERAGE PROFILER)"
پروفایلر پوشش کد (code coverage profiler) اطلاعاتی را درباره دفعات اجرای مسیرهای مختلف کد جمع‌آوری می‌کند. این کار با سنجش‌پذیر کردن (instrumenting) کد کامپایل‌شده توسط JIT در تمامی نقاط توالی (sequence points) انجام می‌شود. هنگام خروج برنامه، پروفایلر پوشش تمام اطلاعات شمارش دفعات اجرا را جمع‌آوری کرده و در یک فایل XML خروجی می‌دهد. کاربرد اصلی پروفایلر پوشش در آزمون واحد (unit testing) است: با اجرای مجموعه‌های آزمون واحد همراه با پروفایلر پوشش، می‌توان مشخص کرد که آیا آزمون‌های واحد واقعاً تمام کدی را که باید، پوشش می‌دهند یا خیر.
.PP
به طور پیش‌فرض، پروفایلر پوشش خروجی خود را در \fIcoverage.xml\fR می‌نویسد. برای مستندات مربوط به ساختار (schema)، به فایل \fImono/profiler/coverage.c\fR در درخت سورس Mono مراجعه کنید.
.PP
لطفاً توجه داشته باشید که پروفایلر پوشش در حال حاضر از سنجش‌پذیر کردن کدهای کامپایل‌شده با روش AOT پشتیبانی نمی‌کند. هنگام جمع‌آوری داده‌های پوشش، ممکن است بخواهید Mono را با گزینه \fB-O=-aot\fR اجرا کنید تا بارگذاری کدهای کامپایل‌شده با AOT غیرفعال شود.
.SS "گزینه‌ها (OPTIONS)"
پروفایلر پوشش از گزینه‌های زیر پشتیبانی می‌کند:
.TP
\fBhelp\fR
چاپ دستورالعمل‌های استفاده.
.TP
\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR
نوشتن داده‌های پوشش در \fIfile\fR. تغییردهنده‌های اختیاری عبارتند از:
.RS
.ne 8
.TP
\fB+\fR
شناسه فرایند (PID) برنامه به انتهای نام فایل اضافه می‌شود. برای مثال، اگر PID برابر با \fB1234\fR باشد، \fBoutput=+cov.xml\fR خروجی را در \fIcov.xml.1234\fR می‌نویسد.
.TP
\fB#\fR
\fIfile\fR به عنوان یک شماره توصیف‌گر فایل (file descriptor) در نظر گرفته می‌شود که با \fBfdopen\fR(3) باز می‌شود. این قابلیت عمدتاً در سناریوهای تعبیه‌شده (embedding) کاربرد دارد.
.TP
\fB|\fR
با \fIfile\fR مانند نام یک برنامه رفتار می‌شود. این برنامه با \fBpopen\fR(3) اجرا شده و داده‌های پوشش به ورودی استاندارد آن هدایت (pipe) خواهند شد.
.RE
.TP
\fBcovfilter-file\fR=\fIfile\fR
ارائه یک فایل فیلتر پوشش. این گزینه می‌تواند چندین بار مشخص شود. زیربخش \fBفایل‌های فیلتر (Filter files)\fR را ببینید..SS "فایل‌های فیلتر (Filter files)"
از فایل‌های فیلتر می‌توان برای انتخاب این‌که چه نوع‌هایی (types) باید برای ابزارگذاری پوشش (coverage instrumentation) در نظر گرفته شوند، استفاده کرد. یک فایل فیلتر از مجموعه‌ای از خطوط به شکل زیر تشکیل شده است:
.PP
.nf
.RS
\fB+\fR|\fB\-\fR\fB[\fR\fIimage_name\fR\fB]\fR\fItype_name_prefix\fR
.RE
.fi
.PP
در اینجا، \fIimage_name\fR چیزی شبیه به \fBmscorlib\fR است. \fItype_name_prefix\fR می‌تواند مانند \fBSystem.Int32\fR برای یک نوع خاص، یا \fBSystem.App\fR برای انتخاب تمامی نوع‌هایی باشد که در فضای‌نام \fBSystem\fR با \fBApp\fR آغاز می‌شوند.
.PP
خطوطی که با \fB+\fR آغاز می‌شوند نشان می‌دهند که یک نوع باید برای پوشش ابزارگذاری شود، در حالی که خطوط شروع‌شده با \fB\-\fR خلاف آن را مشخص می‌کنند. خطوط شروع‌شده با \fB+\fR، صرف‌نظر از ترتیبی که در آن ظاهر شده‌اند، همواره خطوط شروع‌شده با \fB\-\fR را نادیده گرفته و جایگزین (override) می‌کنند.
.PP
خطوطی که با هیچ‌کدام از این دو نویسه آغاز نمی‌شوند نادیده گرفته خواهند شد. از این قابلیت می‌توان برای نوشتن کامنت‌ها استفاده کرد. برای مثال، این یک فایل معتبر است:
.PP
.nf
.RS
# Ignore coverage in network-related code, except HTTP client code.
-[MyProgram]MyProgram.Net
+[MyProgram]MyProgram.Net.Http.HttpClient
.RE
.fi
.SS "مثال (EXAMPLE)"
داده‌های پوشش برای یک برنامه را می‌توان به این صورت جمع‌آوری کرد:
.PP
.nf
.RS
mono \-O=\-aot \-\-profile=coverage:output=cov.xml program.exe
.RE
.fi
.PP
اکنون فایل \fIcov.xml\fR حاوی داده‌های پوشش خواهد بود.
.SH "پروفایلر AOT (AOT PROFILER)"
پروفایلر AOT نمونه‌سازی‌های جنریک (generic instantiations) مورد استفاده برنامه را ثبت کرده و این اطلاعات را در یک فایل مشخص ذخیره می‌کند. سپس کامپایلر AOT می‌تواند از این داده‌ها برای کامپایل پیش‌هنگام (ahead of time) آن نمونه‌سازی‌های جنریک استفاده کند تا زمان راه‌اندازی برنامه کاهش یابد.
.PP
به‌طور پیش‌فرض، پروفایلر AOT خروجی خود را در \fIoutput.aotprofile\fR می‌نویسد. برای مشاهده مستندات مربوط به قالب فایل پروفایلر AOT، به فایل \fImono/profiler/aot.h\fR در درخت کد منبع Mono مراجعه کنید.
.SS "گزینه‌ها (OPTIONS)"
پروفایلر AOT از گزینه‌های زیر پشتیبانی می‌کند:
.TP
\fBduration\fR=\fInum\fR
تنها \fInum\fR ثانیه از زمان اجرا را پروفایل کرده و سپس داده‌ها را می‌نویسد.
.TP
\fBhelp\fR
دستورالعمل‌های نحوه استفاده را چاپ می‌کند.
.TP
\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR
داده‌های خروجی را در \fIfile\fR می‌نویسد. تغییردهنده‌های اختیاری عبارت‌اند از:
.RS
.ne 8
.TP
\fB+\fR
شناسه فرایند (PID) برنامه به انتهای نام فایل اضافه می‌شود. برای مثال، اگر PID برابر \fB1234\fR باشد، \fBoutput=+out.aotprofile\fR خروجی را در \fIout.aotprofile.1234\fR می‌نویسد.
.TP
\fB#\fR
\fIfile\fR به عنوان یک شماره توصیف‌گر فایل (file descriptor) تفسیر شده که با \fBfdopen\fR(3) باز می‌شود. این حالت عمدتاً در سناریوهای تعبیه‌شده (embedding) کاربرد دارد.
.TP
\fB|\fR
با \fIfile\fR به عنوان نام یک برنامه رفتار می‌شود. برنامه با \fBpopen\fR(3) اجرا شده و داده‌های گزارش (log) به ورودی استاندارد آن هدایت (pipe) خواهند شد.
.RE
.TP
\fBverbose\fR
اطلاعات دقیق اشکال‌زدایی را چاپ می‌کند. بیشتر کاربران نباید از این گزینه استفاده کنند..SS "مثال (EXAMPLE)"
یک پروفایل را می‌توان به این صورت جمع‌آوری و استفاده کرد:
.PP
.nf
.RS
mono \-\-profile=aot:output=program.aotprofile program.exe
mono \-\-aot=profile=program.aotprofile program.exe
mono program.exe
.RE
.fi
.PP
.SH "همچنین ببینید (SEE ALSO)"
\fBmono\fR(1), \fBmprof\-report\fR(1)