نام (NAME)

stap-exporter - سازوکار تعامل‌پذیری میان systemtap و prometheus

خلاصه دستور (SYNOPSIS)

stap-exporter [ گزینه‌ها ]

توضیحات (DESCRIPTION)

ابزار stap-exporter مجموعه‌ای از اسکریپت‌های systemtap را اجرا کرده و خروجی‌های procfs آن‌ها را بر حسب تقاضا به کلاینت‌های راه دور HTTP منتقل می‌کند. این امر باعث می‌شود اسکریپت‌های systemtap مستقیماً به‌عنوان صادرکننده‌های مجزای prometheus قابل استفاده باشند. این قابلیت به کمک مجموعه‌ای از ماکروها که در فایل tapset با نام prometheus.stpm فراهم شده‌اند، پشتیبانی می‌شود.

گزینه‌ها (OPTIONS)

برنامه stap-exporter از گزینه‌های زیر پشتیبانی می‌کند:

-p --port PORT: گوش دادن به درگاه (پورت) مشخص‌شده TCP برای دریافت درخواست‌های HTTP. به‌طور پیش‌فرض از پورت ۹۹۰۰ استفاده می‌شود.
-k --keepalive KEEPALIVE: اسکریپت‌هایی که پس از دریافت آخرین درخواست، بیش از KEEPALIVE ثانیه اجرا شوند خاموش و متوقف می‌شوند. به‌طور پیش‌فرض هیچ زمان انتظاری (timeout) وجود ندارد، بنابراین اسکریپت‌ها پس از شروع همواره در حال اجرا باقی می‌مانند.
-s --scripts SCRIPTS: جستجوی دایرکتوری SCRIPTS برای فایل‌های *.stp جهت عرضه و ارائه. مقدار پیش‌فرض در صفحه راهنمای stappaths(7) آمده است.
-h --help: چاپ پیام راهنما.

نحوه عملکرد (OPERATION)

هنگام راه‌اندازی، stap-exporter دایرکتوری مشخص‌شده با گزینه -s را برای یافتن فایل‌هایی با نام *.stp جستجو می‌کند. نام هر فایل به‌عنوان بخشی از نشانی اینترنتی (URL) برای درخواست‌های بعدی HTTP GET در دسترس قرار می‌گیرد. برای نمونه، هنگامی که یک کلاینت HTTP درخواست /foo.stp را ارسال می‌کند و اسکریپت foo.stp (فایل اجرایی / اسکریپت شل) شناخته‌شده باشد، با گزینه‌های اضافی stap برای تعیین نام ماژول فراخوانی و اجرا می‌شود. این نام ماژول قابل پیش‌بینی، به stap-exporter امکان می‌دهد تا فایل procfs حاصل از آن اسکریپت در حال اجرا را برای کلاینت‌های HTTP رونویسی کند.

پس از سپری شدن یک دوره عدم استفاده قابل تنظیم (گزینه -k یا --keepalive)، اسکریپت systemtap متوقف می‌شود. در صورت ارسال درخواست جدید از سوی کلاینت، اسکریپت دوباره راه‌اندازی خواهد شد.

تمامی فایل‌هایی که نام آن‌ها شامل زیررشته autostart باشد، بلافاصله آغاز به کار می‌کنند (و در صورت توقف، مجدداً راه‌اندازی می‌شوند) و اجرای آن‌ها بر حسب تقاضا نخواهد بود. این موارد از محاسبات keepalive مستثنی هستند. اسکریپت‌هایی که ممکن است راه‌اندازی آن‌ها بسیار کند باشد یا تمایل داشته باشند آمارهای بلندمدت ارائه دهند، گزینه‌های مناسبی برای این سازوکار هستند.

مثال‌ها (EXAMPLES)

فرض کنید پرونده example.stp شامل اسکریپت زیر باشد. این اسکریپت فراخوانی‌های سیستمی read را بر مبنای هر ریسه (thread) و هر پردازنده (cpu) شمارش می‌کند.

global arr%
probe syscall.read {
    arr[tid(), cpu()]++
}
probe prometheus {
    @prometheus_dump_array2(arr, "count", "tid", "cpu")
}

ماکروهای prometheus_dump_array برای ایجاد متریک‌ها از یک آرایه به کار می‌روند. ابزار Systemtap ماکروهای prometheus_dump_arrayN را به ازای تمامی مقادیر N از ۱ تا ۸ فراهم می‌کند. آرگومان نخست این ماکروها بیانگر یک آرایه با کلیدهای N-عنصری است. آرگومان دوم نشان‌دهنده نام متریک است. باقی‌مانده N آرگومان دیگر، نمایانگر نام برچسب‌های متریک هستند.

کاربر می‌تواند stap-exporter را با دسترسی کاربر ریشه (root) یا با امتیازات معادل stapdev اجرا کند، سپس پس از وقفه‌ای کوتاه، از هر کلاینت وبی برای دریافت داده‌ها بهره ببرد:

# stap-exporter -p 9999 -k 60 -c . &
$ curl http://localhost:9999/example.stp
Refresh page to access metrics.  [...]
$ curl http://localhost:9999/example.stp
count{tid="12614",cpu="0"} 9
count{tid="12170",cpu="3"} 107
count{tid="1802",cpu="0"} 33687
count{tid="12617",cpu="1"} 99
[...]

همین نشانی URL را می‌توان به بخش scrape_config در سرور Prometheus یا دایرکتوری config.d مربوط به pmdaprometheus در Performance Co-Pilot افزود تا این داده‌ها در یک سامانه نظارتی جمع‌آوری شوند.

امنیت و ایمنی (SAFETY AND SECURITY)

سرور stap-exporter هیچ سازوکار امنیتی خاصی را اعمال نمی‌کند. بنابراین، استقرار آن در یک محیط غیرقابل اعتماد نیازمند در نظر گرفتن موارد زیر است:

انتخاب اسکریپت (script selection): از آنجا که اسکریپت‌های systemtap تحت اختیارات و مجوزهای فرایند stap-exporter (احتمالاً کاربر ریشه یا root) اجرا می‌شوند، مدیر سیستم باید تنها اسکریپت‌های ایمن و قابل‌اطمینان را انتخاب کند. پیش از فعال‌سازی سرویس، اسکریپت‌های نصب‌شده به‌صورت پیش‌فرض را بررسی کنید. اسکریپت‌ها نمی‌توانند از کلاینت‌های وب ورودی دریافت کنند.
دیواره آتش TCP/IP (فایروال): از آنجا که stap-exporter پورت انتخابی TCP/HTTP را روی تمامی رابط‌های شبکه میزبان در دسترس قرار می‌دهد، ممکن است افزودن دیواره آتش (firewall) ضروری باشد. بعید است قرار دادن چنین سرویسی در معرض یک شبکه غیرقابل اعتماد، اقدام مناسبی باشد.
پالایش HTTP (فیلتر کردن): از آنجا که stap-exporter اسکریپت‌های پیکربندی‌شده systemtap را بدون هیچ‌گونه احراز هویت در اختیار تمام کلاینت‌های HTTP قرار می‌دهد، محافظت از آن در برابر سوءاستفاده حتی در شبکه‌های عمدتاً مورد اعتماد نیز ممکن است ضروری باشد. می‌توان از یک پروکسی HTTP برای اعمال فیلترهای وابسته به نشانی اینترنتی (URL)، کلاینت، نحوه استفاده یا احراز هویت استفاده کرد.
پروتکل HTTPS: از آنجا که stap-exporter صرفاً با پروتکل متنی ساده HTTP ارتباط برقرار می‌کند، می‌توان از یک پروکسی معکوس HTTP برای پشتیبانی از پروتکل‌های امنیتی HTTPS بهره گرفت.

همچنین ببینید (SEE ALSO)

stap(1)، stapprobes(3stap)، stappaths(7)، tapset::prometheus(7)

اشکالات (BUGS)

از پیوند باگزیلا در صفحه وب پروژه یا فهرست پستی ما استفاده کنید. http://sourceware.org/systemtap، <systemtap@sourceware.org>.

error::reporting(7stap)، https://sourceware.org/systemtap/wiki/HowToReportBugs