| = Observability: A Camel Quarkus example |
| :cq-example-description: An example that demonstrates how to add support for metrics, health checks and distributed tracing |
| |
| {cq-description} |
| |
| 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 |
| ---- |
| |
| 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 checks for verifying whether the `CamelContext` and 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 of `custom-liveness-check` 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/quarkus-app/quarkus-run.jar |
| ... |
| [io.quarkus] (main) camel-quarkus-examples-... started in 1.163s. Listening on: http://0.0.0.0: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) camel-quarkus-examples-... started in 0.013s. Listening on: http://0.0.0.0:8080 |
| ... |
| ---- |
| |
| == Feedback |
| |
| Please report bugs and propose improvements via https://github.com/apache/camel-quarkus/issues[GitHub issues of Camel Quarkus] project. |