Grafana Alloy على VPS: التثبيت والانتقال من Promtail

لماذا تستبدلون Promtail بـ Alloy الآن

ما الذي يغيّره وكيل واحد على خادمكم

• خدمة واحدة للمراقبة — تمر السجلات والمقاييس عبر العملية نفسها alloy، مع سجل واحد تقرؤونه عند حدوث عطل.
• تحديثات لا تزال تصل — يُنشر Alloy في مستودعات apt وrpm الخاصة بـ Grafana: يكفي apt upgrade لإبقائه محدّثًا مثل باقي النظام.
• انتقال مزوّد بالأدوات — يترجم الأمر alloy convert إعدادات Promtail القائمة وينتج تقريرًا بما لم يتمكن من تحويله.
• مقاييس النظام مدمجة — يحلّ المكوّن prometheus.exporter.unix محلّ node_exporter دون ملف تنفيذي إضافي ولا منفذ يجب فتحه.
• واجهة تصحيح محلية — تعرض الواجهة على المنفذ 12345 مخطط المكوّنات وقيمها، ويمكن الوصول إليها عبر نفق SSH.
• إرسال نحو منظومتكم أو نحو Grafana Cloud — الملف نفسه يرسل إلى Loki مستضاف ذاتيًا أو إلى خدمة مُدارة بتغيير عنوان URL واحد.

متطلبات Alloy على VPS بالأرقام

تثبيت Alloy وربط السجلات والمقاييس

1. 01

   إضافة مستودع Grafana على Debian أو Ubuntu

   sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update && sudo apt-get install alloy

2. 02

   أو تثبيته على AlmaLinux وRocky Linux

   استوردوا المفتاح بالأمر wget -q -O gpg.key https://rpm.grafana.com/gpg.key ثم sudo rpm --import gpg.key. أنشئوا /etc/yum.repos.d/grafana.repo مع baseurl=https://rpm.grafana.com وrepo_gpgcheck=1 وgpgcheck=1 وenabled=1 كما تبيّن صفحة تثبيت Alloy على Linux، ثم نفّذوا sudo dnf install alloy.

3. 03

   تشغيل الخدمة والتحقق من مستخدمها

   sudo systemctl enable --now alloy
sudo systemctl status alloy
systemctl cat alloy | grep User

   يجب أن يعرض الأمر الأخير User=alloy. لا تحدّد الحزمة أي Group=: لذا تأتي صلاحيات القراءة من المجموعات الثانوية لهذا المستخدم، وهي نقطة أساسية لما يلي.

4. 04

   تحديد وجهة السجلات

   افتحوا /etc/alloy/config.alloy وأضيفوا وجهة الإرسال نحو Loki:

   loki.write "default" {
endpoint {
url = "http://127.0.0.1:3100/loki/api/v1/push"
}
}

   استبدلوا العنوان بعنوان Loki لديكم. وإن كان بعيدًا، فاستعملوا HTTPS وكتلة basic_auth.

5. 05

   جمع journald وملفات السجلات

   loki.source.journal "system" {
forward_to = [loki.write.default.receiver]
labels = {"job" = "systemd-journal"}
}
local.file_match "nginx" {
path_targets = [{"__path__" = "/var/log/nginx/*.log", "job" = "nginx"}]
}
loki.source.file "nginx" {
targets = local.file_match.nginx.targets
forward_to = [loki.write.default.receiver]
}

   افتراضيًا، يقرأ مصدر journal المسارين /var/log/journal و/run/log/journal، ولا يعود إلا سبع ساعات إلى الوراء عند أول تشغيل.

6. 06

   جمع مقاييس النظام

   prometheus.exporter.unix "node" { }
prometheus.scrape "node" {
targets = prometheus.exporter.unix.node.targets
forward_to = [prometheus.remote_write.default.receiver]
}
prometheus.remote_write "default" {
endpoint {
url = "http://127.0.0.1:9090/api/v1/write"
}
}

   إن كان node_exporter يعمل مسبقًا على الجهاز، فأوقفوه بعد الانتقال كي لا تُجمع السلاسل نفسها مرتين.

7. 07

   التحقق قبل إعادة التحميل

   sudo alloy validate /etc/alloy/config.alloy
sudo systemctl reload alloy
sudo journalctl -u alloy -f

   يكشف validate خطأ الصياغة أو المكوّن المُشار إليه خطأً قبل أن تحمّل الخدمة الإعدادات.

8. 08

   منح صلاحيات القراءة

   يجب أن يعرض id alloy المجموعتين adm وsystemd-journal. تضيفهما الحزمة عند وجودهما؛ وبعد تثبيت من ملف تنفيذي أو حذف مجموعة، أعيدوهما بالأمر sudo usermod -aG adm,systemd-journal alloy ثم sudo systemctl restart alloy. ولمجلد تطبيق يملكه مستخدم آخر، تفضّل الوثائق قائمة ACL على إضافة مجموعة: sudo setfacl -R -m u:alloy:rx /var/log/monapp وsudo setfacl -R -d -m u:alloy:rx /var/log/monapp.

9. 09

   التحقق من البداية إلى النهاية ثم ربط لوحات المتابعة

   اكتبوا سطرًا شاهدًا بالأمر logger -t alloy-test "ligne de test alloy"، ثم ابحثوا عنه في Grafana، تبويب Explore، بالاستعلام {job="systemd-journal"} |= "ligne de test alloy". أما المقاييس، فيجب أن يعيد الاستعلام node_load1 سلسلة لخادمكم. إن استجاب الاثنان، فأعيدوا استخدام لوحات دليلنا عن Grafana وPrometheus التي تقرأ السلاسل نفسها node_*.

Alloy وDocker: قراءة الحاويات دون فتح كل شيء

الانتقال من Promtail: الخطر الحقيقي في المواضع

نقل إعدادات Promtail دون فقدان ولا تكرار

1. 10

   تحديد ملف الإعدادات وملف المواضع

   افتحوا إعدادات Promtail، وغالبًا ما تكون /etc/promtail/config.yml، وسجّلوا قيمة positions.filename. في تثبيت عبر Docker Compose، يقع هذا الملف داخل وحدة تخزين: سجّلوا مساره الحقيقي على المضيف.

2. 11

   التحويل مع تقرير

   alloy convert --source-format=promtail --report=/tmp/promtail-report.txt --output=/tmp/promtail.alloy /etc/promtail/config.yml

   اقرؤوا التقرير قبل أي شيء. يفرض الخيار --bypass-errors تحويلًا جزئيًا، لكن الوثائق تحذّر من أن السلوك قد يختلف حينها عن الأصل.

3. 12

   التحقق من أن المستخدم alloy يقرأ الملف القديم

   grep legacy_positions_file /tmp/promtail.alloy
sudo -u alloy cat /var/lib/promtail/positions.yaml

   عدّلوا المسار وفق ما سجّلتموه سابقًا. إن فشل الأمر الثاني، فانسخوا الملف إلى مجلد يقرؤه alloy وصحّحوا المسار في الإعدادات المحوّلة.

4. 13

   إيقاف Promtail قبل تشغيل Alloy

   sudo systemctl stop promtail، أو docker compose stop promtail لمنظومة حاويات. يكتب Promtail حينها آخر مواضعه، ولا يُرسل أي سطر مرتين أثناء الانتقال.

5. 14

   تبديل الإعدادات

   انقلوا الكتل المحوّلة إلى /etc/alloy/config.alloy، ونفّذوا sudo alloy validate /etc/alloy/config.alloy ثم sudo systemctl restart alloy. تحققوا فورًا من sudo journalctl -u alloy | grep -i positions: يجب ألا يظهر أي سطر error reading legacy positions file.

6. 15

   المراقبة أسبوعًا ثم الإزالة

   قارنوا حجم السجلات في Grafana قبل الانتقال وبعده، وتابعوا العدّاد loki_write_sent_entries_total في Alloy. احتفظوا بإعدادات Promtail بضعة أيام، ثم sudo systemctl disable promtail وأزيلوا الحزمة أو خدمة Compose.

Promtail وAlloy جنبًا إلى جنب

مرّر الجدول أفقيًا

الإعداد بعد التثبيت: الواجهة والأسرار والتخزين

استكشاف الأعطال: الأخطاء التي لا يصرخ بها Alloy

رسائل الخطأ وحلولها

• مصدر journal يبدأ، لكن لا يصل أي سطر — تقول وثائق loki.source.journal ذلك صراحة: دون المجموعتين adm وsystemd-journal، يبدأ المكوّن دون خطأ ولا يجمع شيئًا. صحّحوا ذلك بالأمر sudo usermod -aG adm,systemd-journal alloy، ثم أعيدوا تشغيل الخدمة، لأن المجموعة المضافة لا تسري إلا عند التشغيل التالي.
• failed to tail the file: open /var/log/…: permission denied — الملف موجود لكن alloy لا يستطيع قراءته. امنحوا قائمة ACL على المجلد بالأمر setfacl -R -m u:alloy:rx وبصيغته -d للملفات التي يُنشئها التدوير لاحقًا.
• لا رسالة ولا سطر لمجلد كامل — يصف البلاغ grafana/alloy #6542 سجلات لم تُرسل قط دون أي خطأ. ويؤكد فيه أحد المشرفين أن الملف غير المقروء يُسجَّل، أما المجلد الذي يتعذّر الوصول إليه فلا. اختبروا ذلك بالأمر sudo -u alloy ls /var/log/monapp.
• error reading legacy positions file … permission denied — لم يقرأ Alloy مواضع Promtail وقد يعيد إرسال كل شيء من البداية (البلاغ #5493). أوقفوا الخدمة، واجعلوا الملف مقروءًا لـ alloy، ثم أعيدوا التشغيل.
• failed to identify the read-write layer ID … mount-id: permission denied — خطأ من المكوّن cAdvisor تحت systemd (البلاغ #4068). المجموعة docker لا تكفي؛ ويذكر مستخدمون أن ملف drop-in يتضمن AmbientCapabilities=CAP_DAC_READ_SEARCH وCapabilityBoundingSet=CAP_DAC_READ_SEARCH يحلّ المشكلة دون تشغيل الخدمة بصلاحيات root. إنه حلّ مجتمعي، اختبروه قبل تعميمه.
• الواجهة خضراء لكن Grafana يبقى فارغًا — تحققوا من loki_write_sent_entries_total ومن سطر الاختبار الذي كتبه logger. إن توقف العدّاد، فالعطل في مرحلة سابقة، عند المصدر.

وكيل محدَّث على خادم تملكونه