مهاجرت از Splunk به LogMug

در این آموزش

1. اول، واقعیت: LogMug هنوز endpoint سازگار با HEC ندارد
2. گام ۱: نصب OpenTelemetry Collector Contrib
3. گام ۲: فایل پیکربندی
4. گام ۳: اجرا و آزمایش
5. گام ۴: امنیت Collector
6. گام ۵: سطح لاگ (اختیاری)
7. اگر Universal Forwarder فایل می‌خواند
8. دورهٔ گذار و مسیر بلندمدت
9. عیب‌یابی
10. منابع و مطالعهٔ بیشتر

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

اول، واقعیت: LogMug هنوز endpoint سازگار با HEC ندارد

LogMug امروز پروتکل HTTP Event Collector (HEC) اسپلانک را مستقیم نمی‌پذیرد؛ یعنی نمی‌توانید فقط نشانی HEC را در برنامه‌ها به LogMug عوض کنید. این قابلیت در برنامه است، ولی منتظرش نمانید. راه کارکردنی امروز این است که OpenTelemetry Collector را وسط بگذارید: Collector با receiver به نام splunk_hec دقیقاً مثل HEC اسپلانک داده می‌گیرد و با exporter به نام otlphttp آن را با OTLP به LogMug می‌فرستد. برنامه‌ها فقط نشانی HEC را به Collector عوض می‌کنند.

گام ۱: نصب OpenTelemetry Collector Contrib

receiver splunk_hec فقط در توزیع contrib هست، نه در توزیع core. ساده‌ترین راه، ایمیج Docker رسمی است:

docker pull otel/opentelemetry-collector-contrib:latest

برای لینوکس یا ویندوز بدون Docker، بستهٔ otelcol-contrib را از صفحهٔ انتشار رسمی بگیرید. در محیط تولید، نسخه را به‌جای latest ثابت کنید.

گام ۲: فایل پیکربندی

فایل config.yaml را بسازید:

receivers:
  splunk_hec:
    endpoint: 0.0.0.0:8088

processors:
  resource:
    attributes:
      # Splunk's sourcetype becomes the service name in LogMug
      - key: service.name
        from_attribute: com.splunk.sourcetype
        action: insert
      # fallback when an event has no sourcetype
      - key: service.name
        value: legacy-app
        action: insert
  batch:

exporters:
  otlphttp/logmug:
    endpoint: https://ingest.logmug.ir
    headers:
      x-logmug-key: ${env:LOGMUG_KEY}

service:
  pipelines:
    logs:
      receivers: [splunk_hec]
      processors: [resource, batch]
      exporters: [otlphttp/logmug]

توضیح بخش‌ها:

• splunk_hec روی پورت ۸۰۸۸، پورت پیش‌فرض HEC، گوش می‌دهد و رویدادهای JSON و raw را می‌پذیرد. فیلد host رویداد به host.name می‌رود و LogMug آن را ستون میزبان می‌کند؛ source، sourcetype و index به ویژگی‌های com.splunk.source، com.splunk.sourcetype و com.splunk.index تبدیل می‌شوند و fields هر رویداد ویژگی‌های قابل‌فیلتر می‌شوند.
• resource نام سرویس را از sourcetype می‌سازد. اگر در Splunk هر برنامه index جدا داشت، می‌توانید from_attribute را com.splunk.index بگذارید.
• otlphttp/logmug: در endpoint فقط نشانی پایه را بدهید؛ exporter خودش /v1/logs را اضافه می‌کند. پروتکل پیش‌فرض protobuf و فشرده‌سازی پیش‌فرض gzip است و هر دو برای LogMug درست‌اند. کلید از متغیر محیطی LOGMUG_KEY خوانده می‌شود تا در فایل نماند.
• فقط pipeline logs تعریف شده، چون LogMug فقط لاگ می‌پذیرد. اگر از HEC متریک هم می‌فرستید، آن را به مقصد دیگری بدهید.

در نسخه‌های جدید Collector، نام اصلی این exporter otlp_http است و otlphttp نام مستعار قدیمی است که هنوز کار می‌کند ولی هنگام شروع هشدار منسوخ بودن می‌دهد. اگر نسخهٔ شما جدید است، می‌توانید در هر دو جا otlp_http/logmug بنویسید.

گام ۳: اجرا و آزمایش

docker run -d --name otelcol -p 8088:8088 \
  -e LOGMUG_KEY=lm_ingest_... \
  -v "$(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml" \
  otel/opentelemetry-collector-contrib:latest

یک رویداد آزمایشی با همان قالبی که برنامه‌ها به Splunk می‌فرستادند:

curl http://localhost:8088/services/collector/event \
  -H "Authorization: Splunk test-token" \
  -d '{"event":"payment failed","sourcetype":"billing","host":"web-01","fields":{"order_id":"991"}}'

پس از چند ثانیه این لاگ با سرویس billing و میزبان web-01 در داشبورد دیده می‌شود.

گام ۴: امنیت Collector

receiver splunk_hec توکن HEC را بررسی نمی‌کند؛ هر توکنی پذیرفته می‌شود. پس:

1. Collector را فقط در شبکهٔ داخلی در دسترس بگذارید و پورت ۸۰۸۸ را با فایروال به سرورهای برنامه محدود کنید.
2. اگر برنامه‌ها با HTTPS به HEC می‌فرستند، برای receiver گواهی بگذارید:

   receivers:
     splunk_hec:
       endpoint: 0.0.0.0:8088
       tls:
         cert_file: /etc/otelcol-contrib/hec.crt
         key_file: /etc/otelcol-contrib/hec.key

3. مسیر Collector تا LogMug با HTTPS و کلید ingest محافظت می‌شود؛ برای Collector یک کلید جدا با نام روشن بسازید (پروژه‌ها و کلیدها).

گام ۵: سطح لاگ (اختیاری)

رویدادهای HEC فیلد استانداردی برای سطح ندارند، پس همه با سطح info ثبت می‌شوند. اگر سطح را در fields با نامی مثل level می‌فرستید، با processor به نام transform آن را به severity منتقل کنید؛ LogMug متن‌هایی مثل ERROR و Warning را خودکار نگاشت می‌کند:

processors:
  transform:
    log_statements:
      - context: log
        statements:
          - set(severity_text, attributes["level"]) where attributes["level"] != nil

و transform را به فهرست processorهای pipeline اضافه کنید. نحو OTTL بین نسخه‌های Collector کمی تغییر کرده است؛ اگر نسخهٔ شما هشدار داد، مستندات همان نسخه را ببینید.

اگر Universal Forwarder فایل می‌خواند

Universal Forwarder با پروتکل اختصاصی Splunk می‌فرستد، نه HEC، و receiver بالا آن را نمی‌پذیرد. برای این سرورها، Forwarder را با receiver به نام filelog در همان Collector جایگزین کنید که فایل‌های لاگ را مستقیم می‌خواند (include: [/var/log/myapp/*.log]) و آن را هم به pipeline logs اضافه کنید.

دورهٔ گذار و مسیر بلندمدت

• ارسال موازی: در دورهٔ گذار می‌توانید در همان Collector یک exporter splunk_hec هم بگذارید تا داده هم‌زمان به Splunk و LogMug برود و تیم با خیال راحت مقایسه کند.
• جستجوها: LogMug زبان SPL ندارد. جستجوهای پرتکرار را به متن آزاد به‌علاوهٔ فیلتر سطح، سرویس، محیط و ویژگی‌ها برگردانید و لینکشان را ذخیره کنید؛ جستجو در داشبورد را ببینید. هشدار روی الگوی لاگ هنوز در LogMug نیست و در حال ساخت است؛ اگر به هشدارهای Splunk وابسته‌اید، این را در برنامهٔ مهاجرت لحاظ کنید.
• بلندمدت: Collector راه‌حل خوبی برای گذار است، ولی برنامه‌هایی که دستشان به کدشان می‌رسد بهتر است مستقیم وصل شوند تا trace_id، سطح و استثناها دقیق ثبت شوند: ⁦ASP.NET Core⁩، Java یا زبان‌های دیگر.

عیب‌یابی

Collector خطاهای exporter را با کد وضعیت پاسخ در لاگ خودش می‌نویسد: docker logs otelcol.

• Collector بالا نمی‌آید و از splunk_hec نام می‌برد: توزیع core نصب شده است؛ ایمیج یا بستهٔ contrib را به کار ببرید.
• 404 از ingest: در endpoint مسیر /v1/logs را هم نوشته‌اید و دو بار اضافه شده است. فقط https://ingest.logmug.ir بنویسید، یا نشانی کامل را در logs_endpoint بدهید.
• 401: متغیر LOGMUG_KEY به کانتینر نرسیده یا کلید باطل شده است.
• 400: بدنه خوانده نشد؛ encoding و compression را روی پیش‌فرض بگذارید.
• 403: سهمیهٔ ماهانهٔ پلن رایگان تمام شده است. حجم لاگ‌های یک سیستم که از Splunk می‌آید معمولاً از پلن رایگان بیشتر است؛ سهمیه‌ها را ببینید.
• 429 و 503: عبور از نرخ مجاز یا شلوغی موقت؛ Collector با صف و تلاش دوباره خودش مدیریت می‌کند.
• برنامه‌ها خطای اتصال به HEC می‌گیرند: پورت ۸۰۸۸ باز نیست، یا برنامه با HTTPS می‌فرستد و receiver بدون tls است.

منابع و مطالعهٔ بیشتر

• Splunk HEC Receiver — همهٔ تنظیمات receiver و نگاشت فیلدهای HEC.
• OTLP HTTP Exporter — تنظیمات endpoint، هدرها، فشرده‌سازی و تلاش دوباره.
• نصب OpenTelemetry Collector — راهنمای رسمی نصب روی Docker، Kubernetes، لینوکس و ویندوز.