انتقل إلى المحتوى الرئيسي

الفصل 1: مقدمة إلى Spring Boot Actuator

مقدمة​

Spring Boot Actuator يضيف ميزات المراقبة والإدارة لتطبيقك. يقوم بتوفير نقاط نهاية HTTP التي تسمح بمراقبة حالة الصحة، المقاييس، وتشخيص المشاكل.

🎯 أهداف الفصل​

في نهاية هذا الفصل، ستعرف:

  1. ✅ ما هو Actuator ولماذا تستخدمه
  2. ✅ إضافة Actuator إلى مشروعك
  3. ✅ تكوين نقاط النهاية
  4. ✅ تأمين الوصول إلى نقاط النهاية

1. ما هو Actuator؟​

الميزات الرئيسية​

Spring Boot Actuator يوفر:
├── Health Checks: هل التطبيق يعمل؟
├── مقاييس: الأداء، استخدام الذاكرة، الطلبات/الثانية
├── معلومات: معلومات عن التطبيق (الإصدار، البناء)
├── البيئة: التكوين والمتغيرات البيئية
├── Loggers: تعديل مستويات السجل في الوقت الفعلي
├── Thread Dump: تحليل الخيوط
├── Heap Dump: تحليل الذاكرة
└── HTTP Trace: تاريخ الطلبات

حالات الاستخدام​

1. Kubernetes: فحوصات الحياة/الجاهزية
2. موازن التحميل: التحقق مما إذا كانت الحالة الصحية سليمة
3. Prometheus: جمع المقاييس
4. تصحيح الأخطاء: التشخيص في الإنتاج
5. DevOps: أتمتة النشر

2. التثبيت​

تبعية Maven​

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

Gradle​

implementation 'org.springframework.boot:spring-boot-starter-actuator'

3. التكوين الأساسي​

تفعيل نقاط النهاية​

بشكل افتراضي، يتم عرض /actuator/health فقط عبر HTTP.

# application.properties

# عرض جميع نقاط النهاية عبر HTTP
management.endpoints.web.exposure.include=*

# أو عرض بعض نقاط النهاية فقط
management.endpoints.web.exposure.include=health,info,metrics,prometheus

# استبعاد نقاط النهاية الحساسة
management.endpoints.web.exposure.exclude=env,beans

التحقق من التثبيت​

# بدء التطبيق
mvn spring-boot:run

# سرد جميع نقاط النهاية المتاحة
curl http://localhost:8080/actuator

الاستجابة:

{
  "_links": {
    "self": {"href": "http://localhost:8080/actuator"},
    "health": {"href": "http://localhost:8080/actuator/health"},
    "info": {"href": "http://localhost:8080/actuator/info"},
    "metrics": {"href": "http://localhost:8080/actuator/metrics"},
    "loggers": {"href": "http://localhost:8080/actuator/loggers"}
  }
}

4. المنفذ والمسار المخصص​

فصل منفذ الإدارة​

# منفذ منفصل لـ Actuator (موصى به في الإنتاج)
management.server.port=8081

# التطبيق يبقى على 8080
# Actuator متاح على 8081

المزايا:

  • عزل حركة المرور للمراقبة
  • تكوين جدار ناري مختلف
  • عدم العرض على الإنترنت

تخصيص المسار​

# تغيير المسار الأساسي
management.endpoints.web.base-path=/admin/monitoring

# ستكون نقاط النهاية تحت:
# /admin/monitoring/health
# /admin/monitoring/info
# إلخ.

5. أمان نقاط النهاية​

مع Spring Security​

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                // نقاط النهاية العامة
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/actuator/info").permitAll()
                
                // نقاط النهاية لـ Prometheus (IP داخلي فقط)
                .requestMatchers("/actuator/prometheus").permitAll()
                
                // جميع نقاط النهاية الأخرى لـ Actuator: ADMIN فقط
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                
                // بقية التطبيق
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        
        return http.build();
    }
}

تعطيل نقاط النهاية​

# تعطيل نقطة نهاية بالكامل
management.endpoint.shutdown.enabled=false
management.endpoint.env.enabled=false

# تعطيل الجميع، ثم التفعيل بشكل انتقائي
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
management.endpoint.info.enabled=true
management.endpoint.metrics.enabled=true

6. نقاط النهاية الأساسية​

/actuator/health​

curl http://localhost:8080/actuator/health
{
  "status": "UP"
}

مع التفاصيل:

management.endpoint.health.show-details=always
{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "H2",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 234567891234,
        "threshold": 10485760
      }
    }
  }
}

/actuator/info​

# إضافة معلومات مخصصة
info.app.name=My Application
info.app.version=1.0.0
info.app.description=تطبيق تجريبي
info.contact.email=support@example.com

# معلومات Git (إذا كان spring-boot-maven-plugin مكونًا)
management.info.git.mode=full
curl http://localhost:8080/actuator/info
{
  "app": {
    "name": "My Application",
    "version": "1.0.0",
    "description": "تطبيق تجريبي"
  },
  "contact": {
    "email": "support@example.com"
  }
}

/actuator/metrics​

# سرد جميع المقاييس
curl http://localhost:8080/actuator/metrics

# مقياس محدد
curl http://localhost:8080/actuator/metrics/jvm.memory.used
{
  "name": "jvm.memory.used",
  "measurements": [
    {"statistic": "VALUE", "value": 123456789}
  ],
  "availableTags": [
    {"tag": "area", "values": ["heap", "nonheap"]},
    {"tag": "id", "values": ["G1 Eden Space", "G1 Old Gen"]}
  ]
}

7. التكوين الكامل الموصى به​

# ===== ACTUATOR =====

# عرض نقاط النهاية الضرورية
management.endpoints.web.exposure.include=health,info,metrics,prometheus,loggers

# منفذ منفصل (اختياري ولكن موصى به في الإنتاج)
# management.server.port=8081

# الصحة مع التفاصيل
management.endpoint.health.show-details=when_authorized
management.endpoint.health.show-components=when_authorized

# معلومات مخصصة
info.app.name=@project.name@
info.app.version=@project.version@
info.app.encoding=@project.build.sourceEncoding@
info.java.version=@java.version@

# تفعيل معلومات البناء
management.info.build.enabled=true
management.info.git.enabled=true
management.info.env.enabled=true

# المقاييس
management.metrics.tags.application=${spring.application.name}

8. ملخص​

التثبيت​

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

التكوين الأدنى​

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always

نقاط النهاية الرئيسية​

نقطة النهايةالاستخدام
/actuator/healthحالة الصحة
/actuator/infoمعلومات التطبيق
/actuator/metricsمقاييس الأداء
/actuator/loggersمستويات السجل
/actuator/envالمتغيرات البيئية

🎯 الخطوة التالية​

لنستكشف بالتفصيل جميع نقاط النهاية المتاحة.

➡️ الفصل 2: نقاط النهاية

⬅️ العودة إلى الوحدة 11