نام (NAME)

pmseries - نمایش اطلاعات درباره سری‌های زمانی معیارهای کارایی

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

pmseries [-adFiIlLmMnqsStvV?] [-c config] [-D debug] [-g pattern] [-h host] [-p port] [-w window] [-Z timezone] [query | labels ... | series ... | source ... ]

توضیحات (DESCRIPTION)

دستور pmseries انواع مختلفی از اطلاعات را درباره معیارهای کارایی که از طریق امکانات سری‌های زمانی مقیاس‌پذیر Performance Co-Pilot (PCP) و یک ذخیره‌ساز داده کلید-مقدار توزیع‌شده مانند https://valkey/io در دسترس هستند، نمایش می‌دهد.

به‌طور پیش‌فرض، pmseries با یک سرور کلید-مقدار محلی ارتباط برقرار می‌کند؛ با این حال می‌توان از گزینه‌های -h و -p برای تعیین یک سرور کلید-مقدار جایگزین استفاده کرد. اگر این نمونه، گرهی درون یک کلاستر باشد، تمام نمونه‌های دیگر در کلاستر به‌طور خودکار کشف شده و مورد استفاده قرار می‌گیرند.

pmseries در چندین حالت مختلف اجرا می‌شود - پرس‌وجوی شناسه‌ها، فراداده‌ها یا مقادیر سری‌های زمانی (که قبلاً در ذخیره‌ساز کلید-مقدار ذخیره شده‌اند)، یا بارگذاری دستی سری‌های زمانی. حالت دوم عموماً فقط برای بارگذاری بایگانی‌های قبلاً جمع‌آوری‌شده (غیرفعال) استفاده می‌شود، زیرا pmproxy(1) هنگامی که در حالت پیش‌فرض سری زمانی خود اجرا می‌شود، این عملکرد را برای نمونه‌های محلی و «زنده» (در حال رشد فعال) pmlogger(1) به‌صورت خودکار انجام می‌دهد. برای جزئیات بیشتر به بخش TIMESERIES LOADING در ادامه و گزینهٔ -L مراجعه کنید.

بدون گزینه‌های خط فرمان که خلاف آن را تعیین کنند، pmseries یک پرس‌وجوی سری زمانی صادر می‌کند تا سری‌های زمانی و مقادیر منطبق را بیابد. همه سری‌های زمانی با استفاده از یک هش یکتای SHA-1 شناسایی می‌شوند که همیشه در قالب ۴۰ رقمی هگزادسیمال و خوانا برای انسان نمایش داده می‌شود. این هش‌ها با استفاده از فراداده‌های مرتبط با هر معیار ساخته می‌شوند.

نکته مهم این است که این فراداده‌ها شامل تمامی فراداده‌های معیار (برچسب‌ها، نام‌ها، توصیف‌کننده‌ها) می‌شوند. برچسب‌های معیار به‌ویژه (تا حد امکان) برای هر ماشین یکتا هستند - برای مثال در لینوکس، برچسب‌های مرتبط با هر معیار شامل شناسه یکتای /etc/machine-id، hostname، domainname و سایر برچسب‌های ماشینی به‌طور خودکار تولیدشده، و همچنین هرگونه برچسب تعریف‌شده توسط مدیر سیستم از /etc/pcp/labels است. این برچسب‌ها را می‌توان با pminfo(1) و معیار pmcd.labels گزارش کرد.

برای اطلاعات تفصیلی درباره برچسب‌های معیار و سایر فراداده‌های معیار مورد استفاده در محاسبه هش شناسه هر سری زمانی، به pmLookupLabels(3)، pmLookupInDom(3)، pmLookupName(3) و pmLookupDesc(3) مراجعه کنید.

شناسه‌های سری زمانی، شناسه‌ای در سطح بالاتر (و مستقل از ماشین) نسبت به شناسه‌های سنتی معیارهای کارایی PCP (یا pmID)، شناسه‌های دامنه نمونه (pmInDom) و نام‌های معیار ارائه می‌دهند. برای جزئیات بیشتر درباره این شناسه‌های سنتی به PCPIntro(1) مراجعه کنید. با این وجود، pmseries از شناسه‌های سری زمانی تا حد زیادی به همان شیوه‌ای استفاده می‌کند که pminfo(1) از indom، شناسه‌های معیار و نام‌های معیار سطح پایین‌تر بهره می‌گیرد.

حالت پیش‌فرض عملکرد pmseries (یعنی بدون گزینه‌های خط فرمان) به آرگومان‌هایی که به آن ارائه می‌شود بستگی دارد. اگر تمام آرگومان‌های غیرگزینه‌ای شناسه‌های سری زمانی باشند (در قالب ۴۰ رقمی هگزادسیمال)، pmseries فراداده‌های این سری‌های زمانی را گزارش خواهد کرد - برای جزئیات به گزینهٔ -a مراجعه کنید. در غیر این صورت، با پارامترها به عنوان یک پرس‌وجوی سری زمانی برخورد خواهد شد..SH "پرس‌وجوهای سری زمانی (TIMESERIES QUERIES)" عبارات پرس‌وجو با استفاده از زبان پرس‌وجوی pmseries که در ادامه شرح داده شده است ساخته می‌شوند، اما می‌توانند به سادگیِ یک نام متریک باشند.

نمونه زیر مثالی از پرس‌وجوی سری‌های زمانی از تمام میزبان‌هایی است که با یک الگوی نام متریک (از طریق glob) مطابقت دارند:

$ pmseries kernel.all.cpu*
1d7b0bb3f6aec0f49c54f5210885464a53629b60
379db729afd63fb9eff436625bd6c55a7adc5cfd
3dd3b45bb05f96636043e5d58b52b441ce542285
[...]
ed2bf325ff6dc7589ec966698e5404b67252306a
dcb2a032a308b5717bf605ba8f8737e9c6e1ed19

برای شناسایی عملوندهای عبارت سری زمانی، زبان پرس‌وجو از نحو کلی زیر استفاده می‌کند:

[metric.name] '{metadata qualifiers}' '[time specification]'

مؤلفه metric.name پرس‌وجوی سری زمانی را به هر نام متریک منطبق PCP محدود می‌کند (فهرست نام‌های متریک برای یک آرشیو PCP یا میزبان زنده با دستور pminfo(1) بدون هیچ آرگومانی فراتر از --host یا --archive گزارش می‌شود). نحو pmseries نحو pminfo را گسترش داده و امکان تطبیق الگو بر پایه glob(7) را در نام متریک فراهم می‌کند. موارد فوق عملوندهای موجود را به عنوان برگ‌های عبارات pmseries شرح می‌دهند، که ممکن است شامل توابع، عملگرهای حسابی و ویژگی‌های دیگر باشند. برای جزئیات بیشتر به بخش EXPRESSIONS در زیر مراجعه کنید.

توصیف‌کننده‌ها و عملگرهای فراداده (METADATA QUALIFIERS AND METADATA OPERATORS)

توصیف‌کننده‌های فراداده در آکولاد ({}) محصور می‌شوند و نتایج پرس‌وجو را به عملوندهای سری زمانی با ویژگی‌های فراداده‌ای گوناگون محدودتر می‌کنند. این توصیف‌کننده‌ها بر اساس نام‌های متریک یا نمونه (instance) و مقادیر برچسب متریک بوده و شکل کلی metadata.name OPERATOR value را می‌گیرند، مانند:

instance.name == "cpu0"
metric.name != "kernel.all.pswitch"

هنگام استفاده از نام‌های برچسب، توصیف‌کننده فراداده اختیاری است و می‌توان آن را حذف کرد، مانند:

label.hostname == "www.acme.com"
hostname == "www.acme.com"

برای نام‌های متریک و نمونه تنها عملگرهای رشته‌ای اعمال می‌شوند، اما برای مقادیر برچسب متریک تمامی عملگرها در دسترس هستند. مجموعه عملگرهای موجود عبارتند از:

تعیین زمان (TIME SPECIFICATION)

بخش نهایی (اختیاری) یک پرس‌وجو به کاربر اجازه می‌دهد بازه زمانی مشخص و مورد نظر خود را تعیین کند. هرگونه تعیین زمان باعث می‌شود که مقادیر تمام سری‌های زمانی منطبق فقط برای بازه زمانی مشخص‌شده بازگردانده شوند.

این مشخصات درون براکت ([]) محصور شده و شامل یک یا چند جزء جداشده با ویرگول است. هر جزء جنبه‌ای مرتبط با زمان را مشخص می‌کند و شکل کلی keyword: value را به خود می‌گیرد، مانند:

samples:10

[metric.name] '{metadata qualifiers}' '[time specification]'

operand | expr operator expr | func(expr[, arg])

func1(func2(expr))
func1(expr) + func2(expr)
expr + func(expr)
func(expr) + expr
expr + expr

$ pmseries 'rate(kernel.all.pswitch{hostname:node88}[count:2] +
                 kernel.all.pswitch{hostname:node89}[count:2])'
1cf1a85d5978640ef94c68264d3ae8866cc11f7c
    [Tue Nov 10 14:39:48.771868000 2020] 71.257509 8e0a59304eb99237b89593a3e839b5bb8b9a9924

$ pmseries 'min_sample(kernel.all.load[count:100])'

$ pmseries 'kernel.all.load[count:2]'
726a325c4c1ba4339ecffcdebd240f441ea77848
    [Tue Nov 10 11:52:30.833379000 2020] 1.100000e+00 a7c96e5e2e0431a12279756d11590fa9fed8f306
    [Tue Nov 10 11:52:30.833379000 2020] 9.900000e-01 ee9b506935fd0976a893dc27242926f49326b9a1
    [Tue Nov 10 11:52:30.833379000 2020] 1.070000e+00 d5e1c360d13064c461169091997e1e8be7488133
    [Tue Nov 10 11:52:20.827134000 2020] 1.120000e+00 a7c96e5e2e0431a12279756d11590fa9fed8f306
    [Tue Nov 10 11:52:20.827134000 2020] 9.900000e-01 ee9b506935fd0976a893dc27242926f49326b9a1
    [Tue Nov 10 11:52:20.827134000 2020] 1.070000e+00 d5e1c360d13064c461169091997e1e8be7488133

$ pmseries 'min_sample(kernel.all.load[count:2])'
11b965bc5f9598034ed9139fb3a78c6c0b7065ba
    [Tue Nov 10 11:52:30.833379000 2020] 1.100000e+00 a7c96e5e2e0431a12279756d11590fa9fed8f306
    [Tue Nov 10 11:52:30.833379000 2020] 9.900000e-01 ee9b506935fd0976a893dc27242926f49326b9a1
    [Tue Nov 10 11:52:30.833379000 2020] 1.070000e+00 d5e1c360d13064c461169091997e1e8be7488133

$ pmseries 'kernel.all.pswitch[count:5]'
d7832c4fba33bcc980b1a1b614e0508043288480
    [Tue Nov 10 12:44:59.380666000 2020] 460774294
    [Tue Nov 10 12:44:49.382070000 2020] 460747232
    [Tue Nov 10 12:44:39.378545000 2020] 460722370
    [Tue Nov 10 12:44:29.379029000 2020] 460697388
    [Tue Nov 10 12:44:19.379096000 2020] 460657412
$ pmseries 'min_sample(kernel.all.pswitch[count:5])'
1b6e92fb5bc012372f54452734dd03f0f131fa06
    [Tue Nov 10 12:44:19.379096000 2020] 460657412 d7832c4fba33bcc980b1a1b614e0508043288480

$ pmseries 'rescale(rate(disk.dev.read_bytes[count:4]), "mbytes/s")'

متاداده سری‌های زمانی (TIMESERIES METADATA)

با استفاده از گزینه‌های خط فرمان، می‌توان از pmseries درخواست کرد تا متاداده‌های (نام‌های سنجه، نام‌های اینستنس، برچسب‌ها، توصیف‌کننده‌ها) مرتبط با یک سری زمانی مجزا یا گروهی از سری‌های زمانی را ارائه دهد؛ به عنوان مثال:

$ pmseries -a dcb2a032a308b5717bf605ba8f8737e9c6e1ed19
dcb2a032a308b5717bf605ba8f8737e9c6e1ed19
    PMID: 60.0.21
    Data Type: 64-bit unsigned int  InDom: PM_INDOM_NULL 0xffffffff
    Semantics: counter  Units: millisec
    Source: f5ca7481da8c038325d15612bb1c6473ce1ef16f
    Metric: kernel.all.cpu.nice
    labels {"agent":"linux","domainname":"localdomain",\
            "groupid":1000,"hostname":"shard",\
            "latitude":-25.28496,"longitude":152.87886,\
            "machineid":"295b16e3b6074cc8bdbda8bf96f6930a",\
            "userid":1000}

مجموعه کامل گزینه‌های گزارش متاداده در pmseries عبارتند از:

-a, --all

گزینه‌ای تسهیل‌کننده برای گزارش تمامی متاداده‌ها برای سری زمانی داده‌شده، معادل با -deilms.

-d, --desc

توصیف‌های سنجه با شرح جزئیات PMID، نوع داده، معناشناسی داده، واحدها، مقیاس و دامنه اینستنس (InDom) مرتبط. این گزینه معادل مستقیمی در pminfo(1) دارد.

-F, --fast

پرس‌وجو یا بارگذاری فقط متاداده سری‌ها، نه مقادیر.

-g pattern, --glob=pattern

ارائه یک pattern (الگو) به سبک glob(7) برای محدود کردن گزارش ارائه‌شده توسط -i، -l، -m و -S.

-i, --instances

توصیف‌های سنجه با شرح جزئیات PMID، نوع داده، معناشناسی داده، واحدها، مقیاس و دامنه اینستنس مرتبط.

-I, --fullindom

چاپ InDom در حالت پرگو (verbose). این گزینه معادل مستقیمی در pminfo(1) دارد.

-l, --labels

چاپ مجموعه‌های برچسب مرتبط با سنجه‌ها و اینستنس‌ها. برچسب‌ها متاداده اختیاری سنجه هستند که با جزئیات کامل در pmLookupLabels(3) شرح داده شده‌اند. این گزینه معادل مستقیمی در pminfo(1) دارد.

-m, --metrics

چاپ نام سنجه‌ها.

-M, --fullpmid

چاپ PMID در حالت پرگو (verbose). این گزینه معادل مستقیمی در pminfo(1) دارد.

-n, --names

چاپ تنها نام‌های برچسب‌ها که با کاما از هم جدا شده‌اند (نه مقادیر آن‌ها) برای برچسب‌های مرتبط با سنجه‌ها و اینستنس‌ها.

-s, --series

چاپ شناسه‌های سری‌های زمانی مرتبط با سنجه‌ها، اینستنس‌ها و منابع. این شناسه‌های یکتا بر اساس برچسب‌های ذاتی (غیر اختیاری) و سایر متاداده‌های سنجه مرتبط با هر بافت PMAPI (منابع)، سنجه‌ها و اینستنس‌ها محاسبه می‌شوند. اتصالات بایگانی، بافت محلی یا اتصالات pmcd(1) برای یک میزبان یکسان، همگی شناسه منبع یکسانی تولید می‌کنند. این گزینه معادل مستقیمی در pminfo(1) دارد. همچنین pmLookupLabels(3) و گزینه -l/--labels را ببینید..SH "منابع سری‌های زمانی (TIMESERIES SOURCES)" یک منبع، یک شناسه یکتا است (که در خارج به‌صورت یک هش هگزادسیمال ۴۰ بایتی SHA-1 نمایش داده می‌شود) که نشان‌دهنده میزبان زنده و/یا آرشیوهایی است که هر سری زمانی از آن سرچشمه گرفته است. بافتار (context) برای یک شناسه منبع (که با -s به دست می‌آید) را می‌توان با این گزینه گزارش کرد:

-S, --sources

چاپ نام‌های منابع سری‌های زمانی. این نام‌ها یا نام میزبان (hostname) یا مسیرهای کامل آرشیو هستند.

توجه به این نکته حائز اهمیت است که منابع زنده و آرشیوی می‌توانند (و خواهند توانست) هش شناسه منبع یکسان SHA-1 تولید کنند، به شرطی که برچسب‌های بافتار برای آن میزبان یکسان باقی بمانند (برچسب‌ها در آرشیوهای PCP ذخیره می‌شوند و همچنین می‌توان آن‌ها را به‌صورت زنده از pmcd(1) دریافت کرد).

بارگذاری سری‌های زمانی (TIMESERIES LOADING)

فراداده و داده‌های سری زمانی یا به‌صورت خودکار توسط یک pmproxy(1) محلی بارگذاری می‌شوند، یا به‌طور دستی با استفاده از یک پرس‌وجوی ویژه‌ساخته pmseries و گزینه -L/--load:

$ pmseries --load "{source.path: \"$PCP_LOG_DIR/pmlogger/acme\"}"
pmseries: [Info] processed 2275 archive records from [...]

این پرس‌وجو باید یک مسیر آرشیو منبع را مشخص کند، اما همچنین می‌تواند درون‌ریزی را به سری‌های زمانی خاص (با استفاده از نام متریک‌ها، برچسب‌ها و غیره) و به یک بازه زمانی خاص با استفاده از مؤلفه تعیین زمان در زبان پرس‌وجو محدود نماید.

برای سهولت، اگر آرگومان load یک مسیر فایل معتبر باشد که توسط access(2) تعیین شده است، می‌توان از یک شکل کوتاه‌شده استفاده کرد:

$ pmseries --load $PCP_LOG_DIR/pmlogger/acme.0

نکته: بارگذاری سری‌های زمانی (از نظر برچسب زمانی) فقط-افزودنی (append-only) است و اگر برای یک متریک مشخص بیش از stream.maxlen ورودی (تعریف شده در $PCP_SYSCONF_DIR/pmseries/pmseries.conf) بارگذاری شود، قدیمی‌ترین ورودی‌ها دور ریخته می‌شوند.

گزینه‌ها (OPTIONS)

گزینه‌های خط فرمان موجود، علاوه بر گزینه‌های فراداده و منابع سری زمانی که در بالا شرح داده شد، عبارتند از:

-c config, --config=config

تعیین فایل config برای استفاده.

-h host, --host=host

اتصال به سرور کلید-مقدار در host، به جای سرور موجود روی localhost.

-L, --load

بارگذاری فراداده و داده‌های سری زمانی در کلاستر کلید-مقدار.

-p port, --port=port

اتصال به سرور کلید-مقدار در port، به جای درگاه پیش‌فرض 6379.

-q, --query

انجام یک پرس‌وجوی سری زمانی. این عمل پیش‌فرض است.

-t, --times

گزارش برچسب‌های زمانی به‌صورت عددی (به میلی‌ثانیه) به جای قالب پیش‌فرض خوانا برای انسان.

-v, --values

گزارش تمام مقادیر شناخته‌شده برای نام(های) داده‌شده label، یا گزارش مقادیر برای شناسه‌های مشخص‌شده series.

-w, --window

ارائه یک مشخصه زمانی که در زمان بازگرداندن مقادیر از طریق استفاده از شناسه‌های series (یعنی زمانی که از یک رشته query استفاده نمی‌شود) روی مقادیر برگشتی اعمال خواهد شد. این مشخصه زمانی از همان قالب درون براکت استفاده می‌کند که پیش‌تر در بخش «TIME SPECIFICATION» توضیح داده شده است.

-V, --version

نمایش شماره نسخه و خروج.

-Z timezone, --timezone=timezone

استفاده از timezone برای تاریخ و زمان. Timezone در قالب متغیر محیطی TZ است، همان‌طور که در environ(7) شرح داده شده است.

-?, --help

نمایش پیام راهنما و خروج..SH "مثال‌ها (EXAMPLES)" پرس‌وجوی نمونهٔ زیر چندین جنبهٔ اساسی از زبان پرس‌وجوی pmseries را نشان می‌دهد:

$ pmseries 'kernel.all.load{hostname:"toium"}[count:2]'
eb713a9cf472f775aa59ae90c43cd7f960f7870f
    [Thu Nov 14 05:57:06.082861000 2019] 1.0e-01 b84040ffccd54f839b65140cf139bab51cbbcf62
    [Thu Nov 14 05:57:06.082861000 2019] 6.8e-01 a60b5b3bf25e71071c41934fa4d7d251f765f30c
    [Thu Nov 14 05:57:06.082861000 2019] 6.4e-01 e1974a062375e6e62370ffadf5b0650dad739480
    [Thu Nov 14 05:57:16.091546000 2019] 1.6e-01 b84040ffccd54f839b65140cf139bab51cbbcf62
    [Thu Nov 14 05:57:16.091546000 2019] 6.7e-01 a60b5b3bf25e71071c41934fa4d7d251f765f30c
    [Thu Nov 14 05:57:16.091546000 2019] 6.4e-01 e1974a062375e6e62370ffadf5b0650dad739480

این پرس‌وجو دو مقدار اخیر را برای همه نمونه‌های متریک kernel.all.load با یک label.hostname که با عبارت باقاعدهٔ “toium” تطابق دارد، بازمی‌گرداند. این یک متریک مجموعه‌مقداره (set-valued) است (یعنی متریکی با یک “دامنهٔ نمونه” که در این حالت از سه نمونه تشکیل شده است: میانگین‌های ۱، ۵ و ۱۵ دقیقه). نخستین ستون بازگردانده‌شده برچسب زمانی است، سپس یک مقدار ممیز شناور، و در نهایت هش سری زمانیِ شناسهٔ نمونه (دو مقدار برای سه نمونه بازگردانده می‌شود، بنابراین شش سطر بازگردانده خواهد شد). سپس می‌توان فرادادهٔ این سری‌های زمانی را بیشتر بررسی کرد:

$ pmseries -a eb713a9cf472f775aa59ae90c43cd7f960f7870f
eb713a9cf472f775aa59ae90c43cd7f960f7870f
    PMID: 60.2.0
    Data Type: float  InDom: 60.2 0xf000002
    Semantics: instant  Units: none
    Source: 0e89c1192db79326900d82131c31399524f0b3ee
    Metric: kernel.all.load
    inst [1 or "1 minute"] series b84040ffccd54f839b65140cf139bab51cbbcf62
    inst [5 or "5 minute"] series a60b5b3bf25e71071c41934fa4d7d251f765f30c
    inst [15 or "15 minute"] series e1974a062375e6e62370ffadf5b0650dad739480
    inst [1 or "1 minute"] labels {"agent":"linux","hostname":"toium"}
    inst [5 or "5 minute"] labels {"agent":"linux","hostname":"toium"}
    inst [15 or "15 minute"] labels {"agent":"linux","hostname":"toium"}

محیط PCP (PCP ENVIRONMENT)

متغیرهای محیطی با پیشوند PCP_ برای پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های مورداستفادهٔ PCP به کار می‌روند. در هر نصب، فایل /etc/pcp.conf حاوی مقادیر محلی برای این متغیرها است. متغیر $PCP_CONF ممکن است برای مشخص کردن یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در pcp.conf(5) شرح داده شده است.

برای متغیرهای محیطی که بر ابزارهای PCP تأثیر می‌گذارند، pmGetOptions(3) را ببینید.

گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)

گزینهٔ -D یا --debug خروجی عیب‌یابی‌های تکمیلی را در stderr برای کمک به تفکیک و بررسی مشکلات فعال می‌کند، اگرچه این اطلاعات گاهی مبهم است و اساساً به جای کاربران نهایی، برای راهنمایی توسعه‌دهندگان در نظر گرفته شده است. debug فهرستی از گزینه‌های اشکال‌زدایی جداشده با کاما است؛ از pmdbg(1) همراه با گزینهٔ -l برای به‌دست‌آوردن فهرستی از گزینه‌های اشکال‌زدایی موجود و مفهوم آن‌ها استفاده کنید.

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

PCPIntro(1), pmcd(1), pminfo(1), pmproxy(1), access(2), PMAPI(3), PMWEBAPI(3), pmLookupDesc(3), pmLookupInDom(3), pmLookupLabels(3), pmLookupName(3), pmNewContextZone(3), pmNewZone(3), pmParseInterval(3), pmParseTimeWindow(3), pcp.conf(5), environ(7), glob(7) و regex(7).