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

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.

The examples assume opentelemetry-javaagent.jar version 2.0.0 or later is used.
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 cube-app run with the OpenTelemetry instrumentation agent on localhost, exporting telemetry to a Collector instance.
- examples/square-app
  
  A small application square-app using autoconfigured OpenTelemetry SDK, run on localhost, exporting telemetry to a Collector instance.
- examples/factorial-app
  
  A small application factorial-app using programmatically configured OpenTelemetry SDK, run on localhost, exporting telemetry to a Collector instance.
- examples/divisor-app
  
  A small application divisor-app using autoconfigured OpenTelemetry SDK, run on localhost, exporting telemetry directly to Jaeger and Prometheus instances.
- examples/countries-service
  
  A single HTTP service countries-service run with the OpenTelemetry instrumentation agent on localhost, implemented with Ring middleware, Compojure router, exporting telemetry to a Collector instance.
- examples/microservices/auto-instrument/middleware
  
  A pair of dependent microservices sentence-summary-service and word-length-service both implemented with Ring middleware, Reitit router, run with 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 both implemented with Pedestal interceptors, run with 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 both implemented with Ring middleware, Reitit router, 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 both 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.

The microservices examples may take some time to start, particularly those which use the OpenTelemetry instrumentation agent. When running the docker compose commands below, wait for the command to complete before proceeding to the next step.

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

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 or enter each terminal command 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

After trying out several of the examples, to delete the Docker images run the following command:
```
docker image prune -a --filter "label=example.clj-otel"
```