شروع سریع: از ثبت‌نام تا اولین لاگ

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

پیش از شروع

همهٔ لاگ‌ها با HTTPS به یک نشانی فرستاده می‌شوند:

• نشانی دریافت لاگ (ingest): https://ingest.logmug.ir
• نشانی داشبورد: https://app.logmug.ir

LogMug سه راه ورود دارد: OpenTelemetry (OTLP/HTTP) برای هر زبانی که کتابخانهٔ OpenTelemetry دارد، پروتکل سازگار با Seq برای برنامه‌هایی که Serilog دارند، و JSON ساده برای اسکریپت‌ها و هر جای دیگر. در این آموزش از راه سوم استفاده می‌کنیم چون از همه سریع‌تر جواب می‌دهد.

گام ۱: ساخت حساب

1. به https://app.logmug.ir بروید و با ایمیل و رمز عبور ثبت‌نام کنید.
2. با هر ثبت‌نام یک سازمان ساخته می‌شود و شما مدیر آن هستید. همهٔ پروژه‌ها و مصرف ماهانه به این سازمان تعلق دارند.
3. حساب تازه روی پلن رایگان است: ۱ گیگابایت در ماه، ۷ روز نگه‌داری و ۱ پروژه. جزئیات را در سهمیه، مدت نگه‌داری و محدودیت‌ها ببینید.

گام ۲: ساخت پروژه و گرفتن کلید

1. در داشبورد گزینهٔ ساخت پروژهٔ جدید را بزنید و یک نام بدهید؛ مثلاً «سامانهٔ فروش». هر پروژه یک سیستم یا محصول است و همهٔ سرویس‌های بک‌اند آن سیستم می‌توانند با همین پروژه لاگ بفرستند.
2. بلافاصله پس از ساخت، یک کلید ingest نشان داده می‌شود که با lm_ingest_ شروع می‌شود. همین حالا آن را در جای امنی ذخیره کنید؛ کلید فقط یک بار نمایش داده می‌شود و LogMug فقط هش آن را نگه می‌دارد.
3. در همان صفحه راهنمای اتصال برای ⁦ASP.NET Core⁩، Serilog، Java، زبان‌های دیگر و HTTP نمایش داده می‌شود که نشانی و کلید واقعی شما در آن پر شده است. می‌توانید کدها را مستقیم کپی کنید.

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

گام ۳: فرستادن اولین لاگ

در یک ترمینال لینوکس یا macOS (یا Git Bash روی ویندوز) این دستور را اجرا کنید و به‌جای lm_ingest_... کلید خودتان را بگذارید:

curl -X POST "https://ingest.logmug.ir/api/ingest/json?service=hello" \
  -H "Authorization: Bearer lm_ingest_..." \
  -H "Content-Type: application/json" \
  -d '[{"level":"info","message":"hello from curl"},{"level":"error","message":"payment failed","order_id":991}]'

اگر همه‌چیز درست باشد، پاسخ با کد ۲۰۲ و بدنه‌ای شبیه این برمی‌گردد:

{"accepted":2,"rejected":0}

در PowerShell ویندوز، curl نام مستعار دستور دیگری است؛ این معادل را به کار ببرید:

Invoke-RestMethod -Method Post `
  -Uri "https://ingest.logmug.ir/api/ingest/json?service=hello" `
  -Headers @{ "x-logmug-key" = "lm_ingest_..." } `
  -ContentType "application/json" `
  -Body '[{"level":"info","message":"hello from PowerShell"}]'

چند نکته دربارهٔ همین درخواست:

• پارامتر service=hello نام سرویس را تعیین می‌کند و بعداً در داشبورد با آن فیلتر می‌کنید.
• فیلد order_id جزو فیلدهای شناخته‌شده نیست، پس به‌عنوان یک ویژگی قابل‌فیلتر ذخیره می‌شود. هر فیلد اضافه‌ای که بفرستید همین رفتار را دارد.
• چون زمان نفرستادیم، زمان دریافت ثبت می‌شود.

گام ۴: دیدن لاگ در داشبورد

1. به صفحهٔ لاگ‌های پروژه در داشبورد بروید. دو خطی که فرستادید باید در بازهٔ پیش‌فرض یک ساعت گذشته دیده شوند.
2. روی سطح error در ستون فیلترها کلیک کنید تا فقط خط خطا بماند.
3. روی خط کلیک کنید تا جزئیات باز شود. کنار ویژگی order_id دکمهٔ «فیلتر» هست که فقط لاگ‌هایی با همین مقدار را نشان می‌دهد.

همهٔ امکانات جستجو در جستجو و فیلتر لاگ‌ها در داشبورد توضیح داده شده است.

گام بعد: اتصال برنامهٔ واقعی

حالا که مسیر کار می‌کند، برنامهٔ خودتان را وصل کنید:

• ⁦ASP.NET Core⁩ و ⁦.NET 8⁩ به بعد: اتصال ⁦ASP.NET Core⁩ با OpenTelemetry
• برنامه‌هایی که Serilog دارند: اتصال برنامه‌هایی که Serilog دارند
• برنامه‌های قدیمی‌تر: اتصال برنامه‌های ⁦.NET Framework 4.x⁩
• Java و Spring Boot: اتصال Java و Spring Boot
• ⁦Node.js⁩، Python، Go و بقیه: زبان‌های دیگر
• مرجع کامل قالب JSON: ارسال لاگ با HTTP و JSON

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

عیب‌یابی

اگر پاسخ ۲۰۲ نگرفتید، کد وضعیت پاسخ معمولاً علت را مستقیم نشان می‌دهد:

اگر پاسخ ۲۰۲ بود ولی لاگی در داشبورد نمی‌بینید، بازهٔ زمانی و فیلترهای فعال را بررسی کنید و مطمئن شوید صفحهٔ همان پروژه‌ای را باز کرده‌اید که کلیدش را به کار بردید.