واجهة Micrometer Observation الجديدة في Spring Boot 3.0
نقدّم هذه المرة ميزة رائعة أخرى تأتي مع Spring Boot 3.0: دعم واجهات المراقبة الجديدة المضافة في Micrometer 1.10 – واجهة Micrometer Observation API.
من ميزات Spring Boot 3 دعم GraalVM Native Image. ونقدّم هذه المرة ميزة رائعة أخرى تأتي مع Spring Boot 3.0: دعم واجهات المراقبة الجديدة المضافة في Micrometer 1.10. ولتوضيح كيفية استخدامها في تطبيقاتك، سنضيفها إلى تطبيق نموذجي.
ما هي واجهة المراقبة (Observation API) في Micrometer؟
واجهة Micrometer Observation API نوع جديد من الواجهات في micrometer يتيح لنا إخفاء واجهات المستوى المنخفض مثل المقاييس (metrics) والتسجيل (logging) والتتبّع (tracing) خلف مفهوم جديد يُسمى Observation. في السابق كنت تنطلق من رغبتك في قياس شيء أو تسجيله أو تتبّعه؛ أما الآن فتريد ببساطة أن تراقب أن شيئًا ما حدث في نظامنا، وعلى هذا الأساس يمكنك إرفاق مقاييس أو سجلات أو تتبّعات. وبما أنها مجرد واجهة تجميلية (facade) فوق الواجهة منخفضة المستوى، فما زال بإمكانك إرسال مقاييسك وتتبّعاتك إلى أنظمة المراقبة أو التتبّع مثل Datadog وGraphite وPrometheus وZipkin. والقائمة الكاملة للأنظمة المدعومة متاحة في توثيق مقاييس Spring Boot وتوثيق التتبّع في Spring Boot.
والجملة الأساسية في التوثيق تلخّص الأمر جيدًا: زوّد الكود بأدوات القياس مرة واحدة واحصد منه فوائد كثيرة. وهذه الفوائد الكثيرة تعني أنه يمكنك بناء ميزات عديدة فوق المراقبة التي أضفتها. والأهم بالنسبة إليّ أن هذه الواجهة تنقل اهتمامنا إلى ما نريد مراقبته بدلًا من كيفية ذلك. فلم نعد مضطرين إلى التعامل مع تجريدات منخفضة المستوى مثل Timer أو Counter أو Logger لقياس شيء ما؛ بل نذكر ببساطة ما نريد مراقبته. دعني أوضح ذلك بمثال.
كيفية استخدام هذه الواجهة
سأغلّف UserService لدينا بمراقبة نموذجية وأشرح المقصود بالفوائد الكثيرة.
فيما يلي جزء من الصنف UserService الذي سنزخرفه (decorate) باستخدام واجهة المراقبة
public class UserApplicationService implements UserService {
private final UserRepository userRepository;
private final PasswordEncoder passwordEncoder;
private final BearerTokenSupplier bearerTokenSupplier;
public UserApplicationService(
UserRepository userRepository, PasswordEncoder passwordEncoder, BearerTokenSupplier bearerTokenSupplier) {
this.userRepository = userRepository;
this.passwordEncoder = passwordEncoder;
this.bearerTokenSupplier = bearerTokenSupplier;
}
@Transactional
@Override
public User signUp(SignUpUserRequest request) {
if (userRepository.existsByEmail(request.email())) {
throw new IllegalArgumentException("Email(`%s`) already exists.".formatted(request.email()));
}
if (userRepository.existsByUsername(request.username())) {
throw new IllegalArgumentException("Username(`%s`) already exists.".formatted(request.username()));
}
User newUser = this.createNewUser(request);
return userRepository.save(newUser);
}
}
وهذه هي الدالة signUp المزخرفة في صنف جديد اسمه ObservedUserService، الذي يغلّف دالتنا signUp داخل Observation
private static final String USER_CONTEXT = "user";
@Override
public User signUp(SignUpUserRequest request) {
Observation observation = Observation.start(USER_CONTEXT + ".signUp", this::createUserContext, observationRegistry);
try (Observation.Scope ignored = observation.openScope()) {
User registeredUser = userService.signUp(request);
observation.event(Observation.Event.of("signedUp", "User signed up"));
return registeredUser;
} catch (Exception ex) {
observation.error(ex);
throw ex;
} finally {
observation.stop();
}
}
private Observation.Context createUserContext() {
Observation.Context context = new Observation.Context();
context.addLowCardinalityKeyValues(KeyValues.of("context", "user"));
return context;
}
وبما أن كل ما نفعله هو إضافة سلوك إضافي، فقد طبّقنا نمط الزخرفة (decorator pattern) لإدخال المراقبة، حتى لا يختلط منطق الأعمال لدينا بتجريد المراقبة الإضافي. لاحظ أن هذا الكود لا يحتوي على Timer أو Counter أو logger.info – فهذه التجريدات منخفضة المستوى غير مطلوبة هنا. أخيرًا، يمكننا التركيز على ما يهم. نريد أن نعرف ما يجري في تطبيقنا: متى بدأ (observation.start)، ومتى انتهى (observation.stop)، وهل وقعت أخطاء في الأثناء (observation.error)، أو هل حدث شيء مهم أثناء العملية (observation.event) وهكذا . نحن نصف ما نريد مراقبته، لا كيفية إنجازه. وبطبيعة الحال هذا مجرد مثال أساسي على استخدام الواجهة الجديدة. فالواجهة تقدم أكثر من ذلك بكثير، وأنا واثق أنك ستجد فيها ما يناسب احتياجاتك.
حسنًا – صار بإمكاننا الآن التركيز على نيّتنا، وهذا رائع، لكن كيف نحصل على المقاييس أو السجلات أو التتبّعات ونحن لم نفعل سوى إضافة مراقبة؟ هنا يأتي دور ObservationHandler. كل ما تبقى هو تسجيل نسخة معالج معيّنة في ObservationRegistry.
فيما يلي جزء من كود ObservationHandler من مكتبة micrometer، يبيّن في أي نقاط من دورة حياة المراقبة يمكننا تنفيذ عمل إضافي.
public interface ObservationHandler<T extends Observation.Context> {
default void onStart(T context) {
}
default void onError(T context) {
}
default void onEvent(Observation.Event event, T context) {
}
default void onStop(T context) {
}
.
.
.
boolean supportsContext(Observation.Context context);
}
تتوفر بالفعل بضعة ObservationHandlers بشكل جاهز. وأحدها DefaultMeterObservationHandler، الذي ينشئ مقاييس Timer وCounter لـ Observation لدينا، فيُقاس كل observation نيابة عنا. وكل ما علينا فعله هو تصدير المقاييس إلى نظام تخزين المقاييس لدينا. دعني أريك كيف نعرض مقاييس المراقبات لـ prometheus عبر نقطة نهاية مخصصة.
كيفية إعداد المقاييس للمراقبات
أبسط طريقة هي استخدام الوحدة spring-boot-starter-actuator. لنضف الوحدات المطلوبة إلى تطبيقنا في build.gradle.kts
implementation("org.springframework.boot:spring-boot-starter-actuator")
implementation(platform("io.micrometer:micrometer-bom:1.11.0"))
implementation("io.micrometer:micrometer-core")
implementation("io.micrometer:micrometer-registry-prometheus")
implementation("io.micrometer:micrometer-observation") // new micrometer module with observation API
كل سطر في هذا الإعداد يتحدث عن نفسه.
جزء إعدادات Spring
بعد ذلك، لنعرض المقاييس بصيغة prometheus على نقطة نهاية HTTP. ولذلك كل ما نحتاجه هو تحديد نقاط النهاية المكشوفة في ملف application.yaml
management:
endpoints:
web:
exposure:
include: "health,metrics,**prometheus**"
هذا كل شيء – سينشئ spring-boot الآن bean من النوع DefaultMeterObservationHandler تلقائيًا، وهنا يأتي سحر spring: فكل bean من النوع ObservationHandler، إلى جانب بعض الأنواع الأخرى من واجهة المراقبات، يُسجَّل في سجل المراقبة نيابة عنا دون أي جهد إضافي. ويُرفق هذا المعالج بالذات مقاييس Timer.Sample وCounter بكل مراقبة. أليس هذا رائعًا!!!! دعني أريك أي المقاييس تظهر الآن في نقطة نهاية مقاييس prometheus.
جزء من استجابة نقطة نهاية المقاييس
...
# HELP user_signUp_seconds_max
# TYPE user_signUp_seconds_max gauge
user_signUp_seconds_max{error="none",} 0.147985042
# HELP user_signUp_seconds
# TYPE user_signUp_seconds summary
user_signUp_seconds_count{error="none",} 2.0
user_signUp_seconds_sum{error="none",} 0.219810917
...
رائع جدًا، لكن هناك شيئًا آخر أودّ أن أريكه…
كيفية إعداد السجلات للمراقبات
هل تودّ إضافة تسجيل (logging) إلى هذه العملية؟ يوجد بالفعل معالج جاهز لذلك – ObservationTextPublisher – وكل ما نحتاجه هو تسجيله كـ spring bean.
@Configuration
public class ObservationLogsConfiguration {
private final Logger logger = LoggerFactory.getLogger(ObservationLogsConfiguration.class);
@Bean
public ObservationTextPublisher observationTextPublisher() {
return new ObservationTextPublisher(
logger::info,
context -> context
.getLowCardinalityKeyValues()
.stream()
.anyMatch(keyValue -> keyValue.getKey().equals("context") && keyValue.getValue().equals("user")),
Observation.Context::getName);
}
}
الوسيط الأول لـ ObservationTextPublisher هو مستهلك الرسائل – هنا logger::info. أما الوسيط الثاني، وهو Predicate<Observation.Context>، فيتيح لك قصر المعالج على سياقات مختارة؛ وقد أضفنا مرشحًا بسيطًا يعتمد على وسوم منخفضة الكاردينالية (low cardinality). والوسيط الأخير هو المحوّل الذي يحوّل السياق إلى رسالة، Function<Observation.Context, String> converter؛ وقد استخدمنا ببساطة اسم السياق كرسالة.
فيما يلي بعض السجلات التي أنتجتها عمليتنا
...
c.s.r.a.c.ObservationLogsConfiguration : STOP - user.signUp
c.s.r.a.c.ObservationLogsConfiguration : START - user.login
c.s.r.a.c.ObservationLogsConfiguration : OPEN - user.login
...
الخلاصة
من الواضح أن واجهة micrometer الجديدة مع spring-boot-actuator قوية للغاية. فهي تتيح لنا التركيز على النيّة بدلًا من تفاصيل التنفيذ منخفضة المستوى. إنها طريقة جديدة في مقاربة قابلية المراقبة (observability)، وأنا من المعجبين بها!