An idiomatic Clojure API for adding telemetry to your libraries and applications using OpenTelemetry.
APACHE-2.0 License
= clj-otel
:icons: font
ifdef::env-github[]
:tip-caption: 💡
:note-caption: ℹ️
:important-caption: ❗
:caution-caption: 🔥
:warning-caption: ⚠️
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].
deps.edn
(defonce set-password-failure-count (instrument/instrument {:name "app.set-password-failure-count" :instrument-type :counter}))
opentelemetry-javaagent.jar
from the https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases[OpenTelemetry instrumentation agent releases page].NOTE: For demonstration configurations that export traces and metrics telemetry, see the xref:_examples[examples].
[#_documentation] == Documentation
clj-otel
modules.clj-otel
enables for Clojure libraries and applications.[#_examples] == Examples
Find complete example applications in the examples
directory.
The examples aim to show:
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.core.async
channels can be found in the examples, specifically the <with-span-binding
macro.TracerProvider
is complete.MeterProvider
is in progress.LoggerProvider
.== TODO
== Changelog
See xref:CHANGELOG.adoc[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 https://clojurians.slack.com/messages/clj-otel[`#clj-otel`] channel in http://clojurians.net/[Clojurians Slack], user steffan
.
== Development
=== Requirements
To develop clj-otel
, you should first install the following tools:
=== Developing
== Acknowledgements
I want to thank:
== License
Copyright © 2021-2024 Steffan Westcott + Distributed under the http://www.apache.org/licenses/LICENSE-2.0[Apache License v2.0]