Liking cljdoc? Tell your friends :D

`clj-otel`

License

clj-otel provides a small idiomatic Clojure API for adding telemetry to your libraries and applications using OpenTelemetry, an emerging standard for telemetry in cloud-native software, enabling effective observability.

Figure 1. A distributed trace displayed in Honeycomb

Microservice dependencies displayed in Lightstep

Figure 2. Exploring microservice dependencies with Lightstep

Requirements

clj-otel is tested with Clojure 1.11.1 and is based on the reference OpenTelemetry for Java implementation which supports Java 8 and higher.

Quickstart

clj-otel may be used in many ways and is highly configurable. This quickstart is a brief outline for getting started in a local environment. More in-depth information on clj-otel can be found in the documentation and examples.

To add manual instrumentation to your library or application at design time

Add project dependency

deps.edn

{;; ...
 :deps {com.github.steffan-westcott/clj-otel-api {:mvn/version "0.1.1"}}}

Use Clojure functions such as steffan-westcott.clj-otel.api.trace.span/with-span! to create spans with attributes

(defn validate-profile [profile]
  (span/with-span! {:name       "Validating profile"
                    :attributes {:system/profile-id (:id profile)}}
    (validate profile)))

To export telemetry data (from both manual and automatic instrumentation) from an application at runtime
- Download the latest OpenTelemetry instrumentation JAR opentelemetry-javaagent.jar from the OpenTelemetry instrumentation agent releases page.
- Add the following JVM options to your application, assuming export to Jaeger:
  "-javaagent:opentelemetry-javaagent.jar" "-Dotel.resource.attributes=service.name=NAME-OF-YOUR-SERVICE" "-Dotel.traces.exporter=jaeger" "-Dotel.metrics.exporter=none"
To receive exported telemetry data
- Prepare a telemetry backend such as Jaeger
  docker run --rm -p 16686:16686 -p 14250:14250 jaegertracing/all-in-one
To explore application behaviour described by the received telemetry data
- Use telemetry backend features such as the Jaeger user interface at http://localhost:16686/search

Documentation

Tutorial : A walk-through of instrumenting a small Clojure program and viewing its telemetry.
Guides : Common task recipes for adding telemetry to your Clojure libraries and applications, then configuring and running applications with telemetry.
API & Reference : API documentation for all clj-otel modules.
Concepts : A primer on observability, OpenTelemetry and what this project clj-otel enables for Clojure libraries and applications.

Examples

Complete example applications can be found in the examples directory. The examples aim to show:

Adding automatic and manual instrumentation to applications
Configuring and running applications that export telemetry data
Viewing telemetry data in backends

See more information on configuring and running the examples.

Project status

clj-otel is a young, alpha grade project that has yet to be exercised in a production setting. Breaking API changes may still be made, but it is sincerely hoped there will be few, if any.
For manual instrumentation:
- Coverage of the Traces API is complete.
- Trace semantics conventions support for recording exceptions is complete. Support for HTTP spans is partial as it is limited by HTTP client/server abstractions and will never be as complete as that provided by automatic instrumentation.
- Support for wrapping asynchronous Clojure code in spans is complete. The API is minimal and low-level, supporting any async library that works with callbacks. Perhaps with community feedback this will be expanded to add more specialised support for popular async libraries. Code for creating spans around core.async channels can be found in the examples, specifically the <with-span-binding macro.
- There is presently no coverage of the Metrics or Logs API, work on these will commence in the near future.
Coverage of programmatic configuration of the OpenTelemetry SDK is complete.

TODO

For manual instrumentation:
- Add Metrics and Logs API support.
- Consider supporting more trace semantics conventions.
Maintain parity with the latest version of opentelemetry-java.
Implement integration tests, using clj-test-containers or similar.
Consider ClojureScript OpenTelemetry support in the browser and node.js using opentelemetry-js. It is likely this will be a separate project.

Changelog

See changelog

Contributing & contact

The most needed type of contribution is experience reports of using clj-otel in real systems. I am keen to hear of places where clj-otel is used and of any problems and successes. This is a very young project, so now is a good time to provide feedback on the API design as improvements can be made freely.

I will be happy to consider pull requests for minor changes, but larger or structural changes may not be accepted while I make a start on some items in the TODO list.

For questions or feedback on clj-otel, I can be contacted on #clj-otel channel on Clojurians Slack, user steffan.

Enable the :dev alias in any REPL session to ensure dependencies on clj-otel-* modules use :local/root versions. This enables development of the modules and their dependents without the need to install the modules for each change to take effect.
Use the following command to get information on available build scripts:
```
clojure -A:deps -T:build help/doc
```
Before making any pull requests, please ensure the source code has been linted and formatted:
```
clojure -T:build lint
clojure -T:build fmt
```

Acknowledgements

I would like to give thanks:

To you (yes, you) for having the curiosity to look into this project. Thank you.
To my friends Golnaz and Nimmo, who pointed me in the direction of observability and OpenTelemetry. Without them, I wouldn’t have had the idea to make this project.
To the OpenTelemetry community and all makers of telemetry backends, for making effective observability of systems a tangible reality. Cloud-native software is so complex now, we need all the help we can get to understand how well it is (or is not) working.
To Diátaxis Framework, for a clear way to structure technical documentation.