Observations and the start

Two tools measure an app, as in Spring:

Both send what they measure to whoever listens. Nothing listens by default, so they cost nothing until something does: the debug timeline of the Flutter starter, a log, a handler of your own.

Why

A slow screen or a slow start has a cause you cannot guess. Measuring tells you which bean takes 300 ms to create, which method runs 40 times a second, what the app waits for before it shows. The framework already measures its own steps; the same tools measure yours, and the same viewer shows both.

Your own measurements

Pick the tool by what you measure:

// 1. A method of a bean: an annotation, no code around it.
@Service()
class Catalog {
  @Observed(name: 'catalog.load')
  Future<List<Book>> load() async { /* ... */ }
}

// 2. A piece of code anywhere.
final books = await observations.observe('catalog.load', () => api.books());

// Or start and stop it yourself, with tags.
final observation = observations.start('search.query')
  ..lowCardinalityKeyValue('language', 'ja');
try {
  /* ... */
} finally {
  observation.stop();
}

// 3. Work of the start: a step of the ApplicationStartup.
final step = startup.start('app.cache.warm')..tag('entries', 120);
/* ... */
step.end();

observations is the ObservationRegistry bean, startup the context's ApplicationStartup (a bean can get it from its ConfigurableListableBeanFactory). Your own ApplicationEvents need nothing: the Flutter starter records every event the context publishes.

Observation

Class What it is
ObservationRegistry Makes observations and holds the handlers. ObservationRegistry.noop, or a registry without handlers, makes no-op observations
Observation One measurement: start(), stop(), error(e), tags, a parent. observe(body) runs body in it, a Future too: it stops when the future completes and records its error
ObservationHandler Told when an observation starts, fails and stops; the debug timeline is one
ObservationContext What a handler gets: name, contextual name, tags, start, duration, error, parent

An observation started while another runs is its child, across await too (the current observation is kept in the Zone).

final class SlowCalls extends ObservationHandler {
  @override
  void onStop(ObservationContext context) {
    if (context.duration! > const Duration(milliseconds: 100)) {
      log.warning('${context.contextualName} took ${context.duration}');
    }
  }
}

Declare a handler as a bean and Spring Boot gives it to the observationRegistry bean.

@Observed

@Observed on a method observes each call; on a class, each of its methods (not getters and setters). A method's own annotation wins over its class's.

Parameter Default Meaning
name method.observed The observation's name
contextualName Class#method The name shown
lowCardinalityKeyValues none Tags as key, value, key, value

Every observation is tagged class and method too.

On and off at build time

In Spring Boot, @Observed works only with:

spring:
  observations:
    annotations:
      enabled: true

The property decides the build, not only the run. With it, the module that puts @Observed into effect is in the app, and the generator writes a proxy for each bean that carries @Observed, and for no other bean. Without it, the module is left out, nothing can match @Observed, and the generator writes no proxy at all: the annotation is only metadata and costs nothing. As in Spring Boot (management.observations.annotations.enabled), it is off by default.

How it works

@Observed is AOP. At build time, the generator writes the proxy classes of the beans an advisor may match. At start, the AspectAutoProxyCreator, a bean post-processor, replaces each such bean with its proxy once the bean is initialized. Each call of a marked method then goes through the proxy to the advice, which runs it in an observation.

So, as in Spring:

ObservedAspect is the advice as an @Aspect class; ObservedPointcut and ObservedInterceptor are the same advice for an advisor bean, which is how Spring Boot registers it.

ApplicationStartup

The framework starts a step around each part of the start; BufferingApplicationStartup keeps them.

Step What it measures
spring.boot.application.starting From run until the environment is read
spring.boot.application.environment-prepared Reading the environment
spring.boot.application.context Making and refreshing the context, every bean inside it
spring.beans.instantiate (tag beanName) One bean, from its constructor to the end of its post-processors
final startup = BufferingApplicationStartup();
SpringApplication([appBeans], applicationStartup: startup).run(args);
for (final step in startup.steps) {
  print(step); // spring.beans.instantiate beanName=catalog 12 ms
}

record(name, startedAt:, duration:, tags:) adds a step that already ran: what happened before the startup existed, or an event of no length.

The Flutter starter sets its own ApplicationStartup always: the stages of the splash and the application events are recorded in every app, each bean only with the debug timeline. See The timeline.

In Spring (Java)

Spring Here
io.micrometer.observation.Observation, ObservationRegistry, ObservationHandler The same names, without Micrometer
@Observed, ObservedAspect The same
management.observations.annotations.enabled spring.observations.annotations.enabled, which also decides whether the proxies are generated
org.springframework.core.metrics.ApplicationStartup, BufferingApplicationStartup The same, plus record

See also