Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/steffan-westcott/clj-otel

An idiomatic Clojure API for adding telemetry to your libraries and applications using OpenTelemetry.
https://github.com/steffan-westcott/clj-otel

clojure distributed-tracing instrumentation metrics observability opentelemetry tracing

Last synced: 27 days ago
JSON representation

An idiomatic Clojure API for adding telemetry to your libraries and applications using OpenTelemetry.

Awesome Lists containing this project

README 

        
= `clj-otel`

:icons: font

ifdef::env-github[]

:tip-caption: :bulb:

:note-caption: :information_source:

:important-caption: :heavy_exclamation_mark:

:caution-caption: :fire:

:warning-caption: :warning:

endif::[]



image:https://img.shields.io/clojars/v/com.github.steffan-westcott/clj-otel-api?logo=clojure&logoColor=white[Clojars,link=https://clojars.org/com.github.steffan-westcott/clj-otel-api]

ifndef::env-cljdoc[]

image:https://cljdoc.org/badge/com.github.steffan-westcott/clj-otel-api[cljdoc,link=https://cljdoc.org/d/com.github.steffan-westcott/clj-otel-api/CURRENT]

endif::[]

image:https://img.shields.io/badge/changelog-grey[changelog,link=CHANGELOG.adoc]

image:https://img.shields.io/github/license/steffan-westcott/clj-otel[License]

image:https://img.shields.io/badge/clojurians-clj--otel-blue.svg?logo=slack[Slack channel,link=https://clojurians.slack.com/messages/clj-otel]



`clj-otel` provides a *small idiomatic Clojure API* for adding *telemetry* to your libraries and applications using https://opentelemetry.io/[*OpenTelemetry*], an emerging standard for telemetry in cloud-native software, enabling effective *observability*.



.A distributed trace displayed in https://www.honeycomb.io/[Honeycomb]

image::doc/images/honeycomb-trace.png[Distributed trace displayed in Honeycomb,width=600,link="doc/images/honeycomb-trace.png?raw=true"]



.Metrics for an HTTP server route displayed on a https://grafana.com/[Grafana] dashboard

image::doc/images/grafana-dashboard.png[Metrics displayed in Grafana,width=600,link="doc/images/grafana-dashboard.png?raw=true"]



== Requirements



`clj-otel` is tested with Clojure 1.11.1 and is based on the reference https://github.com/open-telemetry/opentelemetry-java[OpenTelemetry for Java] implementation, 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 xref:_documentation[documentation] and xref:_examples[examples].



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

** Add project dependency

+

.`deps.edn`

[source,clojure]

----

{;; ...

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

----

** To add traces telemetry, use Clojure functions such as https://cljdoc.org/d/com.github.steffan-westcott/clj-otel-api/CURRENT/api/steffan-westcott.clj-otel.api.trace.span#with-span![`steffan-westcott.clj-otel.api.trace.span/with-span!`] to create spans with attributes

+

[source,clojure]

----

(defn validate-profile [profile]

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

    (validate profile)))

----

** To add metrics telemetry, use Clojure functions in https://cljdoc.org/d/com.github.steffan-westcott/clj-otel-api/CURRENT/api/steffan-westcott.clj-otel.api.metrics.instrument[`steffan-westcott.clj-otel.api.metrics.instrument`] to create instruments, then add or record measurements with attributes

+

[source,clojure]

----

(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 https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases[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 https://www.jaegertracing.io/[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

+

[source,bash]

----

docker run --rm                            \

           -p 16686:16686                  \

           -p 4318:4318                    \

           jaegertracing/all-in-one:1.58.1

----



* 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



NOTE: For demonstration configurations that export traces and metrics telemetry, see the xref:_examples[examples].



[#_documentation]

== Documentation



* link:doc/tutorial.adoc[Tutorial] : A walk-through of instrumenting a small Clojure program and viewing its telemetry.

* link:doc/guides.adoc[Guides] : Common task recipes for adding telemetry to your Clojure libraries and applications, then configuring and running applications with telemetry.

* link:doc/reference.adoc[API & Reference] : API documentation for all `clj-otel` modules.

* link:doc/concepts.adoc[Concepts] : A primer on observability, OpenTelemetry and what this project `clj-otel` enables for Clojure libraries and applications.



[#_examples]

== 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 xref:doc/examples.adoc[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 https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md[recording exceptions] is complete.

*** Trace semantics support for https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md[HTTP spans] in applications run without the OpenTelemetry instrumentation agent is limited.

*** 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 `