{"id":13681871,"url":"https://github.com/steffan-westcott/clj-otel","last_synced_at":"2025-10-04T07:14:30.077Z","repository":{"id":41248275,"uuid":"462474698","full_name":"steffan-westcott/clj-otel","owner":"steffan-westcott","description":"An idiomatic Clojure API for adding telemetry to your libraries and applications using OpenTelemetry.","archived":false,"fork":false,"pushed_at":"2025-10-02T12:23:22.000Z","size":3189,"stargazers_count":220,"open_issues_count":1,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-10-02T14:23:49.453Z","etag":null,"topics":["clojure","distributed-tracing","instrumentation","metrics","observability","opentelemetry","tracing"],"latest_commit_sha":null,"homepage":"https://cljdoc.org/d/com.github.steffan-westcott/clj-otel-api","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steffan-westcott.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-02-22T21:06:55.000Z","updated_at":"2025-10-02T12:23:25.000Z","dependencies_parsed_at":"2023-12-12T14:29:02.276Z","dependency_job_id":"9dcd1d2f-45eb-43b4-964e-66c535cc604d","html_url":"https://github.com/steffan-westcott/clj-otel","commit_stats":{"total_commits":421,"total_committers":3,"mean_commits":"140.33333333333334","dds":0.004750593824228044,"last_synced_commit":"7ead19eb1f8bfaaba230b328e6b00d252d5c6c57"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/steffan-westcott/clj-otel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffan-westcott%2Fclj-otel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffan-westcott%2Fclj-otel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffan-westcott%2Fclj-otel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffan-westcott%2Fclj-otel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steffan-westcott","download_url":"https://codeload.github.com/steffan-westcott/clj-otel/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffan-westcott%2Fclj-otel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278279029,"owners_count":25960624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","distributed-tracing","instrumentation","metrics","observability","opentelemetry","tracing"],"created_at":"2024-08-02T13:01:37.197Z","updated_at":"2025-10-04T07:14:30.071Z","avatar_url":"https://github.com/steffan-westcott.png","language":"Clojure","funding_links":[],"categories":["Clojure"],"sub_categories":[],"readme":"= `clj-otel`\n:icons: font\nifdef::env-github[]\n:tip-caption: :bulb:\n:note-caption: :information_source:\n:important-caption: :heavy_exclamation_mark:\n:caution-caption: :fire:\n:warning-caption: :warning:\nendif::[]\n\nimage:https://img.shields.io/clojars/v/com.github.steffan-westcott/clj-otel-api?logo=clojure\u0026logoColor=white[Clojars,link=https://clojars.org/com.github.steffan-westcott/clj-otel-api]\nifndef::env-cljdoc[]\nimage: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]\nendif::[]\nimage:https://img.shields.io/badge/changelog-grey[changelog,link=CHANGELOG.adoc]\nimage:https://img.shields.io/github/license/steffan-westcott/clj-otel[License]\nimage:https://img.shields.io/badge/clojurians-clj--otel-blue.svg?logo=slack[Slack channel,link=https://clojurians.slack.com/messages/clj-otel]\n\n`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*.\n\n.A distributed trace displayed in https://www.honeycomb.io/[Honeycomb]\nimage::doc/images/honeycomb-trace.png[Distributed trace displayed in Honeycomb,width=600,link=\"doc/images/honeycomb-trace.png?raw=true\"]\n\n.Metrics for an HTTP server route displayed on a https://grafana.com/[Grafana] dashboard\nimage::doc/images/grafana-dashboard.png[Metrics displayed in Grafana,width=600,link=\"doc/images/grafana-dashboard.png?raw=true\"]\n\n== Requirements\n\n`clj-otel` requires Clojure 1.10.3 or higher and is based on https://github.com/open-telemetry/opentelemetry-java[OpenTelemetry for Java], which supports Java 8 and higher.\n\n== Quickstart\n\n`clj-otel` is highly configurable and may be used in many ways.\nThis quickstart briefly outlines getting started in a local environment.\nFind more in-depth information on `clj-otel` in the xref:_documentation[documentation] and xref:_examples[examples].\n\n* To add manual instrumentation to your library or application at design time\n** Add project dependency\n+\n.`deps.edn`\n[source,clojure]\n----\n{;; ...\n :deps {com.github.steffan-westcott/clj-otel-api {:mvn/version \"0.2.9\"}}}\n----\n** 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\n+\n[source,clojure]\n----\n(defn validate-profile [profile]\n  (span/with-span! [\"Validating profile\" {:system/profile-id (:id profile)}]\n    (validate profile)))\n----\n** 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\n+\n[source,clojure]\n----\n(defonce set-password-failure-count\n  (instrument/instrument {:name \"app.set-password-failure-count\"\n                          :instrument-type :counter}))\n\n(instrument/add! set-password-failure-count {:value 1\n                                             :attributes {:reason :too-short}})\n----\n\n* To export telemetry data (from both manual and automatic instrumentation) from an application at runtime\n** 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].\n** 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]\n+\n----\n\"-javaagent:opentelemetry-javaagent.jar\"\n\"-Dotel.service.name=NAME-OF-YOUR-SERVICE\"\n\"-Dotel.metrics.exporter=none\"\n\"-Dotel.logs.exporter=none\"\n----\n\n* To receive exported telemetry data\n** Prepare a telemetry backend such as Jaeger\n+\n[source,bash]\n----\ndocker run --rm                            \\\n           -p 16686:16686                  \\\n           -p 4318:4318                    \\\n           jaegertracing/all-in-one:1.71.0\n----\n\n* To explore application behaviour described by the received telemetry data\n** Use telemetry backend features such as the Jaeger user interface at http://localhost:16686/search\n\nNOTE: For demonstration configurations that export traces and metrics telemetry, see the xref:_examples[examples].\n\n[#_documentation]\n== Documentation\n\n* link:doc/tutorial.adoc[Tutorial] : A walk-through of instrumenting a small Clojure program and viewing its telemetry.\n* link:doc/guides.adoc[Guides] : Common task recipes for adding telemetry to your Clojure libraries and applications, then configuring and running applications with telemetry.\n* link:doc/reference.adoc[API \u0026 Reference] : API documentation for all `clj-otel` modules.\n* link:doc/concepts.adoc[Concepts] : A primer on observability, OpenTelemetry and what this project `clj-otel` enables for Clojure libraries and applications.\n\n[#_examples]\n== Examples\n\nFind complete example applications in the `examples` directory.\nThe examples aim to show:\n\n* Adding automatic and manual instrumentation to applications\n* Configuring and running applications that export telemetry data\n* Viewing telemetry data in backends\n\nSee more xref:doc/examples.adoc[information on configuring and running the examples].\n\n== Project status\n\n* `clj-otel` is a young, alpha grade project with limited use in a production setting.\nBreaking API changes may still be made, but there should be few, if any.\n* For manual instrumentation:\n** Coverage of the Traces API is complete.\n*** Trace semantics conventions support for https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md[recording exceptions] is complete.\n*** 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.\n*** Support for wrapping asynchronous Clojure code in spans is complete.\nThere is support for `core.async` channels, `CompletableFuture`, `Manifold` deferreds, `Missionary` tasks and a callback API.\nThe examples include applications using `core.async` with https://github.com/xadecimal/async-style[`async-style`], `CompletableFuture` with https://github.com/mpenet/auspex/[`auspex`], https://github.com/funcool/promesa[`promesa`] and https://github.com/igrishaev/whew[`whew`], https://github.com/clj-commons/manifold[`Manifold`] deferreds and https://github.com/leonoel/missionary[`Missionary`] tasks.\nThere is also a demonstration https://clojure.github.io/core.async/index.html[`core.async.flow`] instrumented application.\n** Coverage of the Metrics API is complete.\n*** Metrics HTTP semantics support for applications run without the OpenTelemetry instrumentation agent is very limited.\n** Coverage of Logs API is complete.\nNote that the Logs API is for use by logging libraries only.\nFor applications and general libraries, use a logging library with OpenTelemetry logging signal support, such as Log4j2, Timbre etc.\n* For the programmatic configuration of the OpenTelemetry SDK:\n** Coverage of Traces `TracerProvider` is complete.\n** Coverage of Metrics `MeterProvider` is in progress.\nMost configuration options are supported, but some public details of the OpenTelemetry Java SDK are not yet stable.\n** Coverage of Logs `LoggerProvider` is complete.\n\n== TODO\n\n* For manual instrumentation:\n** Consider supporting more https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/trace.md[trace semantics conventions].\n* Maintain parity with the latest version of https://github.com/open-telemetry/opentelemetry-java[`opentelemetry-java`].\n* Implement integration tests using https://github.com/javahippie/clj-test-containers[clj-test-containers] or similar.\n* Consider ClojureScript OpenTelemetry support in the browser and node.js using https://github.com/open-telemetry/opentelemetry-js[`opentelemetry-js`]; this will likely be a separate project.\n\n== Changelog\n\nSee xref:CHANGELOG.adoc[changelog]\n\n== Contributing \u0026 contact\n\nThe *most needed* contribution is *experience reports* of `clj-otel` use in production systems.\nI am keen to hear of usages of `clj-otel` and any problems and successes.\n`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.\n\nI 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.\n\nFor 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`.\n\n== Development\n\n=== Requirements\n\nTo develop `clj-otel`, you should first install the following tools:\n\n* https://clojure.org/guides/deps_and_cli[Clojure CLI tools]\n* https://github.com/clj-kondo/clj-kondo/blob/master/doc/install.md[`clj-kondo` executable binary]\n* https://github.com/kkinnear/zprint#get-zprint[`zprint` executable binary] (1.3.0 or later)\n\n=== Developing\n\n* Get information on available build scripts with this command:\n+\n[source,bash]\n----\nclojure -A:deps -T:build help/doc\n----\n* Before making any pull requests, please ensure the source code has been linted and formatted with these commands:\n+\n[source,bash]\n----\nclojure -T:build lint\nclojure -T:build fmt\n----\n\n== Acknowledgements\n\nI want to thank:\n\n* You (yes, you) for having the curiosity to look into this project.\nThank you.\n* My friends Golnaz and Nimmo, for pointing me in the direction of observability and OpenTelemetry.\nWithout them, I wouldn't have had the idea to do this project.\n* The OpenTelemetry community and all makers of telemetry backends for making the effective observability of systems a tangible reality.\nCloud-native software is so complex now, we need all the help we can get to understand how well it is (or is not) working.\n* The https://diataxis.fr/[Diátaxis Documentation Framework], for a simple way to structure technical documentation.\n\n== License\n\nCopyright © 2021-2025 Steffan Westcott +\nDistributed under the http://www.apache.org/licenses/LICENSE-2.0[Apache License v2.0]","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffan-westcott%2Fclj-otel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteffan-westcott%2Fclj-otel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffan-westcott%2Fclj-otel/lists"}