clj-otel

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

Figure 2. Metrics for an HTTP server route displayed on a Grafana dashboard

Requirements

clj-otel requires Clojure 1.10.3 or higher and is based on OpenTelemetry for Java, which supports Java 8 and higher.

Quickstart

clj-otel is highly configurable and may be used in many ways. This quickstart briefly outlines getting started in a local environment. Find more in-depth information on clj-otel 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.2.9"}}}

  • To add traces telemetry, 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! ["Validating profile" {:system/profile-id (:id profile)}]
        (validate profile)))

  • To add metrics telemetry, use Clojure functions in steffan-westcott.clj-otel.api.metrics.instrument to create instruments, then add or record measurements with attributes

    (defonce set-password-failure-count
      (instrument/instrument {:name "app.set-password-failure-count"
                              :instrument-type :counter}))
    
    (instrument/add! set-password-failure-count {:value 1
                                                 :attributes {:reason :too-short}})

• 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 of traces telemetry only to an OTLP compliant backend such as Jaeger

    "-javaagent:opentelemetry-javaagent.jar"
    "-Dotel.resource.attributes=service.name=NAME-OF-YOUR-SERVICE"
    "-Dotel.metrics.exporter=none"
    "-Dotel.logs.exporter=none"

• To receive exported telemetry data

  • Prepare a telemetry backend such as Jaeger

    docker run --rm                            \
               -p 16686:16686                  \
               -p 4318:4318                    \
               jaegertracing/all-in-one:1.71.0

• 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

ℹ️	For demonstration configurations that export traces and metrics telemetry, see the examples.

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

Find complete example applications 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 with limited use in a production setting. Breaking API changes may still be made, but there should be few, if any.

• For manual instrumentation:

  • Coverage of the Traces API is complete.

    • Trace semantics conventions support for recording exceptions is complete.

    • Trace semantics support for HTTP spans in applications run without the OpenTelemetry instrumentation agent is limited.

    • Support for wrapping asynchronous Clojure code in spans is complete. There is support for core.async channels, CompletableFuture, Manifold deferreds, Missionary tasks and a callback API. The examples include applications using core.async with async-style, CompletableFuture with auspex, promesa and whew, Manifold deferreds and Missionary tasks. There is also a demonstration core.async.flow instrumented application.

  • Coverage of the Metrics API is complete.

    • Metrics HTTP semantics support for applications run without the OpenTelemetry instrumentation agent is very limited.

  • There is currently no coverage of the Logs API, but OpenTelemetry log exporters work as expected without clj-otel assistance.

• For the programmatic configuration of the OpenTelemetry SDK:

  • Coverage of Traces TracerProvider is complete.

  • Coverage of Metrics MeterProvider is in progress. Most configuration options are supported, but some public details of the OpenTelemetry Java SDK are not yet stable.

  • There is currently no coverage of Logging LoggerProvider.

TODO

• For manual instrumentation:

  • Add 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; this will likely be a separate project.

Changelog

See changelog

Contributing & contact

The most needed contribution is experience reports of clj-otel use in production systems. I am keen to hear of usages of clj-otel and any problems and successes. clj-otel is a very young project, so now is an ideal 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 I may not accept more significant changes while I make a start on some items in the TODO list.

For questions or feedback on clj-otel, contact me on the #clj-otel channel in Clojurians Slack, user steffan.

Development

Requirements

To develop clj-otel, you should first install the following tools:

• Clojure CLI tools

• clj-kondo executable binary

• zprint executable binary (1.2.9 or later)

Developing

• Get information on available build scripts with this command:

  clojure -A:deps -T:build help/doc

• Before making any pull requests, please ensure the source code has been linted and formatted with these commands:

  clojure -T:build lint
  clojure -T:build fmt

Acknowledgements

I want to thank:

• You (yes, you) for having the curiosity to look into this project. Thank you.

• My friends Golnaz and Nimmo, for pointing me in the direction of observability and OpenTelemetry. Without them, I wouldn’t have had the idea to do this project.

• The OpenTelemetry community and all makers of telemetry backends for making the 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.

• The Diátaxis Documentation Framework, for a simple way to structure technical documentation.

License

Copyright © 2021-2025 Steffan Westcott
Distributed under the Apache License v2.0