vinylncsa(1) General Commands Manual vinylncsa(1)

vinylncsa - نمایش لاگ‌های Vinyl Cache در قالب لاگ ترکیبی Apache / NCSA

vinylncsa [-a] [-b] [-c] [-C] [-d] [-D] [-E] [-F <format>] [-f <formatfile>] [-g <request|vxid>] [-h] [-j] [-k <num>] [-L <limit>] [-n <workdir>] [-P <file>] [-Q <file>] [-q <query>] [-r <filename>] [-R <limit[/duration]>] [-t <seconds|off>] [-V] [-w <filename>]

ابزار vinylncsa لاگ‌های حافظهٔ اشتراکی vinyld(1) را خوانده و آن‌ها را در قالب لاگ "combined" آپاچی / NCSA نمایش می‌دهد.

هر خط لاگ تولید شده بر اساس یک تراکنش منفرد از نوع Request است که از لاگ حافظهٔ اشتراکی جمع‌آوری شده است. سپس تراکنش Request برای یافتن بخش‌های مرتبط بررسی می‌شود تا یک خط لاگ خروجی تولید گردد. برای فیلتر کردن خطوط لاگ تولیدی، از زبان پرس‌وجو جهت انتخاب تراکنش‌های مربوطه استفاده کنید. تراکنش‌های غیر-Request نادیده گرفته می‌شوند.

گزینه‌های زیر در دسترس هستند:

هنگام نوشتن خروجی در یک فایل، به جای بازنویسی، به انتهای آن الحاق (append) شود. این گزینه بدون گزینهٔ -w هیچ اثری ندارد.
ثبت لاگ درخواست‌های backend. اگر -c مشخص نشده باشد، فقط درخواست‌های backend خطوط لاگ را ایجاد می‌کنند.
ثبت لاگ درخواست‌های client. این حالت پیش‌فرض است. در صورت مشخص شدن -b، برای ثبت لاگ درخواست‌های client نیز به گزینهٔ -c نیاز است.
انجام تطابق همهٔ عبارات باقاعده (regular expressions) و رشته‌ها بدون حساسیت به حروف کوچک و بزرگ (caseless).
پردازش رکوردهای لاگ در ابتدای لاگ و سپس خروج.
اجرا در پس‌زمینه به عنوان دیمن (Daemonize).
نمایش درخواست‌های ESI؛ این گزینه مستلزم حالت client است.
تنظیم رشتهٔ قالب خروجی لاگ.
خواندن قالب خروجی از یک فایل. یک خط منفرد از فایل مشخص‌شده خوانده شده و از آن به عنوان قالب استفاده می‌شود.
گروه‌بندی رکوردهای لاگ. حالت پیش‌فرض گروه‌بندی بر اساس vxid است.
نمایش نحوهٔ استفاده از برنامه و خروج.
سازگار کردن جایگزین‌های مشخص‌کنندهٔ قالب با JSON. هنگام گریزدهی (escape) نویسه‌ها، به جای توالی‌های گریز سبک C مانند \xXX از توالی‌های گریز سبک JSON مانند \uXXXX استفاده می‌شود. رشته‌های خالی به جای "-" با "" جایگزین شده و مقادیر صحیح خالی با null جایگزین می‌شوند. برای نوشتن لاگ‌های JSON از -F یا -f در ترکیب با -j استفاده کنید.
پردازش این تعداد از تراکنش‌های لاگ مطابقت‌یافته پیش از خروج.
حد بالای تراکنش‌های ناقص نگه‌داری‌شده را قبل از آنکه قدیمی‌ترین تراکنش به صورت اجباری تکمیل شود، تعیین می‌کند. هنگام وقوع این رویداد یک رکورد هشدار تولید می‌شود. این تنظیم سقفی بر مصرف حافظهٔ پرس‌وجوهای در حال اجرا اعمال می‌کند. مقدار پیش‌فرض ۱۰۰۰ تراکنش است.
دایرکتوری کاری vinyl مربوط به نمونه‌ای که باید به آن متصل شد را مشخص می‌کند. برای اطلاعات بیشتر و مقادیر پیش‌فرض به مستندات گزینهٔ -n در vinyld(1) مراجعه کنید.
نوشتن PID فرایند در فایل مشخص‌شده.
فایل حاوی پرس‌وجوی VSL مورد استفاده را مشخص می‌کند. زمانی که چندین گزینهٔ -Q یا -q مشخص شده باشند، تمام پرس‌وجوها به گونه‌ای در نظر گرفته می‌شوند که گویی با عملگر 'or' با یکدیگر ترکیب شده‌اند.
پرس‌وجوی VSL مورد استفاده را مشخص می‌کند. زمانی که چندین گزینهٔ -q یا -Q مشخص شده باشند، تمام پرس‌وجوها به گونه‌ای در نظر گرفته می‌شوند که گویی با عملگر 'or' با یکدیگر ترکیب شده‌اند.
خواندن لاگ در قالب فایل باینری از این فایل. این فایل می‌تواند با vinyllog -w filename ایجاد شود. اگر نام فایل - باشد، لاگ‌ها از ورودی استاندارد خوانده می‌شوند و برنامه نمی‌تواند به عنوان دیمن کار کند.
محدود کردن خروجی به حد مشخص‌شده. تراکنش‌هایی که از این حد فراتر روند نادیده گرفته می‌شوند. این حد به صورت حداکثر تعداد تراکنش‌ها (با توجه به روش گروه‌بندی انتخابی) و یک دورهٔ زمانی اختیاری مشخص می‌شود. اگر هیچ مدت زمانی تعیین نشود، مقدار پیش‌فرض s استفاده می‌شود. فیلد مدت زمان می‌تواند مانند VCL قالب‌بندی شود (مانند -R 10/2m) یا به صورت یک بازه زمانی ساده بدون پیشوند باشد (مانند -R 5/m). در حالت گروه‌بندی -g raw، این تنظیم نمی‌تواند همراه با -i، -I، -x یا -X استفاده شود و توصیه می‌کنیم به جای آن از -q استفاده کنید.
مدت زمان انتظار (timeout) قبل از بازگرداندن خطا در اتصال اولیه VSM. در صورت تنظیم، تلاش برای برقراری اتصال VSM هر 0.5 ثانیه به مدت ثانیه‌های تعیین‌شده تکرار می‌شود. در صورت صفر بودن، اتصال تنها یک بار امتحان می‌شود و در صورت ناموفق بودن بلافاصله شکست می‌خورد. اگر روی "off" تنظیم شود، اتصال با شکست مواجه نخواهد شد و به ابزار اجازه می‌دهد شروع به کار کرده و به طور نامحدود منتظر پدیدار شدن نمونهٔ vinyld بماند. مقدار پیش‌فرض ۵ ثانیه است.
نمایش اطلاعات نسخه و خروج.
هدایت خروجی به فایل. فایل بازنویسی خواهد شد مگر اینکه گزینهٔ -a مشخص شده باشد. اگر برنامه در حالت دیمن سیگنال SIGHUP را دریافت کند، فایل مجدداً باز خواهد شد که امکان چرخش (rotate) فایل قدیمی را فراهم می‌کند. این گزینه هنگام اجرا در حالت دیمن الزامی است. اگر نام فایل - باشد، vinylncsa در خروجی استاندارد می‌نویسد و نمی‌تواند به عنوان دیمن کار کند.
چاپ پارامتر optstring برای تابع getopt(3) جهت کمک به نوشتن اسکریپت‌های پوششی (wrapper).

حالت پیش‌فرض vinylncsa «حالت کلاینت» ("client mode") است. در این حالت، لاگ شبیه به خروجی یک وب‌سرور در غیاب Vinyl Cache خواهد بود. حالت کلاینت را می‌توان به‌طور صریح با استفاده از -c انتخاب کرد.

اگر سوییچ -b مشخص شود، vinylncsa در «حالت بک‌اند» ("backend mode") کار خواهد کرد. در این حالت، درخواست‌های ایجاد شده توسط Vinyl Cache به بک‌اندها لاگ خواهند شد. مگر اینکه -c نیز مشخص شده باشد، درخواست‌های کلاینت دریافت شده توسط vinyld نادیده گرفته خواهند شد.

هنگام اجرای vinylncsa در هر دو حالت بک‌اند و کلاینت، اکیداً توصیه می‌شود که مشخص‌کننده قالب %{Vinyl:side}x را برای تمایز بین درخواست‌های بک‌اند و کلاینت بگنجانید.

درخواست‌های کلاینتی که منجر به pipe می‌شوند (یعنی return(pipe) در vcl)، در حالت بک‌اند لاگی تولید نخواهند کرد. دلیل این امر این است که Vinyl Cache درخواستی ایجاد نمی‌کند، بلکه بایت‌ها را کورکورانه در هر دو جهت عبور می‌دهد. با این حال، یک نمونه vinylncsa که در حالت عادی اجرا می‌شود می‌تواند با استفاده از قالب‌ساز %{Vinyl:handling}x که مقدار آن 'pipe' خواهد بود، این مورد را ثبت کند.

در حالت بک‌اند، برخی از فیلدهای موجود در رشته قالب معانی متفاوتی پیدا می‌کنند. به‌ویژه، قالب‌سازهای شمارش بایت (%b، %I، %O) برنامه vinyld را به عنوان کلاینت در نظر می‌گیرند.

امکان اجرای هم‌زمان دو نمونه vinylncsa وجود دارد؛ یکی در حالت بک‌اند و دیگری در حالت کلاینت، که در فایل‌های متفاوتی لاگ ثبت می‌کنند.

قالب لاگ مورد استفاده را مشخص کنید. اگر هیچ قالبی مشخص نشود، قالب پیش‌فرض لاگ به کار می‌رود:

%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-agent}i"

دنباله‌های گریز \n و \t پشتیبانی می‌شوند.

قالب‌سازهای پشتیبانی‌شده عبارتند از:

%b
در حالت کلاینت، اندازه پاسخ به بایت، بدون احتساب سرآیندهای HTTP. در حالت بک‌اند، تعداد بایت‌های دریافتی از بک‌اند، بدون سرآیندهای HTTP. در قالب CLF، یعنی یک '-' به جای 0 در صورتی که هیچ بایتی ارسال نشده باشد.
%D
در حالت کلاینت، زمان صرف‌شده برای پاسخ‌گویی به درخواست، به میکروثانیه. در حالت بک‌اند، زمان از لحظه ارسال درخواست تا دریافت کامل بدنه (body). این معادل %{us}T است.
%H
پروتکل درخواست. در صورت نامشخص بودن، پیش‌فرض HTTP/1.0 است.
%h
میزبان دوردست (Remote host). در صورت نامشخص بودن، پیش‌فرض '-' است. در حالت بک‌اند، این مقدار آدرس IP سرور بک‌اند است.
%I
در حالت کلاینت، کل بایت‌های دریافتی از کلاینت. در حالت بک‌اند، کل بایت‌های ارسالی به بک‌اند.
%{X[:first|last]}i
محتوای سرآیند درخواست X پیش از هرگونه پردازش VCL برای سمت کلاینت، و پیش از vcl_backend_response برای سمت بک‌اند. اگر سرآیند چندین بار در یک تراکنش ظاهر شود، در حالت بک‌اند آخرین مورد و در حالت کلاینت اولین مورد استفاده می‌شود.

اگر بخش اختیاری :first یا :last استفاده شود، پردازش VCL در نظر گرفته خواهد شد و قاعده تطابق به ترتیب اولین تطابق یا آخرین تطابق خواهد بود. هنگام استفاده از :last، سرآیندهای حذف‌شده (unset) نیز همچنان ثبت خواهند شد.

%l
نام لاگ راه دور (Remote logname). همیشه '-' است.
%m
متد درخواست. در صورت نامشخص بودن، پیش‌فرض '-' است.
%{X[:first|last]}o
محتوای سرآیند پاسخ X، همان‌طور که در حالت کلاینت تحویل داده شده، و پیش از پردازش VCL برای حالت بک‌اند. اگر سرآیند چندین بار در یک تراکنش تکرار شود، در حالت کلاینت آخرین مورد و در حالت بک‌اند اولین مورد استفاده می‌شود.

اگر بخش اختیاری :first یا :last استفاده شود، پردازش VCL در نظر گرفته خواهد شد و قاعده تطابق به ترتیب اولین تطابق یا آخرین تطابق خواهد بود. هنگام استفاده از :last، سرآیندهای حذف‌شده (unset) نیز همچنان ثبت خواهند شد.

%O
در حالت کلاینت، کل بایت‌های ارسالی به کلاینت. در حالت بک‌اند، کل بایت‌های دریافتی از بک‌اند.
%q
رشته پرس‌وجو (Query string). در صورت عدم وجود، پیش‌فرض یک رشته خالی است.
%r
سطر اول درخواست. این مقدار از فیلدهای دیگر ساخته می‌شود، بنابراین ممکن است عیناً متن خود درخواست نباشد. بخش یادداشت‌ها (NOTES) را ببینید.
%s
وضعیت (Status) ارسال‌شده به کلاینت. در حالت بک‌اند، وضعیت دریافتی از بک‌اند است.
%t
در حالت کلاینت، زمان دریافت درخواست در قالب تاریخ/زمان HTTP. در حالت بک‌اند، زمان ارسال درخواست است.
%{X}t
در حالت کلاینت، زمان دریافت درخواست در قالبی که با X مشخص شده است. در حالت بک‌اند، زمان ارسال درخواست است. قالب مشخص‌کننده زمان همانند strftime(3) همراه با این افزونه‌ها است:
  • %{sec}: تعداد ثانیه‌ها از مبدا زمان یونیکس (Epoch)
  • %{msec}: تعداد میلی‌ثانیه‌ها از مبدا زمان یونیکس (Epoch)
  • %{usec}: تعداد میکروثانیه‌ها از مبدا زمان یونیکس (Epoch)
  • %{msec_frac}: کسر میلی‌ثانیه
  • %{usec_frac}: کسر میکروثانیه

این افزونه‌ها را نمی‌توان با یکدیگر یا با strftime(3) در یک مشخصه ترکیب کرد. به جای آن از چندین مشخصه %{X}t استفاده کنید.

%T
در حالت کلاینت، زمان صرف‌شده برای پاسخ‌گویی به درخواست، به ثانیه. در حالت بک‌اند، زمان از ارسال درخواست تا دریافت کامل بدنه است. این معادل %{s}T است.
%{X}T
در حالت کلاینت، زمان صرف‌شده برای پاسخ‌گویی به درخواست، در قالبی که توسط X مشخص شده است. در حالت بک‌اند، زمان از ارسال درخواست تا دریافت کامل بدنه است. قالب مشخص‌کننده زمان می‌تواند یکی از موارد زیر باشد: s (همانند %T)، ms یا us (همانند %D).
%U
آدرس URL درخواست بدون رشته پرس‌وجو. در صورت نامشخص بودن، پیش‌فرض '-' است.
%u
کاربر دوردست از طریق احراز هویت (auth).
%{X}x
متغیرهای توسعه‌یافته. متغیرهای پشتیبانی‌شده عبارتند از:
قالب لاگی که در صورت عدم تعیین گزینه‌های -f یا -F استفاده می‌شود. برای افزودن به ابتدا یا انتهای دیگر قالب‌سازها کاربرد دارد.
زمان از شروع پردازش درخواست تا ارسال اولین بایت به کلاینت، به ثانیه. برای حالت بک‌اند: زمان از لحظه ارسال درخواست به بک‌اند تا دریافت کامل سرآیند.
در حالت کلاینت، یکی از رشته‌های 'hit' یا 'miss' بسته به این‌که درخواست منجر به اصابت به حافظه پنهان (cache hit) شده یا خیر. موارد Pipe، pass و synth به عنوان miss در نظر گرفته می‌شوند. در حالت بک‌اند، این فیلد خالی است.
در حالت کلاینت، یکی از رشته‌های 'hit'، 'hitmiss'، 'hitpass'، 'miss'، 'pass'، 'pipe' یا 'synth' که نحوه مدیریت و رسیدگی به درخواست را مشخص می‌کند. در حالت بک‌اند، این فیلد خالی است.
سمت بک‌اند یا کلاینت. یکی از دو مقدار 'b' یا 'c' بسته به این‌که درخواست در کجا ایجاد شده است. در حالت خالص بک‌اند یا کلاینت، این فیلد مقداری ثابت خواهد داشت.
شناسه تراکنش (VXID) در vinyld..TP VCL_Log:key مقدار تنظیم‌شده توسط std.log("key:value") در VCL.
مقدار مدخل VSL برای ترکیب مشخص‌شده از tag-record prefix-field. برچسب (Tag) الزامی است و سایر مؤلفه‌ها اختیاری هستند.

پیشوند رکورد (record prefix) تطابق‌ها را تنها به رکوردهایی محدود می‌کند که این پیشوند را به عنوان بخش اول محتوای رکورد و پس از آن یک دونقطه داشته باشند.

فیلد (field)، در صورت وجود، با رکورد لاگ مانند یک فهرست جداشده با نویسه‌های فاصله برخورد می‌کند و تطابق تنها روی n-امین بخش از رکورد انجام می‌گیرد. شمارش فیلدها از ۱ آغاز شده و تا ۲۵۵ ادامه دارد.

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

  • SIGHUP

    چرخش فایل لاگ (گزینه -w را ببینید) در حالت دیمن، لغو حلقه و خروج منظم هنگام اجرا در پیش‌زمینه.

  • SIGUSR1

    تخلیه (flush) هرگونه تراکنش معلق و باقی‌مانده.

قالب‌بند %r معادل %m http://%{Host}i%U%q %H است. این با رفتار %r در سرور وب Apache HTTP که معادل %m %U%q %H است، تفاوت دارد.

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

به عبارت دیگر، هدرهای درخواست همان‌طور که از کلاینت دریافت شده و همان‌گونه که به بک‌اند فرستاده شده‌اند لاگ می‌شوند؛ در حالی که هدرهای پاسخ همان‌طور که به کلاینت فرستاده شده و همان‌طور که از بک‌اند دریافت شده‌اند ثبت می‌گردند.

علاوه بر این، این قواعد روی مواردی که چندین بار در یک تراکنش ظاهر می‌شوند نیز اعمال می‌شود. برای نمونه، اگر یک هدر چندین بار در یک درخواست کلاینت تکرار شود، در حالت کلاینت اولین مورد و در حالت بک‌اند آخرین مورد ثبت می‌شود.

پیش از نسخه 7.7، قالب‌های %{X}i و %{X}o شامل فیلدهای هدری بودند که از طریق VCL مقداردهی می‌شدند. برای دریافت داده‌ها از تراکنش‌های VCL، در عوض استفاده از %{VCL_Log:key}x را در نظر داشته باشید.

ثبت فیلد دوم از رکورد Begin، مربوط به VXID تراکنش والد:

vinylncsa -F "%{VSL:Begin[2]}x"

ثبت کامل رکورد Timestamp مرتبط با مدت‌زمان پردازش:

vinylncsa -F "%{VSL:Timestamp:Process}x"

ثبت لاگ در قالب JSON، با استفاده از پرچم -j برای اطمینان از اینکه خروجی برای تمامی ورودی‌ها یک JSON معتبر است:

vinylncsa -j -F '{"size": %b, "time": "%t", "ua": "%{User-Agent}i"}'

ثبت اولین و آخرین مقادیر هدر درخواستی که چندین بار در VCL تغییر یافته است:

vinylncsa -F "%{x-custom-header:first}i %{x-custom-header:last}i"

vinyld(1) vinyllog(1) vinylstat(1) vsl-query(7) vsl(7)

ابزار vinylncsa توسط Poul-Henning Kamp با همکاری Verdens Gang AS و Redpill-Linpro توسعه داده شد. این صفحه راهنما در ابتدا توسط Dag-Erling Smørgrav <<des@des.no>> نوشته شد و بعداً توسط Martin Blix Grydeland و Pål Hermunn Johansen به‌روزرسانی گردید.

این سند تحت همان مجوز خود Vinly Cache ارائه شده است. برای جزئیات به LICENCE مراجعه کنید.

  • Copyright (c) 2006 Verdens Gang AS
  • Copyright (c) 2006-2016 Varnish Software AS