Examples — com.github.steffan-westcott/clj-otel-api 0.2.4

Examples

Running the examples

These instructions assume a Unix-like environment, with docker to build container images and spin up instances. All examples use deps.edn for project configuration.

Clone clj-otel repository

To clone this repository, run the following command
```
git clone https://github.com/steffan-westcott/clj-otel.git
```
Get OpenTelemetry instrumentation agent JAR

Before running any of the examples, the file opentelemetry-javaagent.jar must be downloaded and placed in the examples directory. See the releases page for notes and download links.
Select example

The examples use :local/root to depend on clj-otel modules. In your own libraries and applications, use :mvn/version instead, as shown in the guides to add manual instrumentation.

Select an example from the following list and change the current directory to the path shown
- examples/cube-app
  
  A small application run with the OpenTelemetry instrumentation agent on localhost, exporting telemetry to a Collector instance.
- examples/square-app
  
  A small application using autoconfigured OpenTelemetry SDK, run on localhost, exporting telemetry to a Collector instance.
- examples/factorial-app
  
  A small application using programmatically configured OpenTelemetry SDK, run on localhost, exporting telemetry to a Collector instance.
- examples/divisor-app
  
  A small application using autoconfigured OpenTelemetry SDK, run on localhost, exporting telemetry directly to Jaeger and Prometheus instances.
- examples/microservices/auto-instrument/middleware
  
  A pair of dependent microservices sentence-summary-service and word-length-service implemented with Ring middleware, both using the OpenTelemetry instrumentation agent, exporting telemetry to a Collector instance.
- examples/microservices/auto-instrument/interceptor
  
  A pair of dependent microservices solar-system-service and planet-service implemented with Pedestal interceptors, both using the OpenTelemetry instrumentation agent, exporting telemetry to a Collector instance.
- examples/microservices/manual-instrument/middleware
  
  A pair of dependent microservices puzzle-service and random-word-service implemented with Ring middleware, not using the agent, exporting telemetry to a Collector instance.
- examples/microservices/manual-instrument/interceptor
  
  A pair of dependent microservices average-service and sum-service implemented with Pedestal interceptors, not using the agent, exporting telemetry to a Collector instance.
Build example

Some examples must be built before running. These examples have a build.sh file.

To build the chosen example, run the following command
```
./build.sh
```
Start container instances

compose.yaml is a Docker Compose configuration file that specifies container instances to spin up. These containers may include telemetry backends (Jaeger, Prometheus) and the OpenTelemetry Collector. When the Collector is present, otel-collector.yaml is a configuration file that forwards telemetry data to the telemetry backends. The microservice examples include instances for each service and a load generator that automatically exercises the head microservice.
- For all microservices examples, run one of the following commands corresponding to your choice of implementation for the head microservice:
  SERVER=sync docker compose up -d
  SERVER=bound-async docker compose up -d
  SERVER=explicit-async docker compose up -d
- For all other examples, run the following command
  docker compose up -d
Load and exercise example

You may see the following message appear in stdout for the examples using autoconfiguration. It is a known issue in OpenTelemetry Java SDK, but has no impact on the application telemetry data.
```
INFO: AutoConfiguredOpenTelemetrySdk found on classpath but automatic configuration is disabled. To enable, run your JVM with -Dotel.java.global-autoconfigure.enabled=true
```
For the microservices examples, a load generator application is included. The load generator automatically issues randomized valid and invalid requests to the head microservice.

The other examples are designed to be loaded and exercised in the REPL as follows:
- In the chosen example directory and your favourite Clojure development environment, start a REPL with the otel alias enabled
- Load the example namespace and set as current
- Evaluate each expression in the comment block at the end of the namespace

View telemetry data in backends

Traces may appear incomplete until all parts of telemetry data have been received and processed by the telemetry backend. This sometimes impacts recent traces of distributed services, where some but not all contributing services have completed exporting telemetry data.

Jaeger : Navigate to http://localhost:16686/search then select an option in the Service dropdown and click the Find Traces button.
Prometheus : Navigate to http://localhost:9090/graph then enter a metric name in the expression in the search bar, or click the Open metrics explorer button and select a metric.

Stop container instances

To stop and tear down the container instances, run the following command:
```
docker compose down -v
```
Prune example container images

To delete previously built Docker images for the examples, run the following command:
```
docker image prune -a --filter "label=clj-otel.example"
```