This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
commit 15b928ffe1bbcd7681faee8a5677645edec84928
Author: James Netherton <jamesnether...@gmail.com>
AuthorDate: Mon Feb 3 14:04:20 2025 +0000
Tidy observability-services documentation
---
.../extensions/observability-services.adoc | 66 ++++++++++++++--------
.../runtime/src/main/doc/usage.adoc | 66 ++++++++++++++--------
2 files changed, 84 insertions(+), 48 deletions(-)
diff --git
a/docs/modules/ROOT/pages/reference/extensions/observability-services.adoc
b/docs/modules/ROOT/pages/reference/extensions/observability-services.adoc
index 8adcc19466..f77b5daba3 100644
--- a/docs/modules/ROOT/pages/reference/extensions/observability-services.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/observability-services.adoc
@@ -39,35 +39,40 @@ endif::[]
[id="extensions-observability-services-usage"]
== Usage
-This extension is used to provide a set of opinionated components and
configuration which simplify operations such as observability on cloud
environments. Although the component is mainly targeted for cloud, it can be
used in any other environment, giving to the Camel application the capability
to expose a set of observability features by default.
+This extension provides a set of opinionated components and configuration to
simplify operations such as observability on cloud environments.
+Although the extension is mainly targeted for cloud, it can be used in any
other environment.
-All you need to do is to add the dependency to the classpath. There's no need
to add any further configuration. Each individual component will be configured
using each own default settings except the endpoint which will be exposed in
*/observe/<service>* by default.
+By adding the `camel-quarkus-observability-services` extension to your
application, each observability component (described below) will be configured
with their individual default settings.
+No additional configuration is required.
-If you need to customize each of the different components provided within this
service, then, you can specify in the *application.properties* each of the
configuration as it would be done normally when you provide the individual
component.
+HTTP endpoints will be exposed under the context path `/observe/<service>` by
default. Further details about this are described below.
+
+If you need to customize any component provided by this extension, then you
can specify any of their related configuration options in
`application.properties`, as it would be done normally when you work with the
individual component extension(s).
[id="extensions-observability-services-usage-components"]
== Components
-The presence of this dependency will provide the following extensions:
+This extension automatically provides the following Camel Quarkus component
extensions:
-* Camel Quarkus MicroProfile Health - for health checks
-* Camel Quarkus Management - for JMX
-* Camel Quarkus Micrometer - for Camel Micrometer metrics
-* Camel Quarkus OpenTelemetry - for tracing Camel messages (events/spans)
-* Quarkus Micrometer Registry Prometheus - for exporting metrics in Prometheus
format
+* xref:reference/extensions/microprofile-health.adoc[Camel Quarkus
MicroProfile Health] - for health checks
+* xref:reference/extensions/management.adoc[Camel Quarkus Management] - for JMX
+* xref:reference/extensions/micrometer.adoc[Camel Quarkus Micrometer] - for
Camel Micrometer metrics
+* xref:reference/extensions/opentelemetry.adoc[Camel Quarkus OpenTelemetry] -
for tracing Camel messages (events/spans)
+*
https://quarkus.io/guides/telemetry-micrometer#micrometer-and-monitoring-system-extensions[Quarkus
Micrometer Registry Prometheus] - for exporting metrics in Prometheus format
[id="extensions-observability-services-usage-list-of-known-endpoints"]
=== List of known endpoints
-The presence of this dependency will expose the following endpoints:
+The presence of this extension will expose the following endpoints:
|====
|Endpoint | Description
-| `/observe/health` | startup probe endpoint
-| `/observe/health/live` | liveness probe endpoint
-| `/observe/health/ready` | readiness probe endpoint
-| `/observe/metrics` | metrics exposed as in Micrometer Prometheus Registry
+| `/observe/health` | Accumulation of all health check procedures in the
application
+| `/observe/health/live` | Liveness probe endpoint
+| `/observe/health/ready` | Readiness probe endpoint
+| `/observe/health/started` | Application started probe endpoint
+| `/observe/metrics` | Metrics exposed from the Micrometer Prometheus registry
|====
@@ -76,27 +81,40 @@ NOTE: You can configure the endpoints as you'd do normally
within each extension
[id="extensions-observability-services-usage-opentelemetry-configuration"]
== OpenTelemetry configuration
-The presence of this component will provide the required instrumentation to
easily enable the collection of Opentelemetry metrics. The Camel Quarkus
Opentelemetry extension instrument your application with a service which
periodically pushes OTEL traces to the collector. This is disabled by default
in order to prevent the application to push traces when no telemetry server is
available.
+The presence of this extension will provide the required instrumentation to
enable the collection of OpenTelemetry metrics.
+The Camel Quarkus OpenTelemetry extension instruments your application and
periodically attempts to export traces to the configured collector.
+This is disabled by default in order to prevent the application exporting
traces when no telemetry server is available.
-In order to turn it on, you need to specify the following configuration
explicitly:
+In order to enable instrumentation, you need to add the following
configuration to `application.properties`.
-```
+[source,properties]
+----
quarkus.otel.sdk.disabled=false
-```
+----
-Beside that, you can change any further parameter, like, for instance, the
server where to push the traces (default, `http://localhost:4317`)
+To configure any aspect of OpenTelemetry, you can add the following
configuration to `application.properties`. For example to customize the server
endpoint where traces should be exported (default, `http://localhost:4317`).
-```
+[source,properties]
+----
quarkus.otel.exporter.otlp.traces.endpoint=http://my-otel-collector.svc:4317
-```
+----
-NOTE: Quarkus runtime defaults to gRPC protocol (port 4317).
+The full set of configuration options are documented in the
xref:reference/extensions/opentelemetry.adoc[Camel Quarkus OpenTelemetry] and
https://quarkus.io/guides/opentelemetry[Quarkus OpenTelemetry] documentation.
+
+NOTE: Quarkus trace exporting defaults to the gRPC protocol on port 4317.
[id="extensions-observability-services-usage-jmx-configuration"]
== JMX configuration
-The presence of this component implies the presence of `camel-management`
component. This is in charge to include information about Camel application
status in JMX format.
+The presence of this extension implies the presence of the
`camel-quarkus-management` extension.
+This exposes Camel JMX MBeans to provide insights and management of the
running application.
+
+If you prefer to disable Camel JMX instrumentation, you can add the following
configuration to `application.properties`.
-NOTE: The presence of this components automatically enable the collection of
the JMX metrics. This should be negligible from performance point of view,
however, you may want to disable that running the application with
`-Dorg.apache.camel.jmx.disabled=true` JVM option.
+[source,properties]
+----
+camel.main.jmxEnabled=false
+----
+The full set of configuration options are documented in the
xref:reference/extensions/management.adoc[Camel Quarkus Management]
documentation.
diff --git a/extensions/observability-services/runtime/src/main/doc/usage.adoc
b/extensions/observability-services/runtime/src/main/doc/usage.adoc
index 868c7059ad..525140bfec 100644
--- a/extensions/observability-services/runtime/src/main/doc/usage.adoc
+++ b/extensions/observability-services/runtime/src/main/doc/usage.adoc
@@ -1,30 +1,35 @@
-This extension is used to provide a set of opinionated components and
configuration which simplify operations such as observability on cloud
environments. Although the component is mainly targeted for cloud, it can be
used in any other environment, giving to the Camel application the capability
to expose a set of observability features by default.
+This extension provides a set of opinionated components and configuration to
simplify operations such as observability on cloud environments.
+Although the extension is mainly targeted for cloud, it can be used in any
other environment.
-All you need to do is to add the dependency to the classpath. There's no need
to add any further configuration. Each individual component will be configured
using each own default settings except the endpoint which will be exposed in
*/observe/<service>* by default.
+By adding the `camel-quarkus-observability-services` extension to your
application, each observability component (described below) will be configured
with their individual default settings.
+No additional configuration is required.
-If you need to customize each of the different components provided within this
service, then, you can specify in the *application.properties* each of the
configuration as it would be done normally when you provide the individual
component.
+HTTP endpoints will be exposed under the context path `/observe/<service>` by
default. Further details about this are described below.
+
+If you need to customize any component provided by this extension, then you
can specify any of their related configuration options in
`application.properties`, as it would be done normally when you work with the
individual component extension(s).
== Components
-The presence of this dependency will provide the following extensions:
+This extension automatically provides the following Camel Quarkus component
extensions:
-* Camel Quarkus MicroProfile Health - for health checks
-* Camel Quarkus Management - for JMX
-* Camel Quarkus Micrometer - for Camel Micrometer metrics
-* Camel Quarkus OpenTelemetry - for tracing Camel messages (events/spans)
-* Quarkus Micrometer Registry Prometheus - for exporting metrics in Prometheus
format
+* xref:reference/extensions/microprofile-health.adoc[Camel Quarkus
MicroProfile Health] - for health checks
+* xref:reference/extensions/management.adoc[Camel Quarkus Management] - for JMX
+* xref:reference/extensions/micrometer.adoc[Camel Quarkus Micrometer] - for
Camel Micrometer metrics
+* xref:reference/extensions/opentelemetry.adoc[Camel Quarkus OpenTelemetry] -
for tracing Camel messages (events/spans)
+*
https://quarkus.io/guides/telemetry-micrometer#micrometer-and-monitoring-system-extensions[Quarkus
Micrometer Registry Prometheus] - for exporting metrics in Prometheus format
=== List of known endpoints
-The presence of this dependency will expose the following endpoints:
+The presence of this extension will expose the following endpoints:
|====
|Endpoint | Description
-| `/observe/health` | startup probe endpoint
-| `/observe/health/live` | liveness probe endpoint
-| `/observe/health/ready` | readiness probe endpoint
-| `/observe/metrics` | metrics exposed as in Micrometer Prometheus Registry
+| `/observe/health` | Accumulation of all health check procedures in the
application
+| `/observe/health/live` | Liveness probe endpoint
+| `/observe/health/ready` | Readiness probe endpoint
+| `/observe/health/started` | Application started probe endpoint
+| `/observe/metrics` | Metrics exposed from the Micrometer Prometheus registry
|====
@@ -32,25 +37,38 @@ NOTE: You can configure the endpoints as you'd do normally
within each extension
== OpenTelemetry configuration
-The presence of this component will provide the required instrumentation to
easily enable the collection of Opentelemetry metrics. The Camel Quarkus
Opentelemetry extension instrument your application with a service which
periodically pushes OTEL traces to the collector. This is disabled by default
in order to prevent the application to push traces when no telemetry server is
available.
+The presence of this extension will provide the required instrumentation to
enable the collection of OpenTelemetry metrics.
+The Camel Quarkus OpenTelemetry extension instruments your application and
periodically attempts to export traces to the configured collector.
+This is disabled by default in order to prevent the application exporting
traces when no telemetry server is available.
-In order to turn it on, you need to specify the following configuration
explicitly:
+In order to enable instrumentation, you need to add the following
configuration to `application.properties`.
-```
+[source,properties]
+----
quarkus.otel.sdk.disabled=false
-```
+----
-Beside that, you can change any further parameter, like, for instance, the
server where to push the traces (default, `http://localhost:4317`)
+To configure any aspect of OpenTelemetry, you can add the following
configuration to `application.properties`. For example to customize the server
endpoint where traces should be exported (default, `http://localhost:4317`).
-```
+[source,properties]
+----
quarkus.otel.exporter.otlp.traces.endpoint=http://my-otel-collector.svc:4317
-```
+----
+
+The full set of configuration options are documented in the
xref:reference/extensions/opentelemetry.adoc[Camel Quarkus OpenTelemetry] and
https://quarkus.io/guides/opentelemetry[Quarkus OpenTelemetry] documentation.
-NOTE: Quarkus runtime defaults to gRPC protocol (port 4317).
+NOTE: Quarkus trace exporting defaults to the gRPC protocol on port 4317.
== JMX configuration
-The presence of this component implies the presence of `camel-management`
component. This is in charge to include information about Camel application
status in JMX format.
+The presence of this extension implies the presence of the
`camel-quarkus-management` extension.
+This exposes Camel JMX MBeans to provide insights and management of the
running application.
+
+If you prefer to disable Camel JMX instrumentation, you can add the following
configuration to `application.properties`.
-NOTE: The presence of this components automatically enable the collection of
the JMX metrics. This should be negligible from performance point of view,
however, you may want to disable that running the application with
`-Dorg.apache.camel.jmx.disabled=true` JVM option.
+[source,properties]
+----
+camel.main.jmxEnabled=false
+----
+The full set of configuration options are documented in the
xref:reference/extensions/management.adoc[Camel Quarkus Management]
documentation.
