کتابخانه‌ی استاندارد · سیستم و ابزار

گزارش log

ثبت رویدادهای برنامه با سطح اهمیت، پیشوند، فیلدهای ساختاریافته، قالب JSON و نوشتن در پرونده.

واردسازی گزارش

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

برای برنامه‌ای که روی سرور اجرا می‌شود، سرچاپ کافی نیست: باید بدانید هر پیام چقدر مهم است و کی ثبت شده، و بتوانید پیام‌های کم‌اهمیت را خاموش کنید. بسته‌ی گزارش چهار سطح دارد (اشکال‌زدایی، اطلاعات، هشدار، خطا) و فقط پیام‌هایی را ثبت می‌کند که سطحشان از سطح تنظیم‌شده کمتر نباشد؛ سطح پیش‌فرض «اطلاعات» است. هر خط به شکل متن ساده یا یک شیء JSON به خروجی خطا، خروجی استاندارد یا پرونده‌ای چرخشی نوشته می‌شود.

یک خط متنی این شکل را دارد: 2026-10-17 13:09:22 [INFO] shop order 1042 accepted، یعنی زمان محلی، سطح، پیشوند و پیام. نمونه‌های پایین برای ثابت ماندن خروجی، زمان را با نمایش زمان(نادرست) خاموش کرده‌اند.

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

اشتباه‌های رایج:

  • گزارش پرونده‌ای میان‌گیر (بافر) دارد. خط‌ها وقتی به دیسک می‌رسند که میان‌گیر پر شود یا بستن پرونده صدا زده شود؛ پس tail -f عقب می‌ماند و اگر برنامه از کار بیفتد خط‌های آخر از دست می‌روند. در هر مسیر خروج از برنامه بستن پرونده را صدا بزنید.
  • قالب متنی پیام را همان‌طور که هست می‌نویسد. مقداری از کاربر که شکستن خط دارد یک خط گزارش جعلی می‌سازد؛ ولی JSON آن را به شکل \n درون رشته نگه می‌دارد (پایین‌تر را ببینید).
  • تنظیمات متغیرهای سراسری ساده‌اند و قفلی ندارند. فقط هنگام شروع برنامه تغییرشان دهید، نه وقتی نخ‌های دیگر در حال گزارش‌اند.
  • زمان، زمان محلی و بدون اختلاف منطقه‌ی زمانی است، در JSON هم. اگر گزارش چند ماشین را کنار هم می‌گذارید، سرورها را با TZ=UTC اجرا کنید.

سطح را از تنظیمات بخوانید

سطح گزارش نباید در کد ثابت باشد. هنگام توسعه پیام‌های اشکال‌زدایی را می‌خواهید و روی سروری پرکار فقط هشدار و خطا را. سطح را به شکل متن از پرونده‌ی تنظیمات یا محیط بخوانید و با تجزیه سطح به عدد تبدیلش کنید. این تابع debug، info، warn، warning و error را با هر اندازه‌ی حروفی می‌پذیرد و برای هر چیز دیگری «اطلاعات» را برمی‌گرداند؛ پس یک غلط تایپی هیچ‌وقت گزارش را کاملاً خاموش نمی‌کند.

log-level-config.salam
واردسازی گزارش
واردسازی پیکربندی

تابع راه اندازی(متن: رشته):
    ناپایا پ := پیکربندی.تجزیه محیط(متن)
    دیرکن پیکربندی.آزادسازی(پ)
    سطح := گزارش.تجزیه سطح(پیکربندی.دریافت با پیش فرض(پ، "LOG_LEVEL"، "info"))
    گزارش.تنظیم سطح(سطح)
    گزارش.تنظیم پیشوند(پیکربندی.دریافت با پیش فرض(پ، "APP_NAME"، "برنامه"))
    سرچاپ "-- سطح"، گزارش.نام سطح(گزارش.دریافت سطح())
پایان

تابع کار():
    گزارش.اشکال زدایی("جست‌وجوی حافظه‌ی نهان برای کلید user:7")
    گزارش.اطلاعات("سفارش ۱۰۴۲ پذیرفته شد")
    گزارش.هشدار("درگاه پرداخت دیر جواب داد")
    گزارش.خطا("رسید به ایمیل فرستاده نشد")
پایان

تابع ریشه:
    گزارش.به خروجی استاندارد()
    گزارش.نمایش زمان(نادرست)
    راه اندازی("LOG_LEVEL=debug\nAPP_NAME=فروشگاه\n")
    کار()
    راه اندازی("LOG_LEVEL=warning\nAPP_NAME=فروشگاه\n")
    کار()
    راه اندازی("LOG_LEVEL=loud\n")
    کار()
پایان
خروجی-- سطح DEBUG [DEBUG] فروشگاه جست‌وجوی حافظه‌ی نهان برای کلید user:7 [INFO] فروشگاه سفارش ۱۰۴۲ پذیرفته شد [WARN] فروشگاه درگاه پرداخت دیر جواب داد [ERROR] فروشگاه رسید به ایمیل فرستاده نشد -- سطح WARN [WARN] فروشگاه درگاه پرداخت دیر جواب داد [ERROR] فروشگاه رسید به ایمیل فرستاده نشد -- سطح INFO [INFO] برنامه سفارش ۱۰۴۲ پذیرفته شد [WARN] برنامه درگاه پرداخت دیر جواب داد [ERROR] برنامه رسید به ایمیل فرستاده نشد

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

گزارش JSON برای ابزارهای جمع‌آوری

خواندن خط‌های متنی آسان است و جست‌وجو در خط‌های JSON برای ابزارهایی مثل Loki، Elasticsearch یا سرویس‌های گزارش ابری. تنظیم قالب(قالب جیسون) هر خط را یک شیء JSON می‌کند با level، prefix اگر تنظیم شده باشد، msg و یک عضو برای هر کلیدی که به تابع‌های «با فیلد» داده‌اید. اگر نمایش زمان روشن باشد، عضو time با قالب ISO 8601 اول می‌آید.

log-json-requests.salam
واردسازی گزارش
واردسازی رشته

ساختار درخواست:
    همگانی روش: رشته = ""
    همگانی مسیر: رشته = ""
    همگانی وضعیت: صحیح = ۰
    همگانی زمان: صحیح = ۰
پایان

تابع ثبت درخواست(د: درخواست):
    ناپایا کلیدها := وکتور {} برگردان وکتور<رشته>
    ناپایا مقدارها := وکتور {} برگردان وکتور<رشته>
    دیرکن کلیدها.آزادکن()
    دیرکن مقدارها.آزادکن()
    کلیدها.بیفزا("method")
    مقدارها.بیفزا(د.روش)
    کلیدها.بیفزا("path")
    مقدارها.بیفزا(د.مسیر)
    کلیدها.بیفزا("status")
    مقدارها.بیفزا(رشته.از عدد(د.وضعیت برگردان صحیح۶۴))
    کلیدها.بیفزا("ms")
    مقدارها.بیفزا(رشته.از عدد(د.زمان برگردان صحیح۶۴))
    اگر د.وضعیت >= ۵۰۰:
        گزارش.خطا با فیلد("درخواست شکست خورد"، کلیدها، مقدارها)
    وگرنه د.وضعیت >= ۴۰۰:
        گزارش.هشدار با فیلد("درخواست رد شد"، کلیدها، مقدارها)
    وگرنه:
        گزارش.اطلاعات با فیلد("درخواست انجام شد"، کلیدها، مقدارها)
    پایان
پایان

تابع ریشه:
    گزارش.به خروجی استاندارد()
    گزارش.نمایش زمان(نادرست)
    گزارش.تنظیم قالب(گزارش.قالب جیسون)
    گزارش.تنظیم پیشوند("api")
    ثبت درخواست(درخواست { روش = "GET"، مسیر = "/products"، وضعیت = ۲۰۰، زمان = ۱۲ })
    ثبت درخواست(درخواست { روش = "POST"، مسیر = "/login"، وضعیت = ۴۰۱، زمان = ۳ })
    ثبت درخواست(درخواست { روش = "GET"، مسیر = "/report \"q3\""، وضعیت = ۵۰۳، زمان = ۹۵۰ })
پایان
خروجی{"level": "INFO", "prefix": "api", "msg": "درخواست انجام شد", "method": "GET", "path": "/products", "status": "200", "ms": "12"} {"level": "WARN", "prefix": "api", "msg": "درخواست رد شد", "method": "POST", "path": "/login", "status": "401", "ms": "3"} {"level": "ERROR", "prefix": "api", "msg": "درخواست شکست خورد", "method": "GET", "path": "/report \"q3\"", "status": "503", "ms": "950"}

اگر سطح را از نتیجه انتخاب کنید (خطا برای پاسخ‌های 5xx و هشدار برای 4xx)، می‌توانید بدون خواندن همه‌ی درخواست‌ها روی خطاها هشدار بگذارید. گیومه‌های درون مقدار گریز داده می‌شوند تا هر خط JSON معتبری بماند. همه‌ی مقدارها، حتی عددها، به شکل رشته‌ی JSON نوشته می‌شوند.

گزارش در پرونده‌ای که بی‌پایان بزرگ نمی‌شود

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

log-rotation.salam
واردسازی گزارش
واردسازی سیستم عامل
واردسازی ورودی خروجی
واردسازی رشته

تابع خط اول(مسیر: رشته): رشته:
    خط‌ها := ورودی خروجی.خواندن پرونده(مسیر).بشکاف("\n")
    دیرکن خط‌ها.آزادکن()
    برگشت خط‌ها.بگیر(۰)
پایان

تابع ریشه:
    پرونده‌ها := ["worker.log"، "worker.log.1"، "worker.log.2"، "worker.log.3"]
    هر پ در پرونده‌ها:
        سیستم عامل.حذف(پ)
    پایان
    گزارش.نمایش زمان(نادرست)
    اگر گزارش.به پرونده("worker.log") != ۰:
        سرچاپ "worker.log باز نشد"
        برگشت ۱
    پایان
    گزارش.تنظیم چرخش(۱۲۰، ۲)
    تکرار ۲۴ در ش:
        گزارش.اطلاعات("کار شماره‌ی " + رشته.از عدد(ش برگردان صحیح۶۴) + " انجام شد")
    پایان
    گزارش.بستن پرونده()
    هر پ در پرونده‌ها:
        اگر سیستم عامل.وجود دارد(پ):
            سرچاپ پ، "با این خط شروع می‌شود:"، خط اول(پ)
        وگرنه:
            سرچاپ پ، "وجود ندارد"
        پایان
    پایان
پایان
خروجیworker.log با این خط شروع می‌شود: [INFO] کار شماره‌ی 21 انجام شد worker.log.1 با این خط شروع می‌شود: [INFO] کار شماره‌ی 18 انجام شد worker.log.2 با این خط شروع می‌شود: [INFO] کار شماره‌ی 15 انجام شد worker.log.3 وجود ندارد

اندازه‌ی این‌جا خیلی کوچک است تا نمونه چند بار بچرخد. یک سرویس واقعی چیزی مثل ۱۰ * ۱۰۲۴ * ۱۰۲۴ بایت و پنج پشتیبان به کار می‌برد. اندازه پیش از نوشتن هر خط بررسی می‌شود، پس پرونده ممکن است یک خط از حد بلندتر شود. پیش از پایان برنامه بستن پرونده را صدا بزنید، وگرنه خط‌های آخر در میان‌گیر می‌مانند؛ مهلک پیش از خروج با کد ۱ خودش پرونده را می‌بندد.

فیلدهای کلید و مقدار در گزارش متنی

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

log-fields.salam
واردسازی گزارش

تابع خط ورود(کاربر: رشته، تلاش‌ها: صحیح۶۴، موفق: منطقی، عامل: رشته): رشته:
    ناپایا فیلدها := وکتور {} برگردان وکتور<رشته>
    دیرکن فیلدها.آزادکن()
    فیلدها.بیفزا(گزارش.فیلد("user"، کاربر))
    فیلدها.بیفزا(گزارش.فیلد عدد("attempts"، تلاش‌ها))
    فیلدها.بیفزا(گزارش.فیلد منطقی("ok"، موفق))
    فیلدها.بیفزا(گزارش.فیلد("agent"، عامل))
    برگشت گزارش.کلید مقدار("ورود"، فیلدها)
پایان

تابع ریشه:
    گزارش.به خروجی استاندارد()
    گزارش.نمایش زمان(نادرست)
    گزارش.اطلاعات(خط ورود("سارا"، ۱، درست، "curl/8.5"))
    گزارش.هشدار(خط ورود("کاربر مهمان"، ۳، نادرست، "my \"test\" bot"))
    سرچاپ گزارش.فیلد("empty"، "")
    سرچاپ گزارش.فیلد("path"، "/a b")
پایان
خروجی[INFO] ورود user=سارا attempts=1 ok=true agent=curl/8.5 [WARN] ورود user="کاربر مهمان" attempts=3 ok=false agent="my \"test\" bot" empty= path="/a b"

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

پیام‌های قالب‌دار و مقدارهایی که از کاربر می‌آیند

اطلاعات قالبی و دیگر تابع‌های قالبی هر {} را با رشته‌ی بعدی یک وکتور پر می‌کنند که از زنجیره‌ای از + خواناتر است. این تابع‌ها مقدارها را پاک‌سازی نمی‌کنند. این‌جا نام کاربری که شکستن خط دارد در گزارش متنی یک خط [ERROR] جعلی می‌سازد، ولی خط JSON آن را به شکل \n درون یک رشته نگه می‌دارد.

log-untrusted.salam
واردسازی گزارش

تابع جفت(الف: رشته، ب: رشته): وکتور<رشته>:
    ناپایا فهرست := وکتور {} برگردان وکتور<رشته>
    فهرست.بیفزا(الف)
    فهرست.بیفزا(ب)
    برگشت فهرست
پایان

تابع ریشه:
    گزارش.به خروجی استاندارد()
    گزارش.نمایش زمان(نادرست)
    نام := "مینا\n[ERROR] disk full"
    مقدارها := جفت(نام، "10.0.0.7")
    دیرکن مقدارها.آزادکن()
    گزارش.اطلاعات قالبی("کاربر {} از {} وارد شد"، مقدارها)
    کلیدها := جفت("user"، "ip")
    دیرکن کلیدها.آزادکن()
    گزارش.تنظیم قالب(گزارش.قالب جیسون)
    گزارش.اطلاعات با فیلد("کاربر وارد شد"، کلیدها، مقدارها)
    گزارش.تنظیم قالب(گزارش.قالب متن)
    گزارش.تنظیم سطح(گزارش.سطح خطا + ۱)
    گزارش.خطا("این را کسی نمی‌بیند")
    گزارش.تنظیم سطح(گزارش.سطح اطلاعات)
    گزارش.اطلاعات("گزارش دوباره روشن شد")
پایان
خروجی[INFO] کاربر مینا [ERROR] disk full از 10.0.0.7 وارد شد {"level": "INFO", "msg": "کاربر وارد شد", "user": "مینا\n[ERROR] disk full", "ip": "10.0.0.7"} [INFO] گزارش دوباره روشن شد

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

ثبت از چند نخ بدون توقف

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

log-Async.salam
// زبان: فارسی
بسته ریشه

واردسازی گزارش

تابع ریشه:
    گزارش.نمایش زمان(نادرست)
    گزارش.به خروجی استاندارد()
    گزارش.تنظیم پیشوند("async")

    آغازشده := گزارش.شروع ناهمگام(4 برگردان صحیح۶۴)
    گزارش.اطلاعات("one")
    گزارش.اطلاعات("two")
    گزارش.تخلیه()
    گزارش.توقف ناهمگام()

    سرچاپ "started:"، آغازشده
پایان
خروجی[INFO] async one [INFO] async two started: true

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

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

کدام تابع برای کدام کار

می‌خواهیدبه کار ببرید
یک پیام سادهاشکال زدایی، اطلاعات، هشدار، خطا
پیامی که مقدارهایی در آن پر می‌شوداطلاعات قالبی و بقیه‌ی تابع‌های «قالبی»، با جای‌نگهدار {}
فیلدهایی که ابزارها در آن‌ها جست‌وجو کننداطلاعات با فیلد و بقیه‌ی تابع‌های «با فیلد»، بهتر از همه با قالب جیسون
سطح به شکل یک متغیرثبت(سطح، پیام)
توقف برنامه پس از خطایی جبران‌ناپذیرمهلک
خروجی برای کانتینر یا systemdحالت پیش‌فرض، به خطای استاندارد

پایاها و متغیرها

سطح اشکال زدایی LevelDebug

پایا سطح اشکال زدایی: صحیح۳۲ = 0
سطح اشکال‌زدایی؛ جزئیات برای توسعه‌دهنده.
log-Info.salam
واردسازی گزارش

تابع ریشه:
    گزارش.به خروجی استاندارد()
    گزارش.نمایش زمان(نادرست)
    گزارش.تنظیم پیشوند("[برنامه]")
    گزارش.اشکال زدایی("این دیده نمی‌شود")
    گزارش.اطلاعات("سرور آماده است")
    گزارش.هشدار("حافظه رو به پایان است")
    گزارش.خطا("اتصال قطع شد")
    گزارش.تنظیم سطح(گزارش.سطح اشکال زدایی)
    گزارش.اشکال زدایی("حالا دیده می‌شود")
    گزارش.ثبت(گزارش.سطح هشدار، "با سطح دلخواه")
    سرچاپ گزارش.دریافت سطح()، گزارش.نام سطح(گزارش.سطح خطا)، گزارش.تجزیه سطح("warn")، گزارش.سطح اطلاعات
پایان
خروجی[INFO] [برنامه] سرور آماده است [WARN] [برنامه] حافظه رو به پایان است [ERROR] [برنامه] اتصال قطع شد [DEBUG] [برنامه] حالا دیده می‌شود [WARN] [برنامه] با سطح دلخواه 0 ERROR 2 1

سطح اطلاعات LevelInfo

پایا سطح اطلاعات: صحیح۳۲ = 1
سطح اطلاعات؛ رویدادهای عادی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

سطح هشدار LevelWarn

پایا سطح هشدار: صحیح۳۲ = 2
سطح هشدار؛ چیزی غیرعادی ولی نه خطا.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

سطح خطا LevelError

پایا سطح خطا: صحیح۳۲ = 3
سطح خطا.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

قالب متن FormatText

پایا قالب متن: صحیح۳۲ = 0
قالب متنی خوانا.
log-InfoKV.salam
واردسازی گزارش

تابع ریشه:
    گزارش.به خروجی استاندارد()
    گزارش.نمایش زمان(نادرست)
    ناپایا کلیدها := وکتور {} برگردان وکتور<رشته>
    ناپایا مقدارها := وکتور {} برگردان وکتور<رشته>
    دیرکن کلیدها.آزادکن()
    دیرکن مقدارها.آزادکن()
    کلیدها.بیفزا("user")
    مقدارها.بیفزا("sara")
    کلیدها.بیفزا("ms")
    مقدارها.بیفزا("42")
    گزارش.اطلاعات با فیلد("درخواست انجام شد"، کلیدها، مقدارها)
    گزارش.هشدار با فیلد("کند بود"، کلیدها، مقدارها)
    گزارش.خطا با فیلد("شکست خورد"، کلیدها، مقدارها)
    گزارش.تنظیم سطح(گزارش.سطح اشکال زدایی)
    گزارش.اشکال زدایی با فیلد("جزئیات"، کلیدها، مقدارها)
    گزارش.تنظیم قالب(گزارش.قالب جیسون)
    گزارش.اطلاعات("به شکل جیسون")
    سرچاپ گزارش.دریافت قالب() == گزارش.قالب جیسون، گزارش.قالب متن
    ناپایا ف := وکتور {} برگردان وکتور<رشته>
    دیرکن ف.آزادکن()
    ف.بیفزا(گزارش.فیلد("path"، "/login"))
    ف.بیفزا(گزارش.فیلد عدد("status"، ۲۰۰))
    ف.بیفزا(گزارش.فیلد منطقی("cached"، نادرست))
    سرچاپ گزارش.کلید مقدار("پاسخ"، ف)
پایان
خروجی[INFO] درخواست انجام شد user=sara ms=42 [WARN] کند بود user=sara ms=42 [ERROR] شکست خورد user=sara ms=42 [DEBUG] جزئیات user=sara ms=42 {"level": "INFO", "msg": "به شکل جیسون"} true 0 پاسخ path=/login status=200 cached=false

قالب جیسون FormatJSON

پایا قالب جیسون: صحیح۳۲ = 1
قالب JSON، یک شیء در هر خط؛ برای سامانه‌های جمع‌آوری گزارش.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

تابع‌ها

نام سطح LevelName

تابع نام سطح(l: صحیح): رشته
نام انگلیسی سطح با حروف بزرگ: DEBUG، INFO، WARN یا ERROR. هر عدد کمتر از ۰ اشکال‌زدایی و هر عدد بیشتر از ۳ خطا حساب می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

تجزیه سطح ParseLevel

تابع تجزیه سطح(s: رشته): صحیح
متنی مثل "warn" را، بی‌توجه به حروف کوچک و بزرگ و فاصله‌های دو طرف، به سطح تبدیل می‌کند. debug، info، warn، warning و error را می‌شناسد و برای هر چیز دیگر «اطلاعات» می‌دهد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

تنظیم سطح SetLevel

تابع تنظیم سطح(l: صحیح)
پایین‌ترین سطحی که ثبت می‌شود. سطح خطا + ۱ گزارش را خاموش می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

دریافت سطح GetLevel

تابع دریافت سطح(): صحیح
سطح فعلی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

تنظیم پیشوند SetPrefix

تابع تنظیم پیشوند(p: رشته)
پیشوندی که در هر پیام پس از سطح می‌آید، مثل نام برنامه؛ در JSON عضو prefix است. رشته‌ی خالی آن را برمی‌دارد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

نمایش زمان ShowTime

تابع نمایش زمان(b: منطقی)
این‌که هر پیام با زمان محلی، تا ثانیه، شروع شود یا نه. به‌طور پیش‌فرض روشن است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

تنظیم قالب SetFormat

تابع تنظیم قالب(f: صحیح)
قالب متن یا JSON.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

دریافت قالب GetFormat

تابع دریافت قالب(): صحیح
قالب فعلی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

تنظیم چرخش SetRotation

تابع تنظیم چرخش(max_bytes: صحیح۶۴، max_backups: صحیح)
برای گزارش پرونده‌ای: وقتی پرونده به max_bytes رسید، خط بعدی آن را به .1 تغییر نام می‌دهد، نسخه‌های قدیمی‌تر را یک شماره بالا می‌برد و پرونده‌ی تازه‌ای شروع می‌کند؛ حداکثر max_backups نسخه‌ی قدیمی می‌ماند. صفر بایت چرخش را خاموش می‌کند.
log-ToFile.salam
واردسازی گزارش
واردسازی ورودی خروجی

تابع ریشه:
    گزارش.نمایش زمان(نادرست)
    سرچاپ گزارش.به پرونده("app.log")
    گزارش.تنظیم چرخش(۱۰۲۴ * ۱۰۲۴، ۳)
    گزارش.اطلاعات("نوشته شد در پرونده")
    گزارش.بستن پرونده()
    گزارش.به خطای استاندارد()
    چاپ ورودی خروجی.خواندن پرونده("app.log")
پایان
خروجی0 [INFO] نوشته شد در پرونده

به خطای استاندارد ToStderr

تابع به خطای استاندارد()
گزارش در خروجی خطا نوشته شود (پیش‌فرض).

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-ToFile.salam

به خروجی استاندارد ToStdout

تابع به خروجی استاندارد()
گزارش در خروجی استاندارد نوشته شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

به پرونده ToFile

تابع به پرونده(path: رشته): صحیح
گزارش را به انتهای یک پرونده می‌افزاید و صفر برمی‌گرداند، یا منفی یک اگر پرونده باز نشود. نوشتن‌ها تا بستن پرونده در میان‌گیر می‌مانند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-ToFile.salam

بستن پرونده CloseFile

تابع بستن پرونده()
میان‌گیر را خالی و پرونده‌ی گزارش را می‌بندد و گزارش را به خروجی خطا برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-ToFile.salam

شروع ناهمگام StartAsync

تابع شروع ناهمگام(capacity: صحیح۶۴): منطقی
یک نخ نویسنده‌ی پس‌زمینه و یک صف کانالی با ظرفیت داده‌شده راه می‌اندازد؛ از آن پس هر فراخوانی گزارش خطش را در صف می‌گذارد و بدون دست زدن به مقصد برمی‌گردد. صف پر، فراخواننده را منتظر می‌گذارد. اگر حالت ناهمگام از قبل روشن باشد نادرست برمی‌گرداند. صفر یعنی سپردن بی‌بافر.
log-Async.salam
// زبان: فارسی
بسته ریشه

واردسازی گزارش

تابع ریشه:
    گزارش.نمایش زمان(نادرست)
    گزارش.به خروجی استاندارد()
    گزارش.تنظیم پیشوند("async")

    آغازشده := گزارش.شروع ناهمگام(4 برگردان صحیح۶۴)
    گزارش.اطلاعات("one")
    گزارش.اطلاعات("two")
    گزارش.تخلیه()
    گزارش.توقف ناهمگام()

    سرچاپ "started:"، آغازشده
پایان
خروجی[INFO] async one [INFO] async two started: true

توقف ناهمگام StopAsync

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

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Async.salam

تخلیه Flush

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

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Async.salam

ناهمگام است IsAsync

تابع ناهمگام است(): منطقی
آیا حالت ناهمگام روشن است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Async.salam

ثبت Log

تابع ثبت(l: صحیح، msg: رشته)
پیامی با سطح دلخواه ثبت می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

اشکال زدایی Debug

تابع اشکال زدایی(msg: رشته)
پیام اشکال‌زدایی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

اطلاعات Info

تابع اطلاعات(msg: رشته)
پیام اطلاعات.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

هشدار Warn

تابع هشدار(msg: رشته)
پیام هشدار.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

خطا Error

تابع خطا(msg: رشته)
پیام خطا.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Info.salam

اشکال زدایی قالبی Debugf

تابع اشکال زدایی قالبی(tmpl: رشته، args: وکتور<رشته>)
پیام اشکال‌زدایی قالب‌دار: هر {} با رشته‌ی بعدی از args پر می‌شود.
log-Infof.salam
واردسازی گزارش

تابع ریشه:
    گزارش.به خروجی استاندارد()
    گزارش.نمایش زمان(نادرست)
    ناپایا م := وکتور {} برگردان وکتور<رشته>
    دیرکن م.آزادکن()
    م.بیفزا("سارا")
    م.بیفزا("۳")
    گزارش.اطلاعات قالبی("کاربر {} وارد شد و {} پیام دارد"، م)
    گزارش.هشدار قالبی("تلاش ناموفق برای {}"، م)
    گزارش.خطا قالبی("کاربر {} مسدود شد"، م)
    گزارش.تنظیم سطح(گزارش.سطح اشکال زدایی)
    گزارش.اشکال زدایی قالبی("شناسه {}"، م)
پایان
خروجی[INFO] کاربر سارا وارد شد و ۳ پیام دارد [WARN] تلاش ناموفق برای سارا [ERROR] کاربر سارا مسدود شد [DEBUG] شناسه سارا

اطلاعات قالبی Infof

تابع اطلاعات قالبی(tmpl: رشته، args: وکتور<رشته>)
پیام اطلاعات قالبی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Infof.salam

هشدار قالبی Warnf

تابع هشدار قالبی(tmpl: رشته، args: وکتور<رشته>)
پیام هشدار قالبی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Infof.salam

خطا قالبی Errorf

تابع خطا قالبی(tmpl: رشته، args: وکتور<رشته>)
پیام خطای قالبی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-Infof.salam

مهلک Fatal

تابع مهلک(msg: رشته)
پیام خطا را ثبت می‌کند، پرونده‌ی گزارش را می‌بندد و برنامه را با کد ۱ تمام می‌کند، بی آن‌که دیرکنها اجرا شوند. نمونه‌اش این‌جا اجرا نمی‌شود.
log-Fatal.salam
واردسازی گزارش

تابع ریشه:
    گزارش.مهلک("پرونده‌ی پیکربندی پیدا نشد")
پایان

فیلد Field

تابع فیلد(key: رشته، val: رشته): رشته
یک فیلد key=value می‌سازد و مقداری را که فاصله یا نقل‌قول دارد در نقل‌قول می‌گذارد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

فیلد عدد FieldInt

تابع فیلد عدد(key: رشته، val: صحیح۶۴): رشته
یک فیلد با مقدار عددی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

فیلد منطقی FieldBool

تابع فیلد منطقی(key: رشته، val: منطقی): رشته
یک فیلد با مقدار منطقی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

کلید مقدار KV

تابع کلید مقدار(msg: رشته، fields: وکتور<رشته>): رشته
پیام و فیلدهایش را با فاصله به هم می‌چسباند تا به اطلاعات و بقیه داده شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

اشکال زدایی با فیلد DebugKV

تابع اشکال زدایی با فیلد(msg: رشته، keys: وکتور<رشته>، vals: وکتور<رشته>)
پیام اشکال‌زدایی همراه با فیلدهای کلید و مقدار.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

اطلاعات با فیلد InfoKV

تابع اطلاعات با فیلد(msg: رشته، keys: وکتور<رشته>، vals: وکتور<رشته>)
پیام اطلاعاتی با فیلدهایی از دو وکتور هم‌اندازه، کلیدها و مقدارها. در JSON هر جفت یک عضو می‌شود، همیشه به شکل رشته.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

هشدار با فیلد WarnKV

تابع هشدار با فیلد(msg: رشته، keys: وکتور<رشته>، vals: وکتور<رشته>)
پیام هشدار همراه با فیلدها.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam

خطا با فیلد ErrorKV

تابع خطا با فیلد(msg: رشته، keys: وکتور<رشته>، vals: وکتور<رشته>)
پیام خطا همراه با فیلدها.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: log-InfoKV.salam