RRDFETCH(1) rrdtool RRDFETCH(1)

rrdfetch - واکشی داده‌ها از یک RRD

rrdtool fetch filename CF [--resolution|-r resolution] [--start|-s start] [--end|-e end] [--align-start|-a] [--daemon|-d address]

تابع fetch معمولاً به‌طور داخلی توسط تابع گراف (graph) برای دریافت داده‌ها از RRDها استفاده می‌شود. fetch پروندهٔ RRD را تحلیل کرده و تلاش می‌کند داده‌ها را با تفکیک‌پذیری درخواستی بازیابی کند. داده‌های واکشی‌شده در stdout چاپ می‌شوند. داده‌های *UNKNOWN* بسته به تابع printf سیستم‌عامل شما اغلب با رشتهٔ «NaN» نمایش داده می‌شوند.

نام RRD که می‌خواهید داده‌ها را از آن واکشی کنید.
تابع ادغام (consolidation function) که روی داده‌های مد نظر شما برای واکشی اعمال می‌شود (AVERAGE، MIN، MAX، LAST).
بازهٔ زمانی مورد نظری که می‌خواهید مقادیر داشته باشند (ثانیه به‌ازای هر مقدار). می‌توان از یک پسوند اختیاری استفاده کرد (برای مثال "5m" به‌جای 300 ثانیه). rrdfetch تلاش خواهد کرد تا با درخواست شما مطابقت پیدا کند، اما حتی اگر تطابق دقیقی امکان‌پذیر نباشد نیز داده‌ها را برمی‌گرداند. بخش «RESOLUTION INTERVAL» را ببینید.
شروع سری زمانی. زمان به‌صورت ثانیه‌های گذشته از مبدأ epoch‏ (1970-01-01) الزامی است. اعداد منفی نسبت به زمان فعلی سنجیده می‌شوند. به‌طور پیش‌فرض، داده‌های مربوط به یک روز واکشی خواهند شد. همچنین برای توضیحات دقیق دربارهٔ روش‌های تعیین زمان شروع، بخش «AT-STYLE TIME SPECIFICATION» را ببینید.
پایان سری زمانی به ثانیه از مبدأ epoch. همچنین برای توضیحات دقیق دربارهٔ نحوهٔ تعیین زمان پایان، بخش «AT-STYLE TIME SPECIFICATION» را ببینید.
تنظیم خودکار زمان شروع به‌سمت پایین برای تراز شدن با تفکیک‌پذیری (resolution). زمان پایان نیز به همان مقدار تنظیم می‌شود. این کار نیاز به محاسبات خارجی شرح داده‌شده در RESOLUTION INTERVAL را برطرف می‌کند؛ هرچند اگر یک RRA مشخص مد نظر باشد، این گزینه تضمین نمی‌کند که شروع و پایان در محدودهٔ آن قرار گیرند.
نشانی دیمن rrdcached. در صورت مشخص شدن، پیش از خواندن فایل‌های RRD یک دستور "flush" به سرور ارسال می‌شود. این امر به rrdtool امکان می‌دهد تا حتی اگر دیمن طوری پیکربندی شده باشد که مقادیر را برای مدتی طولانی کش کند، داده‌های تازه را بازگرداند. برای مشاهدهٔ فهرستی از قالب‌های پذیرفته‌شده، گزینهٔ -l را در راهنمای rrdcached ببینید. 
rrdtool fetch --daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd AVERAGE

لطفاً توجه داشته باشید که به دلایل ایمنی رشته‌ها (thread-safety)، زمان مشخص‌شده با -s و -e نمی‌تواند از قالب‌های پیچیدهٔ شرح داده‌شده در «AT-STYLE TIME SPECIFICATION» استفاده کند. تنها آرگومان‌های پذیرفته‌شده «اعداد صحیح ساده» هستند. مقادیر مثبت به‌صورت ثانیه‌های گذشته از epoch تفسیر می‌شوند و مقادیر منفی (و صفر) نسبت به now سنجیده می‌شوند. بنابراین «1272535035» به «09:57:15 (UTC), April 29th 2010» و «-3600» به «یک ساعت پیش» اشاره دارد..SS "بازه تفکیک‌پذیری (RESOLUTION INTERVAL)" برای اینکه RRDtool بتواند داده‌هایی غیر از دقیق‌ترین تفکیک‌پذیری RRA را واکشی کند، هر دو زمان آغاز و پایان باید بر روی مرزهایی مشخص شوند که مضربی از تفکیک‌پذیری مورد نظر باشند. مثال زیر را در نظر بگیرید:

rrdtool create subdata.rrd -s 10 \
 DS:ds0:GAUGE:5m:0:U \
 RRA:AVERAGE:0.5:5m:300h \
 RRA:AVERAGE:0.5:15m:300h \
 RRA:AVERAGE:0.5:1h:50d \
 RRA:MAX:0.5:1h:50d \
 RRA:AVERAGE:0.5:1d:600d \
 RRA:MAX:0.5:1d:600d

این RRD داده‌ها را هر ۱۰ ثانیه جمع‌آوری کرده و میانگین‌های آن را در بازه‌های ۵ دقیقه، ۱۵ دقیقه، ۱ ساعت و ۱ روز، و همچنین بیشینه‌ها را برای ۱ ساعت و ۱ روز ذخیره می‌کند.

حال فرض کنید می‌خواهید داده‌های میانگین ۱۵ دقیقه‌ای را برای ساعت گذشته واکشی کنید. ممکن است این دستور را امتحان کنید:

rrdtool fetch subdata.rrd AVERAGE -r 15m -s -1h

با این حال، این کار تقریباً همیشه به سری زمانی‌ای منجر می‌شود که در RRA مربوط به ۱۵ دقیقه نیست. بنابراین، RRA با بالاترین تفکیک‌پذیری، یعنی میانگین‌های ۵ دقیقه‌ای، انتخاب خواهد شد که در این حالت چیزی نیست که شما می‌خواستید.

بنابراین، اطمینان حاصل کنید که:

1.
هر دو زمان آغاز و پایان مضربی از ۹۰۰ ("15m") باشند
2.
هر دو زمان آغاز و پایان در محدوده RRA مورد نظر قرار داشته باشند

پس، اگر زمان فعلی را «t» بنامیم، چنین عمل کنید:

end time == int(t/900)*900,
start time == end time - 1hour,
resolution == 900.

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

TIME=$(date +%s)
RRDRES=900
rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \
   -e $(($TIME/$RRDRES*$RRDRES)) -s e-1h

یا در Perl:

perl -e '$ctime = time; $rrdres = 900; \
         system "rrdtool fetch subdata.rrd AVERAGE \
                 -r $rrdres -e @{[int($ctime/$rrdres)*$rrdres]} -s e-1h"'

یا با استفاده از پرچم --align-start:

rrdtool fetch subdata.rrd AVERAGE -a -r 15m -s -1h

جدا از شیوه سنتی Seconds since epoch (ثانیه‌ها از مبدا زمانی یونیکس)، RRDtool روش تعیین زمان به سبک at را نیز درک می‌کند. این شیوه به پیروی از دستور یونیکس at(1) به نام «at-style» نامیده می‌شود که روش‌های نسبتاً پیشرفته‌ای برای تعیین زمان جهت اجرای وظیفه در تاریخ و زمانی مشخص دارد. شیوه at-style از دو بخش تشکیل شده است: مشخصات TIME REFERENCE (مرجع زمان) و مشخصات TIME OFFSET (افست زمان).

مشخصات مرجع زمان برای تعیین یک لحظه مرجع در زمان استفاده می‌شود (که سپس افست زمان نسبت به آن اعمال می‌گردد). در صورت وجود، باید ابتدا بیاید؛ و هنگامی که حذف شود، پیش‌فرض آن now است. مرجع زمان به نوبه خود از یک مرجع time-of-day (زمان روز؛ که در صورت وجود، باید اول بیاید) و یک مرجع day (روز) تشکیل می‌شود.

بخش time-of-day می‌تواند به صورت HH:MM، HH.MM، یا فقط HH مشخص شود. می‌توانید پسوند am یا pm را به آن اضافه کنید یا از ساعت ۲۴ ساعته استفاده نمایید. برخی از زمان‌های خاص روز نیز پشتیبانی می‌شوند، از جمله midnight (ساعت 00:00)، noon (ساعت 12:00) و اصطلاح بریتانیایی teatime (ساعت 16:00).

بخش day می‌تواند به صورت month-name day-of-the-month و به صورت اختیاری یک عدد ۲ یا ۴ رقمی year مشخص شود (مانند March 8 1999). همچنین می‌توانید از day-of-week-name (مانند Monday) یا یکی از کلمات: yesterday، today، tomorrow استفاده کنید. علاوه بر این، می‌توانید day را به عنوان یک تاریخ کامل در چندین قالب عددی از جمله MM/DD/[YY]YY، DD.MM.[YY]YY، یا YYYYMMDD مشخص کنید.

یادداشت ۱: این رفتار با رفتار اصلی دستور at(1) متفاوت است، جایی که یک تاریخ تک‌عددی به صورت MMDD[YY]YY تفسیر می‌شود.

یادداشت ۲: اگر day را به این شیوه مشخص کنید، وارد کردن time-of-day نیز الزامی است.

در نهایت، می‌توانید از کلمات now، start، end یا epoch به عنوان مرجع زمان خود استفاده کنید. Now به لحظه کنونی اشاره دارد (و همچنین مرجع زمانی پیش‌فرض است). Start (end) می‌تواند برای مشخص کردن زمان نسبت به زمان آغاز (پایان) در ابزارهایی که از این دسته‌ها استفاده می‌کنند (rrdfetch، rrdgraph) به کار رود و epoch نشان‌دهنده مبدا زمانی یونیکس (*IX epoch؛ یعنی برچسب زمانی یونیکس 0 = 1970-01-01 00:00:00 UTC) است. epoch برای رفع ابهام بین یک مقدار برچسب زمانی و برخی قالب‌های اختصاری تعیین تاریخ/زمان مفید است، زیرا این امکان را فراهم می‌سازد که مشخصات افست زمانی با واحدها به کار روند؛ به عنوان مثال epoch+19711205s بدون ابهام برچسب زمانی 19711205 را مشخص می‌کند و نه 1971-12-05 00:00:00 UTC.

نام‌های ماه و روزهای هفته می‌توانند به شکل اختصاری معمول خود استفاده شوند (برای مثال، Dec برای December، Sun برای Sunday و غیره). کلمات now، start، end را می‌توان به صورت n، s، e خلاصه کرد..SS "مشخص کردن آفست زمانی (TIME OFFSET SPECIFICATION)" مشخص‌کردن آفست زمانی برای افزودن/کاستن بازه‌های زمانی مشخص به/از لحظه مبدأ زمانی به‌کار می‌رود. این مشخصه از یک علامت (+ یا -) و یک مقدار تشکیل شده است. واحدهای زمانی زیر می‌توانند برای مشخص‌کردن مقدار استفاده شوند: years، months، weeks، days، hours، minutes، یا seconds. این واحدها می‌توانند به صورت مفرد یا جمع، و به شکل طبیعی یا به یک تک‌حرف مخفف شوند (مانند +3days، -1wk، -3y). چند واحد زمانی را می‌توان با هم ترکیب کرد (مانند -5mon1w2d) یا به هم پیوست (مانند -5h45min = -5h-45min = -6h+15min = -7h+1h30m-15min و غیره).

نکته ۳: اگر آفست زمانی را بر حسب روز، هفته، ماه یا سال مشخص کنید، در نهایت به آفست زمانی‌ای می‌رسید که ممکن است بسته به مبدأ زمانی شما متغیر باشد؛ چرا که همه این واحدهای زمانی مقدار بازه زمانی واحد و یکسانی ندارند (۱ سال شامل ۳۶۵ یا ۳۶۶ روز است، ۱ ماه بین ۲۸ تا ۳۱ روز طول می‌کشد، و حتی ۱ روز ممکن است دو بار در سال، هنگام اعمال تغییر ساعت تابستانی (DST)، دقیقاً برابر با ۲۴ ساعت نباشد). برای حل این مسئله، زمانی که از روزها، هفته‌ها، ماه‌ها یا سال‌ها به عنوان واحدهای آفست زمانی خود استفاده می‌کنید، تاریخ مرجع زمانی شما بدون تلاش اضافی برای اطمینان از چیزی درباره آن تنظیم می‌شود (به این امید که mktime(3) بعداً از پس آن برآید). این امر ممکن است به نتایجی غافلگیرکننده (یا حتی نامعتبر!) منجر شود، مانند 'May 31 -1month' = 'Apr 31' (بی‌معنی) = 'May 1' (پس از نرمال‌سازی با mktime(3))؛ در منطقه زمانی EET عبارت '3:30am Mar 29 1999 -1 day' منجر به '3:30am Mar 28 1999' (یکشنبه) می‌شود که یک ترکیب نامعتبر از زمان/تاریخ است (به دلیل جلو کشیده شدن ساعت در DST از 3am -> 4am، مثال زیر را ببینید).

در مقابل، ساعت‌ها، دقیقه‌ها و ثانیه‌ها بازه‌های زمانی کاملاً مشخصی هستند و تضمین می‌شود که همیشه آفست‌های زمانی را دقیقاً همان‌طور که مشخص شده تولید کنند (برای مثال در منطقه زمانی EET، مقدار '8:00 Mar 27 1999 +2 days' = '8:00 Mar 29 1999' است، اما از آنجا که حدود ساعت 3:00 Mar 28 1999 یک تغییر ۱ ساعته به جلو برای DST رخ می‌دهد، بازه زمانی واقعی بین 8:00 Mar 27 1999 و 8:00 Mar 29 1999 برابر با ۴۷ ساعت خواهد بود؛ از سوی دیگر، '8:00 Mar 27 1999 +48 hours' = '9:00 Mar 29 1999' است، همان‌طور که انتظار می‌رود).

نکته ۴: مخفف تک‌حرفی هم برای months و هم برای minutes حرف m است. برای ابهام‌زدایی، تجزیه‌کننده با به‌کارگیری دو روش اکتشافی زیر سعی می‌کند ذهن شما را بخواند :)

1.
اگر m در بافت (یعنی بلافاصله پس از) سال‌ها، ماه‌ها، هفته‌ها یا روزها استفاده شود، فرض می‌شود که به معنای months است، در حالی که در بافت ساعت‌ها، دقیقه‌ها و ثانیه‌ها به معنای minutes خواهد بود. (برای مثال، در -1y6m یا +3w1m حرف m به صورت months تفسیر می‌شود، در حالی که در -3h20m یا +5s2m تجزیه‌کننده تصمیم به minutes می‌گیرد).
2.
خارج از بافت (یعنی بلافاصله پس از علامت + یا -)، معنای m از روی عددی که مستقیماً بعد از آن می‌آید حدس زده می‌شود. در حال حاضر، اگر مقدار مطلق عدد کمتر از ۶ باشد فرض می‌شود که m به معنای months است، در غیر این صورت به عنوان minutes در نظر گرفته می‌شود. (برای مثال، -6m == -6m minutes، در حالی که +5m == +5 months).

نکات پایانی: مشخص‌کردن زمان به بزرگی و کوچکی حروف حساس نیست (case-insensitive). فاصله را می‌توان آزادانه وارد کرد یا کلاً حذف نمود. با این حال، مواردی وجود دارد که فاصله الزامی است (مانند 'midnight Thu'). در این حالت یا باید کل عبارت را داخل کوتیشن قرار دهید تا توسط پوسته (shell) شما تفکیک نشود، یا از '_' (زیرخط) یا ',' (ویرگول) استفاده کنید که آن‌ها نیز به عنوان فاصله به حساب می‌آیند (مانند midnight_Thu یا midnight,Thu).

Oct 12 -- ۱۲ اکتبر سال جاری

-1month یا -1m -- زمان فعلی از روز، دقیقاً یک ماه قبل (ممکن است نتایج غیرمنتظره داشته باشد، نکته ۳ بالا را ببینید).

noon yesterday -3hours -- دیروز صبح؛ همچنین می‌تواند به صورت 9am-1day نیز مشخص شود.

23:59 31.12.1999 -- ۱ دقیقه مانده به سال ۲۰۰۰.

12/31/99 11:59pm -- ۱ دقیقه مانده به سال ۲۰۰۰ برای امپریالیست‌ها.

12am 01/01/01 -- آغاز هزاره جدید

end-3weeks یا e-3w -- ۳ هفته پیش از زمان پایان (می‌تواند به عنوان مشخصه زمان شروع استفاده شود).

start+6hours یا s+6h -- ۶ ساعت پس از زمان شروع (می‌تواند به عنوان مشخصه زمان پایان استفاده شود).

931200300 -- ۱۸:۴۵ (UTC)، ۵ جولای ۱۹۹۹ (بله، ثانیه‌ها از مبدأ ۱۹۷۰ نیز معتبر هستند).

19970703 12:45 -- ۱۲:۴۵، ۳ جولای ۱۹۹۷ (مورد علاقه من، و حتی دارای شماره ISO (8601) نیز هست)..SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)" متغیرهای محیطی زیر می‌توانند برای تغییر رفتار "rrdtool fetch" استفاده شوند:

اگر این متغیر محیطی مقداردهی شود، تأثیری مشابه با تعیین گزینهٔ "--daemon" در خط فرمان خواهد داشت. اگر هر دو موجود باشند، آرگومان خط فرمان اولویت دارد.

Tobias Oetiker <tobi@oetiker.ch>

2026-08-08 1.11.0