[[actuator.observability]]
== Observability
Observability is the ability to observe the internal state of a running system from the outside.
It consists of the three pillars logging, metrics and traces.

For metrics and traces, Spring Boot uses https://micrometer.io/docs/observation[Micrometer Observation].
To create your own observations (which will lead to metrics and traces), you can inject an `ObservationRegistry`.

include::code:MyCustomObservation[]

NOTE: Low cardinality tags will be added to metrics and traces, while high cardinality tags will only be added to traces.

Beans of type `ObservationPredicate`, `GlobalObservationConvention`, `ObservationFilter` and `ObservationHandler` will be automatically registered on the `ObservationRegistry`.
You can additionally register any number of `ObservationRegistryCustomizer` beans to further configure the registry.

Observability support relies on the https://github.com/micrometer-metrics/context-propagation[Context Propagation library] for forwarding the current observation across threads and reactive pipelines.
By default, `ThreadLocal` values are not automatically reinstated in reactive operators.
This behavior is controlled with the configprop:spring.reactor.context-propagation[] property, which can be set to `auto` to enable automatic propagation.

For more details about observations please see the https://micrometer.io/docs/observation[Micrometer Observation documentation].

TIP: Observability for JDBC can be configured using a separate project.
The https://github.com/jdbc-observations/datasource-micrometer[Datasource Micrometer project] provides a Spring Boot starter which automatically creates observations when JDBC operations are invoked.
Read more about it https://jdbc-observations.github.io/datasource-micrometer/docs/current/docs/html/[in the reference documentation].

TIP: Observability for R2DBC is built into Spring Boot.
To enable it, add the `io.r2dbc:r2dbc-proxy` dependency to your project.



[[actuator.observability.common-tags]]
=== Common tags
Common tags are generally used for dimensional drill-down on the operating environment, such as host, instance, region, stack, and others.
Common tags are applied to all observations as low cardinality tags and can be configured, as the following example shows:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  observations:
	    key-values:
	      region: "us-east-1"
	      stack: "prod"
----

The preceding example adds `region` and `stack` tags to all observations with a value of `us-east-1` and `prod`, respectively.

[[actuator.observability.preventing-observations]]
=== Preventing Observations

If you'd like to prevent some observations from being reported, you can use the configprop:management.observations.enable[] properties:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	management:
	  observations:
	    enable:
	      denied:
	        prefix: false
	      another:
	        denied:
	          prefix: false
----

The preceding example will prevent all observations with a name starting with `denied.prefix` or `another.denied.prefix`.

TIP: If you want to prevent Spring Security from reporting observations, set the property configprop:management.observations.enable.spring.security[] to `false`.

If you need greater control over the prevention of observations, you can register beans of type `ObservationPredicate`.
Observations are only reported if all the `ObservationPredicate` beans return `true` for that observation.

include::code:MyObservationPredicate[]

The preceding example will prevent all observations whose name contains "denied".



[[actuator.observability.opentelemetry]]
=== OpenTelemetry Support
Spring Boot's actuator module includes basic support for https://opentelemetry.io/[OpenTelemetry].

It provides a bean of type `OpenTelemetry`, and if there are beans of type `SdkTracerProvider`, `ContextPropagators`, `SdkLoggerProvider` or `SdkMeterProvider` in the application context, they automatically get registered.
Additionally, it provides a `Resource` bean.
The attributes of the auto-configured `Resource` can be configured via the configprop:management.opentelemetry.resource-attributes[] configuration property.
If you have defined your own `Resource` bean, this will no longer be the case.

NOTE: Spring Boot does not provide auto-configuration for OpenTelemetry metrics or logging.
OpenTelemetry tracing is only auto-configured when used together with <<actuator#actuator.micrometer-tracing, Micrometer Tracing>>.

The next sections will provide more details about logging, metrics and traces.



[[actuator.observability.annotations]]
=== Micrometer Observation Annotations support
To enable scanning of metrics and tracing annotations like `@Timed`, `@Counted`, `@MeterTag` and `@NewSpan` annotations, you will need to set the configprop:micrometer.observations.annotations.enabled[] property to `true`.
This feature is supported Micrometer directly, please refer to the {micrometer-concepts-docs}#_the_timed_annotation[Micrometer] and {micrometer-tracing-docs}/api.html#_aspect_oriented_programming[Micrometer Tracing] reference docs.
