Գնահատել նախագիծը
← Բոլոր հրապարակումները

Micrometer-ի նոր observation API-ն Spring Boot 3.0-ում

Այս անգամ կներկայացնենք Spring Boot 3.0-ի հետ եկող ևս մեկ հիանալի հնարավորություն՝ Micrometer 1.10-ում ավելացված նոր observation API-ների աջակցությունը՝ Micrometer Observation API-ն։

6 րոպե
APISpring BootMicrometerMicrometer Observation API

Spring Boot 3-ի հնարավորություններից մեկը GraalVM Native Image Support-ն է։ Այս անգամ կներկայացնենք Spring Boot 3.0-ի հետ եկող ևս մեկ հիանալի հնարավորություն՝ Micrometer 1.10-ում ավելացված նոր observation API-ների աջակցությունը։ Որպեսզի ցույց տանք, թե ինչպես այն օգտագործել ձեր սեփական հավելվածներում, կավելացնենք այն օրինակելի հավելվածին։

Ի՞նչ է observation API-ն Micrometer-ում

Micrometer Observation API-ն micrometer-ի նոր տեսակի API է, որը թույլ է տալիս ցածր մակարդակի API-ները, ինչպիսիք են մետրիկաները, լոգավորումը և tracing-ը, թաքցնել Observation կոչվող նոր հասկացության հետևում։ Նախկինում դուք ձեռնամուխ էիք լինում ինչ-որ բան չափելուն, լոգավորելուն կամ trace անելուն. հիմա դուք պարզապես ուզում եք դիտարկել, որ մեր համակարգում ինչ-որ բան տեղի է ունեցել, և դրա հիման վրա կարող եք կցել մետրիկաներ, լոգեր կամ trace-եր։ Եվ քանի որ դա պարզապես ֆասադ է ցածր մակարդակի API-ի վրա, դուք դեռ կարող եք ձեր մետրիկաներն ու trace-երը ուղարկել մոնիթորինգի կամ tracing համակարգերին, ինչպիսիք են Datadog-ը, Graphite-ը, Prometheus-ը կամ Zipkin-ը։ Աջակցվող համակարգերի ամբողջական ցանկը հասանելի է Spring Boot-ի մետրիկաների փաստաթղթավորման մեջ և Spring Boot-ի tracing-ի փաստաթղթավորման մեջ։

Փաստաթղթավորման առանցքային նախադասությունը հիանալի ամփոփում է այն. Instrument your code a single time and reap many benefits from it։ Այդ բազմաթիվ առավելությունները նշանակում են, որ ավելացրած observation-ի վրա կարող եք կառուցել բազմաթիվ ֆունկցիաներ։ Ավելին, և սա ինձ համար ամենակարևորն է, այս API-ն մեր ուշադրությունը տեղափոխում է այն բանի վրա, թե ինչ ենք ուզում դիտարկել, այլ ոչ թե թե ինչպես։ Մենք այլևս պետք չէ գործ ունենանք ցածր մակարդակի աբստրակցիաների հետ, ինչպիսիք են Timer-ը, Counter-ը կամ Logger-ը, ինչ-որ բան չափելու համար. մենք պարզապես նշում ենք, թե ինչ ենք ուզում դիտարկել։ Ցույց տամ օրինակով։

Ինչպես օգտագործել այս API-ն

Ես կպատենք մեր UserService-ը օրինակելի observation-ով և կբացատրեմ, թե ինչ նկատի ունեմ բազմաթիվ առավելություններ ասելով։

Ստորև բերված է UserService դասի հատված, որը մենք կզարդարենք observation API-ի միջոցով

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);
    }
}

Իսկ սա զարդարված singUp մեթոդն է 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;
}

Քանի որ մենք անում ենք միայն լրացուցիչ վարք ավելացնել, observation-ը ներմուծելու համար կիրառեցինք decorator pattern-ը, որպեսզի մեր բիզնես տրամաբանությունը չխառնվի լրացուցիչ observation աբստրակցիայի հետ։ Նկատեք, որ այս կոդը չի պարունակում Timer, Counter կամ logger.info. այդ ցածր մակարդակի աբստրակցիաները այստեղ պետք չեն։ Վերջապես կարող ենք կենտրոնանալ այն բանի վրա, ինչը կարևոր է։ Մենք ուզում ենք իմանալ, թե ինչ է կատարվում մեր հավելվածում՝ երբ է այն սկսվել (observation.start), երբ է ավարտվել (observation.stop), ընթացքում որևէ սխալ տեղի ունեցե՞լ է (observation.error), թե՞ գործընթացի ընթացքում ինչ-որ նշանակալի բան է պատահել (observation.event) և այլն։ Մենք նկարագրում ենք, թե ինչ ենք ուզում դիտարկել, այլ ոչ թե ինչպես դա իրականացնել։ Բնականաբար, սա նոր API-ի օգտագործման միայն հիմնական օրինակ է։ API-ն ավելին է առաջարկում, և վստահ եմ, որ կգտնեք մի բան, որը կհամապատասխանի ձեր կարիքներին։

Լավ, այժմ մենք կարող ենք կենտրոնանալ մեր մտադրության վրա, ինչը հիանալի է, բայց ինչպե՞ս ստանալ մետրիկաներ, լոգեր կամ trace-եր, երբ մենք արել ենք միայն observation ավելացնելը։ Այստեղ է, որ գործի է անցնում ObservationHandler-ը։ Մնում է միայն ObservationRegistry-ում գրանցել handler-ի կոնկրետ instance։

Ստորև բերված է micrometer գրադարանի ObservationHandler-ի կոդի հատված, որը ցույց է տալիս, թե observation-ի կյանքի ցիկլի որ կետերում կարող ենք լրացուցիչ աշխատանք կատարել։

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 մեզ համար չափվում է։ Մեզ մնում է միայն մետրիկաները արտահանել մեր մետրիկաների պահպանման համակարգ։ Ցույց տամ, թե ինչպես observation-ների մետրիկաները հրապարակել prometheus-ի համար հատուկ endpoint-ում։

Ինչպես կարգավորել մետրիկաները observation-ների համար
Ամենապարզ մոտեցումը 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 endpoint-ում։ Դրա համար մեզ պետք է միայն սահմանել հրապարակվող endpoint-ները մեր application.yaml ֆայլում

management:
  endpoints:
    web:
      exposure:
        include: "health,metrics,**prometheus**"

Այսքանը. spring-boot-ը այժմ ավտոմատ կերպով կստեղծի DefaultMeterObservationHandler bean մեզ համար, և ահա գալիս է Spring-ի կախարդանքը. ObservationHandler տիպի յուրաքանչյուր bean, observation API-ի մի քանի այլ bean-ների հետ միասին, մեզ համար գրանցվում է observation registry-ում առանց լրացուցիչ ջանքի։ Այս handler-ը յուրաքանչյուր observation-ին կցում է Timer.Sample և Counter մետրիկաներ։ Հիանալի չէ՞!!!! Ցույց տամ, թե որ մետրիկաներն են հիմա հայտնվում prometheus-ի մետրիկաների endpoint-ում։

Մետրիկաների endpoint-ի պատասխանի հատված

...
# 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
...

Բավական լավ է, բայց կա ևս մի բան, որ ուզում եմ ձեզ ցույց տալ…

Ինչպես կարգավորել լոգերը observation-ների համար
Կուզե՞ք այս գործընթացին ավելացնել լոգավորում։ Դրա համար արդեն կա պատրաստի handler՝ 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>-ը, թույլ է տալիս handler-ը սահմանափակել ընտրված context-ներով. մենք ավելացրինք պարզ ֆիլտր՝ հիմնված ցածր cardinality-ի tag-երի վրա։ Վերջին արգումենտը փոխակերպիչն է, որը context-ը վերածում է հաղորդագրության՝ Function<Observation.Context, String> converter. մենք պարզապես օգտագործեցինք context-ի անունը որպես հաղորդագրություն։

Ստորև բերված են մեր գործընթացի ստեղծած որոշ լոգեր

...
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 API-ն spring-boot-actuator-ի հետ միասին չափազանց հզոր է։ Այն թույլ է տալիս կենտրոնանալ մտադրության վրա, այլ ոչ թե ցածր մակարդակի իրականացման մանրամասների։ Սա observability-ին մոտենալու թարմ եղանակ է, և ես դրա երկրպագուն եմ։