examples/observability/README.adoc

= Camel Quarkus Observability

This example project demonstrates how to add support for metrics, health checks and distributed tracing.

TIP: Check the https://camel.apache.org/camel-quarkus/latest/first-steps.html[Camel Quarkus User guide] for prerequisites
and other general information.

== Start in the Development mode

[source,shell]
----
$ mvn clean compile quarkus:dev -DnoDeps
----

The above command compiles the project, starts the application and lets the Quarkus tooling watch for changes in your
workspace. Any modifications in your project will automatically take effect in the running application.

TIP: Please refer to the Development mode section of
https://camel.apache.org/camel-quarkus/latest/first-steps.html#_development_mode[Camel Quarkus User guide] for more details.


=== Metrics endpoint

Metrics are exposed on an HTTP endpoint at `/metrics`. You can also browse application specific metrics from the `/metrics/application` endpoint.

To view all Camel metrics do:

[source,shell]
----
$ curl localhost:8080/metrics/application
----

To pick out specific metrics you can either use `grep` or the `https://stedolan.github.io/jq/[jq]` library :

[source,shell]
----
$ curl -s -H"Accept: application/json" localhost:8080/metrics/application \
    | jq '.["camel.context.exchanges.completed.total;camelContext=camel-quarkus-observability"]'
----

=== Health endpoint

Camel provides some out of the box liveness and readiness checks. To see this working, interrogate the `/health/live` and `/health/ready` endpoints:

[source,shell]
----
$ curl -s localhost:8080/health/live
----

[source,shell]
----
$ curl -s localhost:8080/health/ready
----

The JSON output will contain a check named 'camel' for verifying whether the `CamelContext` is in the 'Started' state and another check to verify whether each individual route is in the 'Started' state.

This example project contains a custom liveness check class `CustomLivenessCheck` and custom readiness check class `CustomReadinessCheck` which leverage the Camel health API.
You'll see these listed in the health JSON as 'custom-liveness-check' and 'custom-readiness-check'. On every 5th invocation of these checks, the health status will be reported as DOWN.

You can also directly leverage MicroProfile Metrics APIs to create checks. Class `CamelUptimeHealthCheck` demonstrates how to register a readiness check.

==== Tracing

The tracing configuration for the application can be found within `application.properties`.

To view tracing events, start a Jaeger tracing server. A simple way of doing this is with Docker:

[source,shell]
----
$ docker run -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 -p 5775:5775/udp -p 6831:6831/udp -p 6832:6832/udp -p 5778:5778 \
    -p 16686:16686 -p 14268:14268 -p 9411:9411 jaegertracing/all-in-one:latest
----

With the server running, browse to http://localhost:16686. Then choose 'greetings-service' from the 'Service' drop down and click the 'Find Traces' button.

The `netty-http` consumer route introduces a random delay to simulate latency, hence the overall time of each trace should be different. When viewing a trace, you should see
a hierarchy of 3 spans showing the progression of the message exchange through each endpoint.


=== Package and run the application

Once you are done with developing you may want to package and run the application.

TIP: Find more details about the JVM mode and Native mode in the Package and run section of
https://camel.apache.org/camel-quarkus/latest/first-steps.html#_package_and_run_the_application[Camel Quarkus User guide]

==== JVM mode

[source,shell]
----
$ mvn clean package
$ java -jar target/*-runner.jar
...
[io.quarkus] (main) Quarkus 0.23.2 started in 1.163s. Listening on: http://[::]:8080
----

==== Native mode

IMPORTANT: Native mode requires having GraalVM and other tools installed. Please check the Prerequisites section
of https://camel.apache.org/camel-quarkus/latest/first-steps.html#_prerequisites[Camel Quarkus User guide].

To prepare a native executable using GraalVM, run the following command:

[source,shell]
----
$ mvn clean package -Pnative
$ ./target/*-runner
...
[io.quarkus] (main) Quarkus 0.23.2 started in 0.013s. Listening on: http://[::]:8080
...
----