
# Observations and the start

Two tools measure an app, as in Spring:

- **`ApplicationStartup`** measures the start: the environment, the context, each bean's creation, and your own steps of the start.
- **`Observation`** measures what runs after the start: a method, a request, any piece of code. `@Observed` does 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:

```dart
// 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 `ApplicationEvent`s 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`).

```dart
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:

```yaml
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 `@PostConstruct` are not observed: they run before the proxy exists. The start is measured by `ApplicationStartup`;
- 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 |

```dart
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](../../spring-boot-starter-flutter/timeline.md).

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

- [AOP](../aop/index.md)
- [The timeline](../../spring-boot-starter-flutter/timeline.md)
- [BeanPostProcessor](../beans/bean-post-processor.md)
