الإعداد والملفّات الشخصية وActuator

مقدمة إلى Spring Boot Actuator

18 دقيقة الدرس 6 من 13

مقدمة إلى Spring Boot Actuator

لقد بنيت التطبيق — فكيف تعرف أنه يعمل بشكل جيد؟ في بيئة الإنتاج تحتاج إلى إجابات على أسئلة من قبيل: هل اتصال قاعدة البيانات حي؟ كم من الذاكرة العشوائية تستهلك JVM؟ كم طلب HTTP معالج في الخادم؟ يجيب Spring Boot Actuator على كل هذه الأسئلة دون كتابة أي كود مخصص من جانبك. فهو يكشف مجموعة من نقاط نهاية HTTP (وحبوب JMX) تُبرز الحالة التشغيلية لتطبيقك في وقت التشغيل.

ما هو Actuator

Actuator هو وحدة Spring Boot من الدرجة الأولى — تبعية تضيفها مرة واحدة فيظهر لك مجموعة كاملة من نقاط النهاية. تُسمى هذه النقاط عادةً نقاط نهاية الإدارة، وتكشف كل منها شريحة محددة من البيانات التشغيلية: الصحة، والمقاييس، ومتغيرات البيئة، وتفريغات الخيوط (thread dumps)، وحبوب الإعداد، وتتبع HTTP وغير ذلك الكثير. بدلًا من كتابة مسار /healthcheck مخصص يختبر قاعدة البيانات، تحصل على تنفيذ مُختبَر وقابل للتوصيل مجانًا.

العمليات الإنتاجية مقابل تصحيح أخطاء التطوير: صُمّمت نقاط نهاية Actuator لفرق العمليات، وعوامل المراقبة (Prometheus و Datadog و New Relic)، وموازنات التحميل، ومنسّقات الحاويات (تحقق kubernetes liveness/readiness). هي ليست تسهيلًا للمطور في المقام الأول — بل متطلب إنتاجي في أي نشر جاد.

إضافة Actuator إلى المشروع

أضف المبتدئ إلى pom.xml (أو ما يعادله في Gradle):

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

هذا هو التغيير الوحيد المطلوب لتفعيل Actuator. عند بدء تشغيل التطبيق ستظهر سطور في السجل مثل:

Exposing 1 endpoint(s) beneath base path '/actuator'

يُعرض فقط /actuator/health عبر HTTP افتراضيًا. هذا الافتراض المتحفظ مقصود — إذ تُسرّب بعض نقاط النهاية بيانات حساسة ويجب تفعيلها صراحةً.

نقاط النهاية الأساسية في لمحة سريعة

تأتي مع Actuator أكثر من اثنتي عشرة نقطة نهاية مدمجة. أهمها للعمليات اليومية في الإنتاج هي:

/actuator/health — حالة الصحة الإجمالية (UP / DOWN / OUT_OF_SERVICE). يفحص قاعدة البيانات ومساحة القرص وسمسار الرسائل وأي مؤشر مخصص تسجّله. هذا هو العنوان الذي يوجّه إليه Kubernetes تحقق liveness وreadiness.
/actuator/info — بيانات التعريف التعسفية للتطبيق: إصدار البناء وcommit git وخصائص البيئة. يُملأ من application.properties أو application.yml تحت مساحة الاسم info.*.
/actuator/metrics — سجل مقاييس مدعوم بـ Micrometer. يسرد أسماء المقاييس المتاحة؛ تعمّق في /actuator/metrics/{name} للحصول على القيم. يغطي ذاكرة JVM وتوقفات GC وأعداد طلبات HTTP وغيرها.
/actuator/env — الـ Environment المحلول — كل مصدر خاصية (خصائص النظام ومتغيرات البيئة وapplication.yml) وقيمها الفعلية. تُخفى القيم الحساسة افتراضيًا.
/actuator/beans — القائمة الكاملة لحبوب Spring المسجلة في سياق التطبيق وأنواعها وتبعياتها.
/actuator/mappings — كل @RequestMapping مسجّل بما فيه أسلوب المعالج. لا غنى عنه عند تصحيح مفاجآت التوجيه.
/actuator/loggers — عرض وتغيير مستويات السجلات ديناميكيًا في وقت التشغيل دون إعادة تشغيل التطبيق.
/actuator/threaddump — لقطة لجميع خيوط JVM وتتبعات مكدسها الحالية. أول أداة تلجأ إليها عند تشخيص توقف جامد (deadlock) أو خيط جامح.
/actuator/httptrace (أُعيدت تسميته /actuator/httpexchanges في Spring Boot 3) — آخر N من أزواج طلب/استجابة HTTP. يتطلب تسجيل حبة HttpExchangeRepository.
/actuator/shutdown — يوقف التطبيق بأناة عبر طلب POST. معطّل افتراضيًا ويجب أن يظل كذلك على أي خادم يمكن الوصول إليه عبر الإنترنت.

تفعيل نقاط النهاية وكشفها

يميّز Actuator بين كون نقطة النهاية مُفعَّلة (الميزة نشطة) ومكشوفة (قابلة للوصول عبر HTTP أو JMX). يمكن أن تكون نقطة النهاية مُفعَّلة لكن غير مكشوفة. الاستراتيجية الافتراضية متقيدة عن قصد:

جميع نقاط النهاية مُفعَّلة افتراضيًا ما عدا shutdown.
فقط health مكشوف عبر HTTP افتراضيًا.
جميع نقاط النهاية مكشوفة عبر JMX افتراضيًا (إن كان JMX مُفعَّلًا).

لكشف نقاط نهاية إضافية استخدم management.endpoints.web.exposure.include:

# application.properties

# كشف health و info و metrics عبر HTTP
management.endpoints.web.exposure.include=health,info,metrics

# أو كشف كل شيء (شائع في البيئات الداخلية/التطويرية — راجع الأمان قبل الإنتاج)
management.endpoints.web.exposure.include=*

# استثناء shutdown صراحةً حتى عند استخدام حرف البدل
management.endpoints.web.exposure.exclude=shutdown

لا تكشف جميع نقاط النهاية على منفذ عام بدون مصادقة. يمكن لنقاط مثل /actuator/env و/actuator/beans كشف قيم الإعداد ومسارات الفئات والترابطات الداخلية التي يمكن للمهاجم استغلالها. يتناول الدرس 9 في هذا البرنامج التعليمي تأمين Actuator باستخدام Spring Security.

المسار الأساسي ومنفذ إدارة منفصل

يُركّب Actuator افتراضيًا جميع نقاط النهاية تحت /actuator. يمكنك تغيير هذا البادئة:

# الانتقال إلى /ops
management.endpoints.web.base-path=/ops

بالنسبة للخدمات الداخلية من المعتاد خدمة نقاط نهاية الإدارة على منفذ منفصل تمامًا لا يمكن الوصول إليه من الإنترنت العام — فقط من داخل مجموعة Kubernetes أو الـ VPC:

# خدمة نقاط نهاية الإدارة على المنفذ 8081
management.server.port=8081

# ربط الإدارة فقط بـ localhost (ليس بالبطاقة الشبكية العامة)
management.server.address=127.0.0.1

هذا أحد أنظف الأنماط المعمارية لـ Actuator في الإنتاج: يخدم تطبيقك الحركة على المنفذ 8080 (أو 443 خلف وكيل)، وتستدعي بنيتك التحتية للمراقبة المنفذ 8081 المحمي بجدار حماية من العالم الخارجي.

كيف يتكامل Actuator مع بقية المنظومة

لا يعمل Actuator بمعزل — بل صُمّم ليُستهلك:

Kubernetes — هيّئ livenessProbe وreadinessProbe ليستدعيا /actuator/health/liveness و/actuator/health/readiness (يفصلهما Spring Boot 3 تلقائيًا عند النشر في بيئة Kubernetes).
Prometheus / Grafana — أضف micrometer-registry-prometheus ويجمع Prometheus البيانات من /actuator/prometheus بينما يعرض Grafana لوحات التحكم. لا حاجة لأي كود إضافي فوق التبعية.
أدوات تجميع السجلات — يتيح لك /actuator/loggers رفع مستوى السجل إلى DEBUG على عقدة حية لالتقاط عطل معين ثم خفضه — دون إعادة تشغيل.

استخدم نقطة النهاية info لإظهار إصدار البناء. أضف هدف build-info الخاص بـ spring-boot-maven-plugin ومعرف commit git من خط أنابيب CI. عند وقوع حادثة، يخبرك /actuator/info بالضبط أي بناء وأي commit يعمل — لا غنى عنه في أسطول من الحاويات حيث قد تكون علامات الصور غير محددة.

# application.properties — كشف معلومات commit git والبناء في /actuator/info
management.info.git.mode=full
management.info.build.enabled=true

info.app.name=order-service
info.app.team=platform

الخلاصة

يحوّل Spring Boot Actuator تطبيقك إلى خدمة تصف نفسها وقابلة للمراقبة. بتبعية واحدة تحصل على فحوصات صحة، وفحص البيئة، ومقاييس وقت التشغيل، وتغيير مستويات السجلات بشكل حي، وتفريغات الخيوط — كل ما تحتاجه فرقة العمليات لتشغيل خدمة في الإنتاج وتصحيح أعطالها. الانضباط الرئيسي هو معرفة نقاط النهاية التي تكشفها وكيفية حمايتها: افتراضيًا فقط /actuator/health مرئي، ولسبب وجيه. تبني الدروس التالية في هذا البرنامج التعليمي على هذا الأساس — تخصيص مؤشرات الصحة، ونشر مقاييس Micrometer، وتأمين سطح الإدارة باستخدام Spring Security.