{;; ...
:deps {com.github.steffan-westcott/clj-otel-api {:mvn/version "0.2.4.1"}}}
To add telemetry to a library or application, use automatic instrumentation and/or manual instrumentation as described in the following subsections.
Follow the guide to run the application with the OpenTelemetry instrumentation agent to add automatic instrumentation.
Add project dependency :
deps.edn
{;; ...
:deps {com.github.steffan-westcott/clj-otel-api {:mvn/version "0.2.4.1"}}}
Follow the guides below to add manual traces and metrics instrumentation.
Use steffan-westcott.clj-otel.api.trace.span/with-span!
to wrap a body of forms in a span, where the current context is used to keep track of (potentially nested) spans:
(defn get-nums [args]
(span/with-span! "Getting numbers"
(fetch-nums args)))
Use steffan-westcott.clj-otel.api.trace.span/with-bound-span!
to wrap a body of forms in a span, where the bound context is used to keep track of (potentially nested) spans:
(defn get-nums [args]
(span/with-bound-span! "Getting numbers"
(fetch-nums args)))
Use steffan-westcott.clj-otel.api.trace.span/with-span-binding
to wrap a body of forms in a span, where the context to use is passed in as the :parent
option.
The new context containing the new span is bound to context*
in this example:
(defn get-nums [context args]
(span/with-span-binding [context* {:parent context
:name "Getting numbers"}]
(fetch-nums context* args)))
Use steffan-westcott.clj-otel.api.trace.span/async-bound-span
to start a new span, where the context to use is the bound context. The new span ends when either success/failure callback respond
/raise
is evaluated:
(defn get-nums-async [args respond raise]
(span/async-bound-span {:name "Getting numbers"
:kind :client}
(fn [respond* raise*]
(fetch-nums-async args respond* raise*))
respond
raise))
Use steffan-westcott.clj-otel.api.trace.span/async-span
to start a new span, where the context to use is passed in as the :parent
option. The new spans ends when either success/failure callback respond
/raise
is evaluated:
(defn get-nums-async [context args respond raise]
(span/async-span {:parent context
:name "Getting numbers"
:kind :client}
(fn [context* respond* raise*]
(fetch-nums-async context* args respond* raise*))
respond
raise))
Include an attributes map when creating a span:
(defn user-info [user-id]
(span/with-span! ["Getting user info" {:system/user-id user-id}]
(fetch-user-info user-id)))
Alternatively, use steffan-westcott.clj-otel.api.trace.span/add-span-data!
including the :attributes
option to add attributes to an existing span.
By default, the span in the bound or current context is updated:
(defn user-info [user-id]
(span/add-span-data! {:attributes {:system/user-id user-id}})
(fetch-user-info user-id))
Use the :context
option to specify the context containing the span to update:
(defn user-info [context user-id]
(span/add-span-data! {:context context
:attributes {:system/user-id user-id}})
(fetch-user-info context user-id))
Use steffan-westcott.clj-otel.api.trace.span/add-event!
to add an event to an existing span in the bound or current context.
The event may include attributes:
(defn complete-stage [job]
(span/add-event! "Job stage completed" {:service.workflow.job/stage (:stage job)})
(notify-watchers job))
Alternatively use steffan-westcott.clj-otel.api.trace.span/add-span-data!
including the :event
option for more flexibility:
(defn complete-stage [context job]
(span/add-span-data! {:context context
:event {:name "Job stage completed"
:attributes {:service.workflow.job/stage (:stage job)}}})
(notify-watchers context job))
clj-otel automatically adds events to spans for thrown exceptions which leave (escape) the span’s scope.
This behaviour applies to synchronous and asynchronous spans.
|
Use steffan-westcott.clj-otel.api.trace.span/add-exception!
to add an event describing an exception to an existing span.
Use this function to capture details about caught (non-escaping) exceptions.
The exception event may include attributes, controlled by the :attributes
option.
By default, the exception event is added to the span in the bound or current context:
(defn process-args [args]
(try
(parse-args args)
(catch Throwable e
(span/add-exception! e {:escaping? false
:attributes {:app/args args}})
{:result :parse-error})))
Use the :context
option to specify the context containing the span to add the exception event to:
(defn process-args [context args]
(try
(parse-args args)
(catch Throwable e
(span/add-exception! e {:context context
:escaping? false
:attributes {:app/args args}})
{:result :parse-error})))
See this OpenTelemetry guide to select the appropriate instrument type to use.
Follow the instructions below to create the instrument and take measurements synchronously or asynchronously, depending on the type of instrument.
Counter, up-down counter and histogram instruments support taking measurements synchronously. |
Use steffan-westcott.clj-otel.api.metrics.instrument/instrument
to create an instrument of the required type.
(defonce foo-count
(instrument/instrument {:name "app.foo-count"
:instrument-type :counter
:unit "{foo}"
:description "The number of foos counted"}))
(defonce segment-size
(instrument/instrument {:name "app.segment-size"
:instrument-type :histogram
:unit "{byte}"
:description "The size of requested segment"}))
Use steffan-westcott.clj-otel.api.metrics.instrument/add!
to add a measurement to a counter or up-down counter.
The measurement may have attributes and context.
By default, the bound or current context is used.
(defn get-red-foo [context args]
(instrument/add! foo-count {:context context
:value 1
:attributes {:colour :red}})
(red-foo args))
Use steffan-westcott.clj-otel.api.metrics.instrument/record!
to record a measurement in a histogram.
The measurement may have attributes and context.
By default, the bound or current context is used.
(defn allocate-segment [context size]
(instrument/record! segment-size {:context context
:value size
:attributes {:partition :public
:generation :young}})
(schedule-segment size))
Counter, up-down counter and gauge instruments support taking measurements asynchronously. |
Create a 0-arity function that returns a measurement, or a sequence of measurements. The measurement(s) may have attributes.
Use steffan-westcott.clj-otel.api.metrics.instrument/instrument
to create an instrument of the required type.
The second parameter is the function created in the previous step.
(defn read-temperature []
(let [temp (get-core-temp)]
{:value temp
:attributes {:location :reactor-core}}))
(defonce temperature
(instrument/instrument {:name "app.temperature"
:instrument-type :gauge
:measurement-type :long
:unit "{degree Celsius}"
:description "The operating temperature"}
read-temperature))
When running an application with the OpenTelemetry instrumentation agent, the agent automatically adds JVM runtime telemetry. |
Add project dependency :
deps.edn
{;; ...
:deps {com.github.steffan-westcott/clj-otel-instrumentation-runtime-telemetry-java8 {:mvn/version "0.2.4.1"}}}
Use steffan-westcott.clj-otel.instrumentation.runtime-telemetry-java8/register!
to add JVM runtime telemetry.
The metrics are recorded by instruments which take measurements asynchronously.
(defonce _jvm-reg (runtime-telemetry/register!))
Add project dependency :
deps.edn
{;; ...
:deps {com.github.steffan-westcott/clj-otel-instrumentation-runtime-telemetry-java17 {:mvn/version "0.2.4.1"}}}
Use steffan-westcott.clj-otel.instrumentation.runtime-telemetry-java17/register!
to add JVM runtime telemetry.
The metrics are recorded by instruments which take measurements asynchronously.
(defonce jvm-reg (runtime-telemetry/register!))
Use steffan-westcott.clj-otel.instrumentation.runtime-telemetry-java17/close!
to stop the JVM telemetry.
(runtime-telemetry/close! jvm-reg)
The guides in this section describe semantic conventions support for HTTP client and server spans.
Use Ring middleware steffan-westcott.clj-otel.api.trace.http/wrap-server-span
to add HTTP server span support to a Ring handler.
The enabled support features vary with the selected middleware options. The middleware can be configured to work in applications that run with or without the OpenTelemetry instrumentation agent. It also supports synchronous (1-arity) and asynchronous (3-arity) handlers.
This is an example using Jetty in an application run with the agent
(ns example.service
(:require [ring.adapter.jetty :as jetty]
[steffan-westcott.clj-otel.api.trace.http :as trace-http]))
(defn request-handler [request]
;; ...
)
(def handler
(-> request-handler
(trace-http/wrap-server-span {:create-span? false})))
(defonce server
(jetty/run-jetty #'handler {:port 8080 :join? false}))
Optionally, to add some HTTP server metrics for applications run without the OpenTelemetry instrumentation agent, add middleware steffan-westcott.clj-otel.api.metrics.http.server/wrap-active-requests
and steffan-westcott.clj-otel.api.metrics.http.server/wrap-metrics-by-route
.
This is the same example as above, for an application run without the agent
(ns example.service
(:require [ring.adapter.jetty :as jetty]
[steffan-westcott.clj-otel.api.metrics.http.server :as metrics-http-server]
[steffan-westcott.clj-otel.api.trace.http :as trace-http]))
(defn request-handler [request]
;; ...
)
(def handler
(-> request-handler
(metrics-http-server/wrap-metrics-by-route)
(metrics-http-server/wrap-active-requests)
(trace-http/wrap-server-span {:create-span? true})))
(defonce server
(jetty/run-jetty #'handler {:port 8080 :join? false}))
If you use middleware that injects data on the matched route into the Ring request map, add middleware steffan-westcott.clj-otel.api.trace.http/wrap-route
to add the route data to HTTP server spans for all matched routes.
Alternatively, use steffan-westcott.clj-otel.api.trace.http/wrap-reitit-route
for Reitit or steffan-westcott.clj-otel.api.trace.http/wrap-compojure-route
for Compojure.
This is an example when using Reitit, with Jetty in an application run with the agent
(ns example.service
(:require [muuntaja.core :as m]
[reitit.ring :as ring]
[ring.adapter.jetty :as jetty]
[steffan-westcott.clj-otel.api.trace.http :as trace-http]))
(defn foo-handler [request]
;; ...
)
(def handler
(ring/ring-handler (ring/router
["/foo" {:name ::foo :get foo-handler}]
{:data {:muuntaja m/instance
:middleware [trace-http/wrap-reitit-route
;; ... other middleware
]}})
(ring/create-default-handler)
;; Add HTTP server span support to all requests, including
;; those which have no matching route.
{:middleware [[trace-http/wrap-server-span {:create-span? false}]]}))
(defonce server
(jetty/run-jetty #'handler {:port 8080 :join? false}))
This is an example when using Compojure, again with Jetty in an application run with the agent
(ns example.service
(:require [compojure.core :refer [defroutes GET] :as compojure]
[ring.adapter.jetty :as jetty]
[steffan-westcott.clj-otel.api.trace.http :as trace-http]))
(defroutes handler
(GET "/foo" [] ...)
...)
(def service
(-> handler
;; Add matched Compojure route to server span data.
(compojure/wrap-routes trace-http/wrap-compojure-route)
;; Add HTTP server span support to all requests, including
;; those which have no matching route.
trace-http/wrap-server-span))
(defonce server
(jetty/run-jetty #'service {:port 8080 :join? false}))
Optionally, to add some HTTP server metrics for applications run without the OpenTelemetry instrumentation agent, add middleware steffan-westcott.clj-otel.api.metrics.http.server/wrap-active-requests
and steffan-westcott.clj-otel.api.metrics.http.server/wrap-metrics-by-route
.
This is the same example using Reitit as above, for an application run without the agent
(ns example.service
(:require [muuntaja.core :as m]
[reitit.ring :as ring]
[ring.adapter.jetty :as jetty]
[steffan-westcott.clj-otel.api.metrics.http.server :as metrics-http-server]
[steffan-westcott.clj-otel.api.trace.http :as trace-http]))
(defn foo-handler [request]
;; ...
)
(def handler
(ring/ring-handler (ring/router
["/foo" {:name ::foo :get foo-handler}]
{:data {:muuntaja m/instance
:middleware [trace-http/wrap-reitit-route
metrics-http-server/wrap-metrics-by-route
;; ... other middleware
]}})
(ring/create-default-handler)
;; Wrap handling of all requests, including those
;; which have no matching route.
{:middleware [[trace-http/wrap-server-span {:create-span? true}]
[metrics-http-server/wrap-active-requests]]}))
(defonce server
(jetty/run-jetty #'handler {:port 8080 :join? false}))
Use steffan-westcott.clj-otel.api.trace.http/server-span-interceptors
and steffan-westcott.clj-otel.api.trace.http/route-interceptor
to add HTTP server span support to a Pedestal HTTP service.
The enabled support features vary with the selected interceptor options. The interceptors can be configured to work in applications that run with or without the OpenTelemetry instrumentation agent.
An example using Jetty in an application run with the agent
(ns example.service
(:require [io.pedestal.http :as http]
[io.pedestal.http.route :as route]
[io.pedestal.interceptor :as interceptor]
[steffan-westcott.clj-otel.api.trace.http :as trace-http]))
(def routes
(route/expand-routes ... ))
(defn update-default-interceptors [default-interceptors]
(map interceptor/interceptor
(concat (trace-http/server-span-interceptors {:create-span? false})
default-interceptors
[(trace-http/route-interceptor)])))
(defn service [service-map]
(-> service-map
(http/default-interceptors)
(update ::http/interceptors update-default-interceptors)
(http/create-server)))
(def service-map
{::http/routes routes
::http/type :jetty
::http/port 8080
::http/join? false})
(defonce server
(http/start (service service-map)))
Optionally, to add some HTTP server metrics for applications run without the OpenTelemetry instrumentation agent, add interceptors steffan-westcott.clj-otel.api.metrics.http.server/active-requests-interceptor
and steffan-westcott.clj-otel.api.metrics.http.server/metrics-by-route-interceptors
This is the same example as above, for an application run without the agent
(ns example.service
(:require [io.pedestal.http :as http]
[io.pedestal.http.route :as route]
[io.pedestal.interceptor :as interceptor]
[steffan-westcott.clj-otel.api.metrics.http.server :as metrics-http-server]
[steffan-westcott.clj-otel.api.trace.http :as trace-http]))
(def routes
(route/expand-routes ... ))
(defn update-default-interceptors [default-interceptors]
(map interceptor/interceptor
(concat (trace-http/server-span-interceptors {:create-span? true})
[(metrics-http-server/active-requests-interceptor)]
default-interceptors
[(trace-http/route-interceptor)]
(metrics-http-server/metrics-by-route-interceptors))))
(defn service [service-map]
(-> service-map
(http/default-interceptors)
(update ::http/interceptors update-default-interceptors)
(http/create-server)))
(def service-map
{::http/routes routes
::http/type :jetty
::http/port 8080
::http/join? false})
(defonce server
(http/start (service service-map)))
Route data is automatically added to server spans when using the Ring middleware steffan-westcott.clj-otel.api.trace.http/wrap-route or Pedestal interceptor steffan-westcott.clj-otel.api.trace.http/route-interceptor
|
Use steffan-westcott.clj-otel.api.trace.http/add-route-data!
to add the matched route to a server span.
By default, the route data is added to the span in the bound or current context:
(trace-http/add-route-data! :get "/rooms/:room-id")
Use the :context
option to specify the context containing the span to add the route data to:
(trace-http/add-route-data! :get "/rooms/:room-id" {:context context})
When running an application with the OpenTelemetry instrumentation agent, the agent automatically adds HTTP response data to client spans for supported clients. |
Use steffan-westcott.clj-otel.api.trace.http/add-client-span-response-data!
to add HTTP response data to a client span.
Use this function when working with an HTTP client not supported by the OpenTelemetry instrumentation agent.
By default, the HTTP response data is added to the span in the bound or current context:
(trace-http/add-client-span-response-data! response)
Use the :context
option to specify the context containing the span to add the HTTP response data to:
(trace-http/add-client-span-response-data! response {:context context})
When running an application with the OpenTelemetry instrumentation agent, the agent automatically propagates the context in HTTP client requests for supported clients. |
Use steffan-westcott.clj-otel.context/->headers
to get headers to merge (inject) with other headers in the HTTP request to be issued for context propagation.
Use this function when working with an HTTP client not supported by the OpenTelemetry instrumentation agent.
By default, the bound or current context is propagated:
(let [context-headers (context/->headers)
request' (update request :headers merge context-headers)]
;; ...
)
Use the :context
option to specify the context to be propagated:
(let [context-headers (context/->headers {:context context})
request' (update request :headers merge context-headers)]
;; ...
)
The options below determine what telemetry data is exported from an application as it runs. Select one of these options and follow the linked guide:
Run with the OpenTelemetry auto-instrumentation agent
Select this option to export telemetry data produced by automatic and manual instrumentation.
Run with autoconfigure SDK extension
Select this option to export telemetry data from manual instrumentation only; The SDK will be configured using properties or environment variables.
Run with programmatically configured SDK
Select this option to export telemetry data from manual instrumentation only; The SDK will be configured programmatically in the application.
Select this option to mute all telemetry data.
Traces, metrics and logs telemetry data are muted in the last option or by setting the autoconfiguration properties otel.traces.exporter , otel.metrics.exporter and otel.logs.exporter to none (the defaults are otlp for all properties) when using either of the first two options.
|
Download the latest version of the OpenTelemetry instrumentation agent JAR, the file opentelemetry-javaagent.jar
from the releases page.
The agent JAR includes the SDK and all its dependencies.
Configure the agent and SDK using properties and environment variables. See the agent and SDK configuration documentation.
When running the application, enable the agent with the -javaagent
JVM flag.
For an example application my-app
that exports traces only using OTLP over gRPC, use a project configuration like the following:
deps.edn
{;; ...
:aliases {
:otel {:jvm-opts ["-javaagent:path/to/opentelemetry-javaagent.jar"
"-Dotel.resource.attributes=service.name=my-app"
"-Dotel.traces.exporter=otlp"
"-Dotel.metrics.exporter=none"
"-Dotel.logs.exporter=none"
"-Dotel.exporter.otlp.traces.protocol=grpc"]}}}
Add project dependencies:
Required: com.github.steffan-westcott/clj-otel-sdk-extension-autoconfigure
for the SDK itself, SDK extension and a Clojure wrapper for initialisation.
Required: io.opentelemetry/opentelemetry-exporter-???
for any exporters referenced in the configuration.
See Java exporter libraries supported by autoconfiguration.
Optional: io.opentelemetry.instrumentation/opentelemetry-resources
for various resources to be automatically added to telemetry data.
Optional: io.opentelemetry.contrib/opentelemetry-aws-resources
for various resources describing the AWS execution environment to be automatically added to telemetry data.
Optional: io.opentelemetry.contrib/opentelemetry-aws-xray-propagator
for text map propagator implementing the AWS X-Ray Trace Header propagation protocol.
Optional: io.opentelemetry/opentelemetry-extension-trace-propagators
for text map propagators implementing OpenTracing Basic Tracers, Jaeger and B3 propagation protocols.
Optional: io.grpc/grpc-netty-shaded
, io.grpc/grpc-protobuf
and io.grpc/grpc-stub
to use Netty for gRPC transport rather than the default OkHttp (see example below).
This is not needed if gRPC is not used by any exporters or the application.
Configure the SDK using properties and environment variables.
See SDK autoconfigure configuration documentation for details on all autoconfiguration options.
At application start, use steffan-westcott.clj-otel.sdk.autoconfigure/init-otel-sdk!
to initialise a configured SDK instance.
By default, the instance is set as the default OpenTelemetry
used by clj-otel
and a JVM shutdown hook is registered to close it.
For an example application my-app
that exports traces only using OTLP over gRPC with Netty transport, use a project configuration like the following:
deps.edn
{;; ...
:deps {com.github.steffan-westcott/clj-otel-sdk-extension-autoconfigure {:mvn/version "0.2.4.1"}}
:aliases {
:otel {:jvm-opts ["-Dotel.resource.attributes=service.name=my-app"
"-Dotel.traces.exporter=otlp"
"-Dotel.metrics.exporter=none"
"-Dotel.logs.exporter=none"
"-Dotel.exporter.otlp.traces.protocol=grpc"]
:extra-deps {io.opentelemetry/opentelemetry-exporter-otlp {:mvn/version "1.33.0"}
io.opentelemetry.instrumentation/opentelemetry-resources {:mvn/version "1.32.0-alpha"}
io.grpc/grpc-netty-shaded {:mvn/version "1.60.1"}
io.grpc/grpc-protobuf {:mvn/version "1.60.1"}
io.grpc/grpc-stub {:mvn/version "1.60.1"}}}}}
To initialise a configured SDK instance, set as default OpenTelemetry
and register a shutdown hook to close:
example/my-app.clj
(ns example.my-app
(:require [steffan-westcott.clj-otel.sdk.autoconfigure :as autoconfig]))
(defn init-otel! []
(autoconfig/init-otel-sdk!))
Add project dependencies:
Required: com.github.steffan-westcott/clj-otel-sdk
for the SDK itself and a Clojure wrapper of SDK configuration
Required: com.github.steffan-westcott/clj-otel-exporter-???
for Clojure wrapped versions of any exporters referenced in the configuration.
See Clojure wrapped versions of exporters supported by autoconfiguration.
Optional: com.github.steffan-westcott/clj-otel-sdk-extension-resources
for Clojure wrapped versions of various resources to add to telemetry data.
Optional: com.github.steffan-westcott/clj-otel-contrib-aws-resources
for Clojure wrapped versions of resources describing the AWS execution environment.
Optional: com.github.steffan-westcott/clj-otel-contrib-aws-xray-propagator
for Clojure wrapped text map propagator implementing the AWS X-Ray Trace Header propagation protocol.
Optional: com.github.steffan-westcott/clj-otel-extension-trace-propagators
for Clojure wrapped text map propagators implementing OpenTracing Basic Tracers, Jaeger and B3 propagation protocols.
Optional: io.grpc/grpc-netty-shaded
, io.grpc/grpc-protobuf
and io.grpc/grpc-stub
to use Netty for gRPC transport rather than the default OkHttp (see example below).
This is not needed if gRPC is not used by any exporters or the application.
At application start, use steffan-westcott.clj-otel.sdk.otel-sdk/init-otel-sdk!
to configure and initialise an SDK instance.
By default, the instance is set as the default OpenTelemetry
used by clj-otel
and a JVM shutdown hook is registered to close it.
For an example application my-app
that exports traces only using OTLP over gRPC with Netty transport, use a project configuration like the following:
deps.edn
{;; ...
:deps {com.github.steffan-westcott/clj-otel-exporter-otlp {:mvn/version "0.2.4.1"}
com.github.steffan-westcott/clj-otel-sdk-extension-resources {:mvn/version "0.2.4.1"}
com.github.steffan-westcott/clj-otel-sdk {:mvn/version "0.2.4.1"}
io.grpc/grpc-netty-shaded {:mvn/version "1.60.1"}
io.grpc/grpc-protobuf {:mvn/version "1.60.1"}
io.grpc/grpc-stub {:mvn/version "1.60.1"}}}
To initialise a configured SDK instance, set as default OpenTelemetry
and register a shutdown hook to close:
example/app.clj
(ns example.my-app
(:require [steffan-westcott.clj-otel.exporter.otlp-grpc-trace :as otlp-grpc-trace]
[steffan-westcott.clj-otel.resource.resources :as res]
[steffan-westcott.clj-otel.sdk.otel-sdk :as sdk]))
(defn init-otel! []
(sdk/init-otel-sdk!
"my-app"
{:resources [(res/host-resource)
(res/os-resource)
(res/process-resource)
(res/process-runtime-resource)]
:tracer-provider
{:span-processors
[{:exporters [(otlp-grpc-trace/span-exporter)]}]}}))
There are no steps to add dependencies or otherwise configure the application to run without the agent or SDK.
An application run without the OpenTelemetry instrumentation agent or SDK will not export any telemetry data. Usage of the OpenTelemetry API (manual instrumentation) in the application will invoke no-op implementations. |
The OpenTelemetry Collector is used to manage telemetry data in transit, as an alternative to applications exporting data directly to telemetry backends.
See the configuration documentation.
This example Collector configuration has a traces
pipeline where:
Trace data are received by the Collector as OTLP over gRPC
Memory usage in the Collector process is limited
Traces are batched in the Collector prior to export to the backend
Traces are exported by the Collector as OTLP over gRPC to the Jaeger backend on host jaeger
otel-collector-config.yaml
receivers:
otlp:
protocols:
grpc:
processors:
memory_limiter:
check_interval: 1s
limit_mib: 750
batch:
exporters:
otlp:
endpoint: "jaeger:4317"
tls:
insecure: true
service:
pipelines:
traces:
receivers: [ otlp ]
processors: [ memory_limiter, batch ]
exporters: [ otlp ]
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close