نام (NAME)

rrdcached - دیمن حافظه‌نهان داده‌ها برای rrdtool

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

rrdcached [-a alloc_size] [-b base_dir [-B]] [-F] [-f timeout] [-G group]] [-g] [-j journal_dir] [-L] [-l address] [-m mode] [-O] [-o log_file] [-P permissions] [-p pid_file] [-R] [-s group] [-t write_threads] [-U user]] [-V log_level] [-w timeout] [-z delay].SH "توضیحات (DESCRIPTION)" rrdcached یک دیمِن است که به‌روزرسانی‌های فایل‌های RRD موجود را دریافت می‌کند، آن‌ها را انباشته می‌سازد، و اگر تعداد کافی دریافت شده باشد یا زمان مشخصی سپری شده باشد، به‌روزرسانی‌ها را در فایل RRD می‌نویسد. از دستور flush می‌توان برای اجبار به نوشتن مقادیر بر روی دیسک استفاده کرد، تا ابزارهای رسم نمودار و موارد مشابه بتوانند با داده‌های به‌روز کار کنند.

این دیمن با در نظر گرفتن ساختارهای بزرگ توسعه یافته است. این ساختارها معمولاً دیر یا زود بنا به دلایلی که فراتر از حوصلهٔ این سند است با مشکلات مرتبط با I/O مواجه می‌شوند. برای جزئیات به ویکی در وبگاه RRDtool مراجعه کنید. همچنین پیش از استفاده از این دیمن، بخش «ملاحظات امنیتی (SECURITY CONSIDERATIONS)» در زیر را بررسی کنید! شرح مفصلی از نحوهٔ عملکرد دیمن را می‌توانید در بخش «نحوهٔ کارکرد (HOW IT WORKS)» در زیر بیابید.

گزینه‌ها (OPTIONS)

-l address

به دیمن می‌گوید به address متصل شود و اتصالات ورودی TCP را روی آن سوکت بپذیرد. اگر address با "unix:" آغاز شود، هر آنچه پس از این پیشوند می‌آید به عنوان مسیر یک سوکت دامنه یونیکس (UNIX domain socket) تفسیر می‌شود. در غیر این صورت، آدرس یا نام گره با استفاده از getaddrinfo() حل و تحلیل می‌شود.

برای سوکت‌های شبکه، درگاه را می‌توان با استفاده از قالب "[address]:port" مشخص کرد. اگر نشانی یک آدرس IPv4 یا یک نام دامنه کاملاً مشخص (یعنی آدرس شامل حداقل یک نقطه (".")) باشد، می‌توان کروشه‌ها را حذف کرد که الگوی (ساده‌تر) "address:port" حاصل می‌شود. درگاه پیش‌فرض 42217 است. اگر یک سوکت شبکه مشخص کنید، مطالعهٔ بخش «ملاحظات امنیتی (SECURITY CONSIDERATIONS)» الزامی است.

قالب‌های زیر پذیرفته می‌شوند. لطفاً توجه داشته باشید که در حالت دوم، آدرس سوکت دامنه یونیکس باید با یک اسلش آغاز شود!

unix:</path/to/unix.sock>
/<path/to/unix.sock>
<hostname-or-ip>
[<hostname-or-ip>]:<port>
<hostname-or-ipv4>:<port>

در صورت ارائهٔ یک درگاه بدون میزبان (برای نمونه "-l :42217")، دیمن روی آن درگاه در تمام رابط‌های شبکه گوش فرا خواهد داد. در صورتی که درگاه پیش‌فرض مد نظر باشد، از "-L" برای بی‌نیازی از ارائهٔ صریح درگاه استفاده کنید.

اگر هیچ گزینهٔ -l مشخص نشود، آدرس پیش‌فرض، "unix:/tmp/rrdcached.sock"، استفاده خواهد شد. می‌توان چندین گزینهٔ -l ارائه داد.

-L

به دیمن می‌گوید به درگاه پیش‌فرض TCP روی تمام رابط‌های در دسترس متصل شود. این گزینه معادل "-l ''" است، بدون سردرگمی ناشی از پارامتر رشتهٔ خالی.

-s group_name|gid

مجوزهای گروهی یک سوکت دامنه یونیکس را تنظیم می‌کند. این گزینه شناسهٔ عددی گروه یا نام گروه را می‌پذیرد. آن گروه سپس هر دو مجوز خواندن و نوشتن را برای سوکت خواهد داشت (سوکت دارای مجوزهای دسترسی 0760 خواهد بود) و بنابراین قادر به ارسال دستورها به دیمن است. این گزینه ممکن است در مواردی مفید باشد که نمی‌توانید به آسانی همهٔ فرایندهای RRD را با اختیارات کاربری یکسان اجرا کنید (مانند اسکریپت‌های CGI تولید نمودار که معمولاً در بستر مجوزهای وب‌سرور اجرا می‌شوند).

این گزینه بر آدرس‌های سوکت یونیکس بعدی (گزینه‌های -l بعدی) یا سوکت پیش‌فرض (در صورت عدم تعیین هیچ گزینهٔ -l) تأثیر می‌گذارد؛ یعنی می‌توانید تنظیمات متفاوتی را برای سوکت‌های مختلف تعیین کنید.

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

-m mode

مجوزهای دسترسی فایلی یک سوکت دامنه یونیکس را تنظیم می‌کند. این گزینه یک عدد در مبنای هشت را که نمایانگر الگوی بیتی حالت دسترسی است می‌پذیرد (برای جزئیات chmod(1) را ببینید).

لطفاً توجه داشته باشید که همهٔ سیستم‌ها این تنظیم را اعمال نمی‌کنند. در لینوکس، مجوزهای خواندن/نوشتن برای اتصال به یک سوکت یونیکس الزامی است. با این حال، بسیاری از سیستم‌های مشتق‌شده از BSD مجوزهای سوکت‌های یونیکس را نادیده می‌گیرند. برای جزئیات به unix(7) مراجعه کنید.

این گزینه بر آدرس‌های سوکت یونیکس بعدی (گزینه‌های -l بعدی) یا سوکت پیش‌فرض (در صورت عدم تعیین گزینه‌های -l) تأثیر می‌گذارد؛ یعنی می‌توانید تنظیمات متفاوتی برای سوکت‌های مختلف تعیین نمایید.

حالت پیش‌فرض این است که مالکیت یا مجوزهای سوکت تغییر نکند و در نتیجه از پیش‌فرض سیستم استفاده شود.

-P command[,command[,...]]

دستورهای پذیرفته‌شده را هم از طریق سوکت شبکه و هم سوکت یونیکس مشخص می‌کند. این امر به مدیران RRDCacheD امکان می‌دهد تا کنش‌های پذیرفته‌شده از منابع مختلف را کنترل کنند.

آرگومان داده‌شده به گزینهٔ -P فهرستی از دستورها است که با کاما از هم جدا شده‌اند. برای مثال، به منظور مجاز کردن تنها دستورهای "FLUSH" و "PENDING" می‌توان چنین مشخص کرد:

rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS

گزینهٔ -P بر نشانی‌های سوکت بعدی (گزینه‌های -l بعدی) یا سوکت پیش‌فرض (در صورت عدم تعیین گزینه‌های -l) تأثیر می‌گذارد. در مثال زیر، تنها سوکت شبکهٔ IPv4 (آدرس 10.0.0.1) به دستورهای "FLUSH" و "PENDING" محدود خواهد شد:

rrdcached -l unix:/some/path -P FLUSH,PENDING -l 10.0.0.1

فهرست کاملی از دستورهای در دسترس را می‌توانید در بخش «دستورهای معتبر (Valid Commands)» در زیر بیابید. دو استثنای جزئی خاص وجود دارد:

-V log_level

برنامهٔ rrdcached در زیر بار سنگین می‌تواند لاگ‌ها را به‌شدت پر کند. این گزینهٔ خط فرمان حداکثر log_level مورد استفاده را مشخص می‌سازد، بدین معنی که پیامی با سطح پرگویی بالاتر از log_level نادیده گرفته می‌شود (LOG_EMERG کمترین و LOG_DEBUG بیشترین سطح است).

مقادیر پذیرفته‌شده برای "log_level" (از کمترین به بیشترین پرگویی): LOG_EMERG، LOG_ALERT، LOG_CRIT، LOG_ERR، LOG_WARNING، LOG_NOTICE، LOG_INFO، LOG_DEBUG

سطح لاگ پیش‌فرض هنگامی که این پرچم حضور ندارد: LOG_ERR

همچنین ببینید: syslog.h

-o log_file

ثبت وقایع در فایل داده‌شده به جای syslog.

-w timeout

داده‌ها هر timeout ثانیه یک‌بار بر روی دیسک نوشته می‌شوند. می‌توان از یک پسوند اختیاری استفاده کرد (برای نمونه "5m" به جای 300 ثانیه). اگر این گزینه مشخص نشود، بازهٔ زمانی پیش‌فرض 300 ثانیه به کار خواهد رفت.

-z delay

در صورت تعیین، rrdcached نوشتن هر RRD را به اندازهٔ یک عدد تصادفی بر حسب ثانیه در بازهٔ [0,delay) به تأخیر می‌اندازد. این عمل از صف‌بندی همزمان بیش از حد عملیات نوشتن جلوگیری می‌کند. این مقدار نباید بزرگ‌تر از مقدار تعیین‌شده در -w باشد. می‌توان از یک پسوند اختیاری استفاده کرد (برای نمونه "3m" به جای 180 ثانیه). به‌طور پیش‌فرض، هیچ تأخیری وجود ندارد.

-f timeout

هر timeout ثانیه، کل حافظهٔ نهان (cache) برای یافتن مقادیر قدیمی که روی دیسک نوشته می‌شوند، جستجو می‌شود. این عمل تنها بر روی فایل‌هایی تأثیر می‌گذارد که به‌روزرسانی آن‌ها متوقف شده است، بنابراین تنظیم این مقدار روی یک عدد بزرگ، مانند 3600 ثانیه، در بیشتر موارد قابل قبول است. می‌توان از یک پسوند اختیاری استفاده نمود (برای نمونه "1h" به جای 3600 ثانیه). این مهلت زمانی به‌طور پیش‌فرض 3600 ثانیه است.

-p file

نام و مکان فایل PID را تنظیم می‌کند. در صورت عدم تعیین، مقدار پیش‌فرض، "$localstatedir/run/rrdcached.pid" استفاده خواهد شد.

-t write_threads

تعداد ریسه‌های (threadها) استفاده‌شده برای نوشتن فایل‌های RRD را تعیین می‌کند. مقدار پیش‌فرض 4 است. افزایش این عدد به rrdcached اجازه می‌دهد تا درخواست‌های ورودی/خروجی (I/O) همزمان بیشتری را به هسته ارسال کند. این امر ممکن است به هسته امکان دهد تا ترتیب نوشتن دیسک را بازآرایی کرده و در نتیجه توان عملیاتی بهتری برای دیسک حاصل شود.

-j dir

به‌روزرسانی‌ها را در یک ژورنال در dir می‌نویسد. در صورت خرابی و توقف ناگهانی برنامه یا سیستم، این امر به دیمن اجازه می‌دهد تا هر به‌روزرسانی معلق در زمان خرابی را بر روی دیسک بنویسد.

هنگام راه‌اندازی، دیمن وجود فایل‌های ژورنال را در این دایرکتوری بررسی می‌کند. در صورت یافت شدن، پیش از آنکه دیمن پذیرش اتصالات جدید را آغاز کند، تمام به‌روزرسانی‌های درون آن به داخل حافظه خوانده خواهند شد.

ژورنال با همان بسامد زمان‌سنج flush مشخص‌شده با -f چرخش داده می‌شود.

هنگامی که ژورنال‌سازی فعال باشد، دیمن از یک فرایند خاموش‌سازی سریع استفاده می‌کند. به جای نوشتن همهٔ فایل‌ها روی دیسک، اطمینان حاصل می‌کند که ژورنال به درستی نوشته شده است و بلافاصله خارج می‌شود. اگرچه فایل‌های داده RRD کاملاً به‌روز نخواهند بود، اما هیچ اطلاعاتی از دست نرفته است؛ دفعهٔ بعد که دیمن راه‌اندازی شود، همهٔ به‌روزرسانی‌های معلق از روی ژورنال بازپخش خواهند شد.

برای غیرفعال کردن خاموش‌سازی سریع، از گزینهٔ -F استفاده کنید..IP -F 4 صرف‌نظر از تنظیمات journal، هنگام خاموش شدن دیمن همواره تمام به‌روزرسانی‌ها را به فایل‌های دادهٔ RRD منتقل (flush) می‌کند.

-g

اجرا در پیش‌زمینه. دیمن fork() نخواهد کرد.

-b dir

دیمن در هنگام راه‌اندازی به یک دایرکتوری مشخص تغییر مسیر می‌دهد. تمام فایل‌های ارسال‌شده به دیمن که با یک مسیر نسبی مشخص شده‌اند، نسبت به این دایرکتوری تفسیر خواهند شد. اگر مشخص نشود، پیش‌فرض، یعنی "/tmp"، استفاده خواهد شد.

+------------------------+------------------------+
! Command line           ! File updated           !
+------------------------+------------------------+
! foo.rrd                ! /tmp/foo.rrd           !
! foo/bar.rrd            ! /tmp/foo/bar.rrd       !
! /var/lib/rrd/foo.rrd   ! /var/lib/rrd/foo.rrd   !
+------------------------+------------------------+
Paths given on the command  line and paths actually
updated by the daemon,  assuming the base directory
"/tmp".

هشدار: مسیرهای منتهی به دایرکتوری پایه و خود آن نباید پیوند نمادین (symbolic link) باشند. به عبارت دیگر، اگر دایرکتوری پایه به صورت زیر مشخص شده باشد:

-b /base/dir/somewhere

... آنگاه هیچ‌یک از موارد زیر نباید پیوند نمادین باشند:

/base
/base/dir
/base/dir/somewhere

-B

تنها اجازهٔ نوشتن در دایرکتوری پایهٔ مشخص‌شده در -b (و هر زیردایرکتوری آن) را می‌دهد. این گزینه پیوندهای نمادین را شناسایی نمی‌کند. مسیرهای حاوی "../" نیز مسدود خواهند شد.

-R

اجازهٔ ایجاد بازگشتی زیردایرکتوری در دایرکتوری پایهٔ مشخص‌شده در -b (و هر زیردایرکتوری آن) را می‌دهد. فقط زمانی می‌تواند استفاده شود که -B نیز تنظیم شده باشد.

-a alloc_size

اشاره‌گرهای مقدار را در تکه‌هایی به اندازهٔ alloc_size تخصیص می‌دهد. این کار ممکن است در سیستم‌هایی با پیاده‌سازی‌های کندِ realloc()، در ازای مصرف حافظهٔ کمی بیشتر، بهره‌وری CPU را بهبود بخشد. پیش‌فرض 1 است. این مقدار را بیشتر از مقدار -w تقسیم بر میانگین اندازهٔ step در RRD خود تنظیم نکنید.

-O

جلوگیری از بازنویسی فایل‌های موجود توسط دستور CREATE، حتی اگر صریحاً به آن دستور داده شده باشد. این قابلیت برای امنیت بیشتر است.

-G -group

هنگام اجرا به عنوان دیمن و فراخوانی از یک حساب کاربری ممتاز، امتیازات گروه را به امتیازات group بازنشانی می‌کند. گروه می‌تواند به صورت یک نام یا یک شناسهٔ گروه مشخص شود. اگر دیمن نتواند با موفقیت به گروه مشخص‌شده منتقل شود، با یک پیام تشخیصی خارج خواهد شد.

-U -user

هنگام اجرا به عنوان دیمن و فراخوانی از یک حساب کاربری ممتاز، امتیازات کاربر را به امتیازات user بازنشانی می‌کند. کاربر می‌تواند به صورت یک نام یا یک شناسهٔ کاربر مشخص شود. اگر دیمن نتواند با موفقیت به کاربر مشخص‌شده منتقل شود، با یک پیام تشخیصی خارج خواهد شد.

دستورهای تحت تأثیر RRDTOOL (AFFECTED RRDTOOL COMMANDS)

دستورهای زیر را می‌توان با استفاده از آرگومان خط فرمان --daemon یا متغیر محیطی RRDCACHED_ADDRESS از وجود rrdcached آگاه ساخت:

• dump
• fetch
• flush
• graph
• graphv
• info
• first
• last
• lastupdate
• update
• xport
• create
• list

دستور update می‌تواند مقادیر را به جای نوشتن مستقیم روی دیسک، به دیمن ارسال کند. همهٔ دستورهای دیگر می‌توانند پیش از دسترسی به فایل‌ها، یک دستور FLUSH (به زیر مراجعه کنید) به دیمن ارسال کنند تا حتی اگر مهلت زمانی حافظهٔ نهان بزرگ باشد، با داده‌های به‌روز کار کنند..SH "گزارش خطاها (ERROR REPORTING)" دیمن خطاها را به یکی از دو روش گزارش می‌کند: در طول راه‌اندازی، پیام‌های خطا در "STDERR" چاپ می‌شوند. یکی از مراحل هنگام راه‌اندازی، انشعاب (fork) به پس‌زمینه و بستن "STDERR" است - پس از این، نوشتن مستقیم برای کاربر دیگر امکان‌پذیر نیست. پس از رخ دادن این امر، دیمن پیام‌های گزارش (log) را با استفاده از syslog(3) به دیمن ثبت وقایع سیستم ارسال خواهد کرد. تسهیلات (facility) مورد استفاده "LOG_DAEMON" است.

نحوه کارکرد (HOW IT WORKS)

هنگام دریافت یک به‌روزرسانی، rrdcached روی دیسک نمی‌نویسد، بلکه در درخت داخلی خود به دنبال مدخلی برای آن فایل می‌گردد. در صورت پیدا نشدن، مدخلی شامل زمان فعلی (که در نمودار زیر «First» نامیده شده) ایجاد می‌شود. این زمان، زمانی که در خط فرمان مشخص شده نیست، بلکه زمانی است که سیستم‌عامل آن را «اکنون» در نظر می‌گیرد. مقدار و زمان آن مقدار (که در نمودار زیر «Time» نامیده شده) به گره درخت پیوست می‌شوند.

هنگام افزودن یک مقدار به یک گره درخت، بررسی می‌شود که آیا زمان نوشتن مقادیر روی دیسک فرا رسیده است یا خیر. مقادیر در صورتی روی دیسک نوشته می‌شوند که "now() - First >= timeout" باشد، که در آن "timeout" مهلت زمانی مشخص‌شده با استفاده از گزینهٔ -w است؛ «گزینه‌ها (OPTIONS)» را ببینید. اگر مقادیر «به‌اندازهٔ کافی قدیمی» باشند، در «صف به‌روزرسانی» (update queue) قرار می‌گیرند؛ یعنی به فهرست پیوندیِ نشان‌داده‌شده در زیر پیوست می‌شوند. از آنجا که گره‌های درخت و عناصر فهرست پیوندی ساختار دادهٔ یکسانی در حافظه هستند، هر به‌روزرسانی برای فایلی که پیش‌تر در صف قرار گرفته است نیز همراه با نوشتن بعدی در فایل RRD نوشته خواهد شد.

یک «رشتهٔ به‌روزرسانی» (update thread) جداگانه به‌طور مداوم نخستین عنصر را از صف به‌روزرسانی خارج می‌کند (dequeue) و همهٔ مقادیر آن را در فایل مربوطه می‌نویسد. بنابراین تا زمانی که صف به‌روزرسانی خالی نباشد، فایل‌ها با بالاترین نرخ ممکن نوشته می‌شوند.

از آنجا که انقضای زمان فایل‌ها تنها هنگامی بررسی می‌شود که مقادیر جدید به فایل افزوده شوند، فایل‌های «مرده»، یعنی فایل‌هایی که دیگر به‌روزرسانی نمی‌شوند، هرگز روی دیسک نوشته نخواهند شد. از این رو، هر از گاهی با کنترلِ گزینهٔ -f، کل درخت پیمایش شده و تمام مقادیر «قدیمی» در صف قرار می‌گیرند. از آنجا که این عمل تنها بر فایل‌های «مرده» اثر می‌گذارد و پیمایش درخت نسبتاً پرهزینه است، باید «بازهٔ فلاش» (flush interval) را روی مقداری به‌اندازهٔ کافی بالا تنظیم کنید. مقدار پیش‌فرض ۳۶۰۰ ثانیه (یک ساعت) است.

نقطهٔ ضعف ذخیرهٔ موقت (caching) مقادیر این است که آن‌ها در نمودارهای تولیدشده از فایل‌های RRD نمایش داده نخواهند شد. برای دور زدن این مشکل، دیمن «دستور flush» را برای تخلیهٔ داده‌های فایل‌های خاص فراهم می‌کند. این بدان معناست که فایل در ابتدای (head) صف به‌روزرسانی درج شده یا اگر پیش‌تر در صف قرار گرفته باشد، به آنجا منتقل می‌شود. دستور flush تنها پس از اینکه به‌روزرسانی‌های معلق فایل روی دیسک نوشته شدند بازخواهد گشت.

+------+   +------+                               +------+
! head !   ! root !                               ! tail !
+---+--+   +---+--+                               +---+--+
    !         /\                                      !
    !        /  \                                     !
    !       /\  /\                                    !
    !      /\/\ \ `----------------- ... --------,    !
    V     /      `-------,                       !    V
+---+----+---+    +------+-----+             +---+----+---+
! File:  foo !    ! File:  bar !             ! File:  qux !
! First: 101 !    ! First: 119 !             ! First: 180 !
! Next:&bar -+--->! Next:&... -+---> ... --->! Next:NULL  !
| Prev:NULL  !<---+-Prev:&foo  !<--- ... ----+-Prev: &... !
+============+    +============+             +============+
! Time:  100 !    ! Time:  120 !             ! Time:  180 !
! Value:  10 !    ! Value: 0.1 !             ! Value: 2,2 !
+------------+    +------------+             +------------+
! Time:  110 !    ! Time:  130 !             ! Time:  190 !
! Value:  26 !    ! Value: 0.1 !             ! Value: 7,3 !
+------------+    +------------+             +------------+
:            :    :            :             :            :
+------------+    +------------+             +------------+
! Time:  230 !    ! Time:  250 !             ! Time:  310 !
! Value:  42 !    ! Value: 0.2 !             ! Value: 1,2 !
+------------+    +------------+             +------------+

نمودار بالا موارد زیر را نشان می‌دهد:

• فایل‌ها/مقادیر در یک درخت (متوازن) ذخیره می‌شوند.
• گره‌های درخت و مدخل‌های موجود در صف به‌روزرسانی، ساختار دادهٔ یکسانی هستند.
• زمان محلی («First») و زمان مشخص‌شده در به‌روزرسانی‌ها («Time») ممکن است تفاوت داشته باشند.
• مقادیر زمان‌منقضی‌شده در انتها («tail») درج می‌شوند.
• مقادیری که به‌صراحت فلاش شده‌اند در ابتدا («head») درج می‌شوند.
• هنر اسکی (ASCII art) معرکه است..SH "ملاحظات امنیتی (SECURITY CONSIDERATIONS)"

پروتکل (PROTOCOL)

دیمن با استفاده از یک پروتکل خط‌محور ASCII با کلاینت‌ها ارتباط برقرار می‌کند که خواندن و نوشتن آن آسان است. این امر پیاده‌سازی پروتکل را برای اسکریپت‌ها آسان کرده و به کاربران امکان می‌دهد با استفاده از telnet به دیمن متصل شده و موارد را «دستی» آزمایش کنند.

این پروتکل خط‌محور است؛ بدین معنا که هر رکورد از یک یا چند خط تشکیل شده است. یک خط با نویسه تغذیه سطر (line feed) یعنی 0x0A پایان می‌یابد که معمولاً به‌صورت "\n" نوشته می‌شود. در مثال‌های زیر، این نویسه به‌صورت "<LF>" («line feed») نوشته خواهد شد.

پس از برقراری اتصال، انتظار می‌رود کلاینت یک «دستور» ارسال کند. یک دستور شامل کلیدواژه دستور، احتمالاً تعدادی آرگومان و یک نویسه پایان‌دهنده خط جدید (newline) است. برای مشاهده فهرست دستورها، بخش «Valid Commands» در ادامه را ببینید.

مثال:

FLUSH /tmp/foo.rrd<LF>

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

مثال‌ها:

 0 Success<LF>
 2 Two lines follow<LF>
 This is the first line<LF>
 And this is the second line<LF>
دستورهای زیر توسط دیمن پشتیبانی می‌شوند:

FLUSH filename

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

FLUSHALL

باعث می‌شود دیمن شروع به تخلیهٔ تمام (ALL) مقادیر معلق روی دیسک کند. این دستور
فوراً بازمی‌گردد، حتی اگر انجام نوشتن‌ها زمان زیادی ببرد.

PENDING filename

به‌روزرسانی‌های «معلق» را برای یک فایل به ترتیب نمایش می‌دهد. به‌روزرسانی‌های نشان‌داده‌شده
هنوز روی فایل RRD زیرین نوشته نشده‌اند.

FETCH filename CF [start [end] [ds ...]]

تابع "rrd_fetch" را با آرگومان‌های مشخص‌شده فراخوانی کرده و نتیجه را در قالب متنی
بازمی‌گرداند. در صورت نیاز، فایل ابتدا روی دیسک تخلیه می‌شود. تابع سمت کلاینت
"rrdc_fetch" (تعریف‌شده در "rrd_client.h") خروجی را پردازش (parse) کرده و برای
یکپارچه‌سازی آسان پرس‌وجوهای از راه دور، دقیقاً مانند "rrd_fetch_r" رفتار می‌کند.
پارامتر ds ستون‌هایی را برای برون‌ریزی (dump) تعیین می‌کند - اگر مقداری مشخص نشود، همه بازگردانده می‌شوند.

FETCHBIN filename CF [start [end] [ds ...]]

تابع "rrd_fetch" را با آرگومان‌های مشخص‌شده فراخوانی کرده و برای جلوگیری از سربارِ غیرضروریِ
تبدیل ساختار داده (un/marshalling)، نتیجه را در قالب متنی/دودویی بازمی‌گرداند.
در صورت نیاز، فایل ابتدا روی دیسک تخلیه می‌شود. تابع سمت کلاینت
"rrdc_fetch" (تعریف‌شده در "rrd_client.h") خروجی را پردازش کرده و برای
یکپارچه‌سازی آسان پرس‌وجوهای از راه دور، دقیقاً مانند "rrd_fetch_r" رفتار می‌کند.
پارامتر ds ستون‌هایی را برای برون‌ریزی تعیین می‌کند - اگر مقداری مشخص نشود، همه بازگردانده می‌شوند.

FORGET filename

فایل filename را از حافظهٔ موقت (کَش) حذف می‌کند. هر به‌روزرسانیِ معلقی از دست خواهد رفت.

QUEUE

فایل‌هایی را که در صف خروجی قرار دارند نمایش می‌دهد. صفر یا چند خط در قالب زیر
بازمی‌گرداند، که در آن <num_vals> تعداد مقادیر قابل نوشتن برای <file> است:
    <num_vals> <file>

HELP [command]

پیام راهنمای کوتاهی از نحوهٔ کاربرد را بازمی‌گرداند. اگر دستوری داده نشود، یا command برابر با HELP باشد، فهرستی از دستورهای پشتیبانی‌شده توسط دیمن بازگردانده می‌شود. در غیر این صورت، توضیح کوتاهی بازگردانده می‌شود که احتمالاً حاوی اشاره‌ای به یک صفحهٔ راهنما (manual page) است. واضح است که این دستور برای استفادهٔ تعاملی در نظر گرفته شده و قالبی که دستورها و خلاصه‌های کاربرد در آن بازگردانده می‌شوند ساختار کاملاً معینی ندارد.

STATS

فهرستی از سنجه‌ها (metrics) را بازمی‌گرداند که می‌توان از آن‌ها برای سنجش کارایی دیمن و بررسی وضعیت آن استفاده کرد. برای شرح مقادیر بازگردانده‌شده، بخش «Performance Values» را در زیر ببینید.

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

مثال:

9 Statistics follow
QueueLength: 0
UpdatesReceived: 30
FlushesReceived: 2
UpdatesWritten: 13
DataSetsWritten: 390
TreeNodesNumber: 13
TreeDepth: 4
JournalBytes: 190
JournalRotate: 0

PING

دستور PING-PONG؛ این دستور هنگام استفاده از استخر اتصالات (connection pool) بین کلاینت کاربر و RRDCACHED بسیار مفید است.

مثال:

0 PONG

UPDATE filename values [values ...]

داده‌های بیشتری را به یک نام‌فایل اضافه می‌کند. این همان عملیاتی است که دیمن برای آن طراحی شده، بنابراین شرح دوبارهٔ سازوکار آن ضرورتی ندارد. برای توضیحات دقیق‌تر، بخش «HOW IT WORKS» در بالا را بخوانید.

توجه داشته باشید که rrdcached تنها برچسب‌های زمانی مطلق را در مقادیر به‌روزرسانی می‌پذیرد. رشته‌های به‌روزرسانی مانند «N:1:2:3» پیش از ارسال به rrdcached، توسط کتابخانهٔ کلاینت RRD به‌طور خودکار به زمان مطلق تبدیل می‌شوند.

WROTE filename

این دستور پس از نوشته شدن موفقیت‌آمیز یک فایل روی دیسک، در ژورنال نوشته می‌شود. این دستور هنگام بازپخش ژورنال (journal replay) برای تعیین اینکه کدام به‌روزرسانی‌ها پیش‌تر اعمال شده‌اند، به کار می‌رود. این دستور فقط در ژورنال معتبر است؛ و از دیگر کانال‌های دستور پذیرفته نمی‌شود.

FIRST filename [rranum]

برچسب زمانی اولین CDP را در RRA مشخص‌شده بازمی‌گرداند. پیش‌فرض در صورت عدم تعیین، استفاده از RRA صفر است.

LAST filename

برچسب زمانی آخرین به‌روزرسانی RRD مشخص‌شده را بازمی‌گرداند. توجه داشته باشید که کَش پیش از بررسی تخلیه نمی‌شود، چرا که انتظار می‌رود کلاینت در صورت نیاز، این کار را جداگانه درخواست کند.

INFO filename

اطلاعات پیکربندی RRD مشخص‌شده را بازمی‌گرداند. توجه داشته باشید که کَش پیش از بررسی تخلیه نمی‌شود، چرا که انتظار می‌رود کلاینت در صورت نیاز، این کار را جداگانه درخواست کند.

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

I<keyname> I<type> I<value>

CREATE filename [-s stepsize] [-b begintime] [-r sourcefile ...] [-t templatefile] [-O] DSdefinitions ... RRAdefinitions ...

این دستور فایل RRD را بر اساس پارامترهای ارائه‌شده ایجاد می‌کند، به شرطی که پارامترها معتبر باشند و (در صورتی که گزینهٔ -O داده شده باشد یا rrdcached با پرچم -O آغاز به کار کرده باشد) filename مشخص‌شده از قبل وجود نداشته باشد.

BATCH

این دستور بارگذاری انبوه (bulk load) چندین دستور را آغاز می‌کند. این ویژگی برای سامانه‌هایی با نرخ به‌روزرسانی بسیار بالا طراحی شده است، چرا که اجازه می‌دهد به ازای هر read() و write() بیش از یک دستور صادر شود.

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

پردازش دستور زمانی پایان می‌یابد که کلاینت یک نقطه («.») را در خطی جداگانه ارسال کند. پس از اینکه کلاینت به کار خود پایان داد، سرور با تعداد خطاها و فهرست پیام‌های خطا (در صورت وجود) پاسخ می‌دهد. هر پیام خطا نشان‌دهندهٔ شمارهٔ دستوری است که به آن مربوط می‌شود، همراه با متن خودِ پیام خطا. نخستین دستور کاربر پس از BATCH، دستور شمارهٔ یک است.

client:  BATCH
server:  0 Go ahead.  End with dot '.' on its own line.
client:  UPDATE x.rrd 1223661439:1:2:3            <--- command #1
client:  UPDATE y.rrd 1223661440:3:4:5            <--- command #2
client:  and so on...
client:  .
server:  2 Errors
server:  1 message for command 1
server:  12 message for command 12

LIST [RECURSIVE] I/<path>

این دستور امکان فهرست‌کردن دایرکتوری‌ها و پایگاه‌های دادهٔ rrd را همان‌گونه که توسط دیمن دیده می‌شوند، فراهم می‌کند. «دایرکتوری» ریشه همان base_dir است ('-b dir' را ببینید). هنگامی که با 'LIST RECURSIVE /<path>' فراخوانی شود، رفتاری مشابه با 'ls -R' خواهد داشت، اما محدود به فایل‌های rrd است (فهرست‌کردن تمام پایگاه‌های rrd در زیردرخت <path>، و نادیده‌گرفتن دایرکتوری‌های خالی).

SUSPEND filename

نوشتن روی یک فایل RRD را به حالت تعلیق درمی‌آورد. تا زمانی که یک فایل در حالت تعلیق است، تمام سنجه‌های آن در حافظه کَش می‌شوند تا زمانی که برای آن فایل RESUME یا RESUMEALL فراخوانی شود.

RESUME filename

نوشتن روی یک فایل RRD را که قبلاً توسط SUSPEND یا SUSPENDALL معلق شده بود، از سر می‌گیرد.

SUSPENDALL

نوشتن روی همهٔ فایل‌های RRD را به حالت تعلیق درمی‌آورد. تا زمانی که فایلی در حالت تعلیق است، تمام سنجه‌های آن در حافظه کَش می‌شوند تا زمانی که برای آن فایل RESUME یا RESUMEALL فراخوانی شود.

RESUMEALL

نوشتن روی همهٔ فایل‌های RRD را که قبلاً توسط SUSPEND یا SUSPENDALL معلق شده بودند، از سر می‌گیرد.

QUIT

قطع اتصال از rrdcached..SS "مقادیر عملکرد (Performance Values)" شمارنده‌های زیر توسط دستور STATS بازگردانده می‌شوند:

QueueLength (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد گره‌هایی که در حال حاضر در صف به‌روزرسانی قرار دارند.

UpdatesReceived (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد دستورهای UPDATE دریافت‌شده.

FlushesReceived (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد دستورهای FLUSH دریافت‌شده.

UpdatesWritten (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد کل به‌روزرسانی‌ها، یعنی فراخوانی‌های "rrd_update_r"، از زمان راه‌اندازی دیمن.

DataSetsWritten (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد کل «مجموعه‌داده‌ها»ی نوشته‌شده روی دیسک از زمان راه‌اندازی دیمن. یک مجموعه‌داده، یک یا چند مقدار ارسال‌شده به دستور UPDATE است. برای مثال: "1223661439:123:456" یک مجموعه‌داده با دو مقدار است. اصطلاح «مجموعه‌داده» برای جلوگیری از سردرگمی در مورد این‌که آیا مقادیر تکی یا گروه‌هایی از مقادیر شمرده می‌شوند، به کار رفته است.

TreeNodesNumber (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد گره‌های موجود در حافظهٔ پنهان.

TreeDepth (عدد صحیح ۶۴ بیتی بدون علامت)

عمق درخت مورد استفاده برای جست‌وجوی سریع کلید.

JournalBytes (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد کل بایت‌های نوشته‌شده در ژورنال از زمان راه‌اندازی.

JournalRotate (عدد صحیح ۶۴ بیتی بدون علامت)

تعداد دفعاتی که ژورنال از زمان راه‌اندازی چرخانده شده است (rotate).

سیگنال‌ها (SIGNALS)

SIGINT و SIGTERM

دیمن با دریافت هر یک از این سیگنال‌ها به طور عادی خارج می‌شود. به به‌روزرسانی‌های معلق مطابق با گزینه‌های -j و -F رسیدگی می‌شود.

SIGUSR1

دیمن پس از تخلیهٔ تمام به‌روزرسانی‌ها روی دیسک خارج می‌شود. این عمل ممکن است مدتی زمان ببرد.

SIGUSR2

دیمن بلافاصله بدون تخلیهٔ به‌روزرسانی‌ها روی دیسک خارج می‌شود. هنگام راه‌اندازی مجدد دیمن، به‌روزرسانی‌های معلق از ژورنال بازپخش خواهند شد. هشدار: اگر ژورنال‌نویسی (-j) فعال نباشد، تمام به‌روزرسانی‌های معلق از دست خواهند رفت.

گزارش باگ‌ها (BUGS)

در حال حاضر باگ شناخته‌شده‌ای وجود ندارد.

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

rrdtool, rrdgraph

نویسندگان (AUTHORS)

Florian Forster <octo at verplant.org>

هم rrdcached و هم این صفحهٔ راهنما توسط Florian نوشته شده‌اند.

مشارکت‌کنندگان (CONTRIBUTORS)

kevin brintnall <kbrint@rufus.net> Steve Shipway <steve@steveshipway.org> Martin Sperl <rrdtool@martin.sperl.org>