Observability main page

docs/src/main/asciidoc/_includes/observability-include.adoc

@@ -0,0 +1 @@
+This document is part of the xref:observability.adoc[Observability in Quarkus reference guide] which features this and other observability related components.

docs/src/main/asciidoc/centralized-log-management.adoc

@@ -13,6 +13,8 @@ include::_attributes.adoc[]
 This guide explains how you can send your logs to a centralized log management system like Graylog, Logstash (inside the Elastic Stack or ELK - Elasticsearch, Logstash, Kibana) or
 Fluentd (inside EFK - Elasticsearch, Fluentd, Kibana).
 
+include::{includes}/observability-include.adoc[]
+
 There are a lot of different ways to centralize your logs (if you are using Kubernetes, the simplest way is to log to the console and ask your cluster administrator to integrate a central log manager inside your cluster).
 In this guide, we will expose how to send them to an external tool using supported Quarkus extensions in supported standard formats like Graylog Extended Log Format (GELF), Elastic Common Schema (ECS) or the OpenTelemetry Log signal.
 

docs/src/main/asciidoc/jfr.adoc

@@ -15,6 +15,8 @@ This guide explains how https://openjdk.org/jeps/328[Java Flight Recorder] (JFR)
 JFR records various information from the Java standard API and JVM as events.
 By adding the Quarkus JFR extension, you can add custom Quarkus events to JFR. This will help you solve potential problems in your application.
 
+include::{includes}/observability-include.adoc[]
+
 JFR can be preconfigured to dump a file, and when the application exits, JFR will output the file.
 The file will contain the content of the JFR event stream to which Quarkus custom events have also been added.
 You can, of course, get this file at any time you want, even if your application exits unexpectedly.

docs/src/main/asciidoc/logging.adoc

@@ -12,6 +12,8 @@ include::_attributes.adoc[]
 
 Read about the use of logging API in {project-name}, configuring logging output, and using logging adapters to unify the output from other logging APIs.
 
+include::{includes}/observability-include.adoc[]
+
 Quarkus uses the JBoss Log Manager logging backend for publishing application and framework logs.
 Quarkus supports the JBoss Logging API and multiple other logging APIs, seamlessly integrated with JBoss Log Manager.
 You can use any of the <<logging-apis,following APIs>>:

docs/src/main/asciidoc/observability.adoc

@@ -0,0 +1,149 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= Observability in Quarkus
+include::_attributes.adoc[]
+:diataxis-type: reference
+:categories: observability
+:summary: This guide explains how your Quarkus application can utilize OpenTelemetry to provide observability for interactive web applications.
+:topics: observability,opentelemetry, micrometer, jfr, logging, metrics, tracing, monitoring, devservice
+:extensions: io.quarkus:quarkus-opentelemetry,io.quarkus:quarkus-micrometer,io.quarkus:quarkus-jfr
+
+Observability can be defined as the capability to allow a human to ask and answer questions about a system.
+
+Over the time, many extensions have been developed to provide observability capabilities to Quarkus applications. This guide will provide an overview of the observability extensions available in Quarkus and which can be used to provide observability according to the needs of your Quarkus application.
+
+== Telemetry
+
+Telemetry contains data about the internal state of the system and can be split into categories or *signals*:
+
+* *Logging*, classical local or distributed logs
+* *Metrics*, metrics calculated in each Quarkus application instance
+* *Tracing*, distributed tracing across applications
+* *Profiling*, to analize and monitor the application's performance, resource usage, and runtime behavior
+* *Events*, the most generic signal. It's a representation of something significant happening during the execution of a program.
+
+== Guidelines
+
+There is only one important guideline in Quarkus observability:
+
+* The https://opentelemetry.io/docs/specs/otel/protocol/[OpenTelemetry OTLP protocol] is the recommended way to send telemetry out of a Quarkus application. This provides a unified output for the application's telemetry.
+
+== Overview
+
+Some extensions have overlapping functionality and there are recommended extensions for each type of signal.
+
+
+The following table provides an overview of the observability extensions available in Quarkus, the signals they provide and which is the recommended extension for each signal.
+
+|===
+|Extension |Logging |Metrics |Tracing |Profiling |Health Check|Events
+
+|xref:opentelemetry.adoc[quarkus-opentelemetry]
+|O
+|O
+|R
+|
+|
+|X
+
+|xref:telemetry-micrometer.adoc[quarkus-micrometer]
+|
+|R
+|
+|
+|
+|
+
+|xref:telemetry-micrometer-to-opentelemetry.adoc[quarkus-micrometer-opentelemetry]
+|X
+|R
+|R
+|
+|
+|X
+
+|xref:jfr.adoc[quarkus-jfr]
+|
+|
+|
+|R
+|
+|X
+
+|xref:logging.adoc[Logging in Quarkus]
+|X
+|
+|
+|
+|
+|
+
+|xref:logging.adoc#json-logging[quarkus-logging-json]
+|X
+|
+|
+|
+|
+|
+
+
+|xref:centralized-log-management.adoc[quarkus-logging-gelf]
+|D
+|
+|
+|
+|
+|
+|===
+
+- *R* - recommended
+- *X* - supports
+- *D* - deprecated
+- *O* - off by default
+
+== The signals
+
+=== Logging and events
+
+We can say a log line is a type of event that includes a severity classification. The OpenTelemetry project recognizes this approach, resulting in an OpenTelemetry API for logs and events that is pretty much the same.
+
+Log is a much older concept and is still widely used in the industry, that's why the overview table from above has different columns for logs and events.
+
+In the future we'll see a convergence of these two concepts, as people start adopting OpenTelemetry Logs.
+
+==== Quarkus logging extensions
+
+Quarkus uses the *JBoss Log Manager* logging backend to publish application and framework logs either in the console or files. These logs can also be forwarded to a centralized logging system, either by using the legacy xref:centralized-log-management.adoc[`quarkus-logging-gelf`] extension or the recommended xref:opentelemetry.adoc[`quarkus-opentelemetry`] or xref:telemetry-micrometer-to-opentelemetry.adoc[`quarkus-micrometer-opentelemetry`] extensions.
+
+OpenTelemetry logs are disabled by default in the `quarkus-opentelemetry` extension, but enabled by default in the `quarkus-micrometer-opentelemetry` extension.
+
+==== Other events
+
+There is no recommended way to generate observability events in Quarkus because the OpenTelemetry Events API is still under development and its use is not recommended, yet.
+
+The xref:jfr.adoc[`quarkus-jfr`] extension can generate observability related events.
+
+=== Metrics
+
+Quarkus has been using Micrometer to collect metrics from the application for a long time. Almost all the out-of-the-box metrics instrumentation in Quarkus are implemented with Micrometer.
+
+More recently, OpenTelemetry Metrics has become available in the xref:opentelemetry.adoc[`quarkus-opentelemetry`] extension, but it's disabled by default because metrics semantic conventions are not stable yet.
+
+The solution is to use the xref:telemetry-micrometer-to-opentelemetry.adoc[`quarkus-micrometer-opentelemetry`] extension to allow using *Micrometer metrics* and *OpenTelemetry logs and traces* at the same time with a unified output using the OTLP protocol. Manual OpenTelemetry metrics can also be created with this extension and all signals are enabled by default, for convenience.
+
+=== Tracing
+
+Quarkus uses OpenTelemetry Tracing to provide tracing capabilities to the application. The xref:opentelemetry.adoc[`quarkus-opentelemetry`] and the xref:telemetry-micrometer-to-opentelemetry.adoc[`quarkus-micrometer-opentelemetry`] extensions are the recommended way to use for tracing.
+
+=== Profiling
+
+Quarkus uses the Java Flight Recorder (JFR) to provide profiling capabilities to the application. The xref:jfr.adoc[`quarkus-jfr`] extension is the recommended way to generate the events necessary to profile the application.
+
+The OpenTelemetry profiling signal, still under development, might be available in the future.
+
+== See telemetry
+
+The xref:observability-devservices-lgtm.adoc[Grafana LGTM Dev Service] extension is available to visualize the telemetry data for logs, metrics and traces in Grafana.

docs/src/main/asciidoc/opentelemetry-logging.adoc

@@ -16,6 +16,8 @@ distributed logging for interactive web applications.
 
 include::{includes}/extension-status.adoc[]
 
+include::{includes}/observability-include.adoc[]
+
 [NOTE]
 ====
 - OpenTelemetry Logging is considered _tech preview_ and is disabled by default.

docs/src/main/asciidoc/opentelemetry-metrics.adoc

@@ -16,6 +16,8 @@ metrics for interactive web applications.
 
 include::{includes}/extension-status.adoc[]
 
+include::{includes}/observability-include.adoc[]
+
 [NOTE]
 ====
 - OpenTelemetry Metrics is considered _tech preview_ and is disabled by default.

docs/src/main/asciidoc/opentelemetry-tracing.adoc

@@ -13,6 +13,9 @@ include::_attributes.adoc[]
 This guide explains how your Quarkus application can utilize https://opentelemetry.io/[OpenTelemetry] (OTel) to provide
 distributed tracing for interactive web applications.
 
+include::{includes}/observability-include.adoc[]
+
+
 [NOTE]
 ====
 - The xref:opentelemetry.adoc[OpenTelemetry Guide] is available with signal independent information about the OpenTelemetry extension.

docs/src/main/asciidoc/opentelemetry.adoc

@@ -16,6 +16,8 @@ Observability for interactive web applications.
 
 On these page we show the signal independent features of the extension.
 
+include::{includes}/observability-include.adoc[]
+
 [NOTE]
 ====
 - The old OpenTelemetry guide has been split into this generic guide, the xref:opentelemetry-tracing.adoc[OpenTelemetry Tracing Guide], the new xref:opentelemetry-metrics.adoc[OpenTelemetry Metrics Guide] and the xref:opentelemetry-logging.adoc[OpenTelemetry Logging Guide].

docs/src/main/asciidoc/telemetry-micrometer-to-opentelemetry.adoc

@@ -17,6 +17,8 @@ This extension provides support for both Micrometer and OpenTelemetry in Quarkus
 
 include::{includes}/extension-status.adoc[]
 
+include::{includes}/observability-include.adoc[]
+
 [NOTE]
 ====
 - This extension is available since Quarkus version 3.19.

docs/src/main/asciidoc/telemetry-micrometer-tutorial.adoc

@@ -13,6 +13,8 @@ include::_attributes.adoc[]
 
 Create an application that uses the Micrometer metrics library to collect runtime, extension and application metrics and expose them as a Prometheus (OpenMetrics) endpoint.
 
+include::{includes}/observability-include.adoc[]
+
 == Prerequisites
 
 include::{includes}/prerequisites.adoc[]

docs/src/main/asciidoc/telemetry-micrometer.adoc

@@ -17,6 +17,8 @@ include::_attributes.adoc[]
 Micrometer provides an abstraction layer for metrics collection.
 It defines an API for basic meter types, like counters, gauges, timers, and distribution summaries, along with a `MeterRegistry` API that generalizes metrics collection and propagation for different backend monitoring systems.
 
+include::{includes}/observability-include.adoc[]
+
 IMPORTANT: Micrometer is the recommended approach to metrics for Quarkus.
 
 NOTE: By default, the metrics are exposed on the main HTTP server.