Observations and the start
Two tools measure an app, as in Spring:
ApplicationStartupmeasures the start: the environment, the context, each bean's creation, and your own steps of the start.Observationmeasures what runs after the start: a method, a request, any piece of code.@Observeddoes it for a method without code around it.
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:
- the constructor, the injection and
@PostConstructare not observed: they run before the proxy exists. The start is measured byApplicationStartup; - a call from inside the bean (
this.load()) is not observed: it does not go through the proxy.
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 |