Functions for manipulating spans.
Functions for manipulating spans.
(add-event! name)(add-event! name attributes)Adds an event to the bound or current context. name is a string, keyword or
symbol to use as the event name. attributes is a map of attributes to
attach to the event. For more flexible options, use add-span-data!.
Adds an event to the bound or current context. `name` is a string, keyword or symbol to use as the event name. `attributes` is a map of attributes to attach to the event. For more flexible options, use [[add-span-data!]].
(add-exception! exception)(add-exception! exception
{:keys [context attributes]
:or {context (context/dyn) attributes ex-data}})Adds an event describing an exception that is escaping a span's scope. By
default, exception data (as per ex-info) are added as attributes to the
event. The span's status is set to :error with the exception triage
summary as the error description. May take an option map as follows:
| key | description |
|---|---|
:context | Context containing span to add exception event to (default: bound or current context). |
:attributes | Either a function which takes exception and returns a map of additional attributes for the event, or a map of additional attributes (default: ex-data). |
Adds an event describing an `exception` that is escaping a span's scope. By default, exception data (as per `ex-info`) are added as attributes to the event. The span's status is set to `:error` with the exception triage summary as the error description. May take an option map as follows: | key | description | |-------------|-------------| |`:context` | Context containing span to add exception event to (default: bound or current context). |`:attributes`| Either a function which takes `exception` and returns a map of additional attributes for the event, or a map of additional attributes (default: `ex-data`).
(add-interceptor-exception! e)(add-interceptor-exception! e
{:keys [context attributes]
:or {context (context/dyn) attributes ex-data}})Adds an event describing an interceptor exception e that is escaping a
span's scope. Attributes identifying the interceptor and stage are added to
the event. Also, by default exception data (as per ex-info) are added as
attributes. The span's status is set to :error with the wrapped exception
triage summary as the error description. May take an option map as follows:
| key | description |
|---|---|
:context | Context containing span to add exception event to (default: bound or current context) |
:attributes | Either a function which takes exception and returns a map of additional attributes for the event, or a map of additional attributes (default: ex-data). |
Adds an event describing an interceptor exception `e` that is escaping a span's scope. Attributes identifying the interceptor and stage are added to the event. Also, by default exception data (as per `ex-info`) are added as attributes. The span's status is set to `:error` with the wrapped exception triage summary as the error description. May take an option map as follows: | key | description | |-------------|-------------| |`:context` | Context containing span to add exception event to (default: bound or current context) |`:attributes`| Either a function which takes `exception` and returns a map of additional attributes for the event, or a map of additional attributes (default: `ex-data`).
(add-span-data! {:keys [context name status attributes event ex-data links]
:or {context (context/dyn)}})Adds data to a span. All data values documented here are optional unless otherwise noted as required. Takes a top level option map as follows:
Top level option map
| key | description |
|---|---|
:context | Context containing span to add data to (default: bound or current context). |
:name | String, keyword or symbol to set as the span name. |
:status | Option map (see below) describing span status to set. |
:attributes | Map of additional attributes to merge in the span. |
:event | Option map (see below) describing an event to add to the span. |
:ex-data | Option map (see below) describing an exception event to add to the span. |
:links | Collection of links to add to span. Each link is [sc] or [sc attr-map], where sc is a SpanContext, Span or Context containing the linked span and attr-map is a map of attributes of the link. |
:status option map
| key | description |
|---|---|
:code | Status code, either :ok or :error (required). |
:description | Status description string, only applicable with :error status code. |
:event option map
| key | description |
|---|---|
:name | String, keyword or symbol to set as the event name. |
:attributes | Map of attributes to attach to the event. |
:timestamp | Event timestamp, value is either an Instant or vector [amount ^TimeUnit unit]. |
:ex-data option map
| key | description |
|---|---|
:exception | Exception instance (required). |
:attributes | Map of additional attributes to attach to exception event. |
Adds data to a span. All data values documented here are optional unless otherwise noted as required. Takes a top level option map as follows: Top level option map | key | description | |-------------|-------------| |`:context` | Context containing span to add data to (default: bound or current context). |`:name` | String, keyword or symbol to set as the span name. |`:status` | Option map (see below) describing span status to set. |`:attributes`| Map of additional attributes to merge in the span. |`:event` | Option map (see below) describing an event to add to the span. |`:ex-data` | Option map (see below) describing an exception event to add to the span. |`:links` | Collection of links to add to span. Each link is `[sc]` or `[sc attr-map]`, where `sc` is a `SpanContext`, `Span` or `Context` containing the linked span and `attr-map` is a map of attributes of the link. `:status` option map | key | description | |--------------|-------------| |`:code` | Status code, either `:ok` or `:error` (required). |`:description`| Status description string, only applicable with `:error` status code. `:event` option map | key | description | |-------------|-------------| |`:name` | String, keyword or symbol to set as the event name. |`:attributes`| Map of attributes to attach to the event. |`:timestamp` | Event timestamp, value is either an `Instant` or vector `[amount ^TimeUnit unit]`. `:ex-data` option map | key | description | |-------------|-------------| |`:exception` | Exception instance (required). |`:attributes`| Map of additional attributes to attach to exception event.
(as-span-opts x)Coerce to span options map for new-span!
Coerce to span options map for `new-span!`
(async-bound-cf-span span-opts & body)Returns a CompletableFuture that starts a new span, sets the bound context
to the new context containing the span and evaluates body which is
expected give a CompletableFuture that may use any specified Executor.
The span is ended on completion. Asynchronous functions within body should
be defined using bound-fn or similar to convey bindings such as the bound
context.
Returns a `CompletableFuture` that starts a new span, sets the bound context to the new context containing the span and evaluates `body` which is expected give a `CompletableFuture` that may use any specified `Executor`. The span is ended on completion. Asynchronous functions within `body` should be defined using `bound-fn` or similar to convey bindings such as the bound context.
(async-bound-span span-opts f respond raise)Starts a new span, sets the bound context to the new context containing the
span and immediately returns evaluation of function f. The bound context is
restored to its original value after f is evaluated. respond/raise are
callback functions to be evaluated later on a success/failure result. The
span is ended just before either callback is evaluated or f itself throws
an exception. Does not use nor mutate the current context. This is a
low-level function intended for adaption for use with any async library that
can work with callbacks. span-opts is the same as for new-span!. f
must take arguments [respond* raise*] where respond* and raise* are
callback functions to be used by f. All callback functions take a single
argument, raise and raise* take a Throwable instance.
Starts a new span, sets the bound context to the new context containing the span and immediately returns evaluation of function `f`. The bound context is restored to its original value after `f` is evaluated. `respond`/`raise` are callback functions to be evaluated later on a success/failure result. The span is ended just before either callback is evaluated or `f` itself throws an exception. Does not use nor mutate the current context. This is a low-level function intended for adaption for use with any async library that can work with callbacks. `span-opts` is the same as for [[new-span!]]. `f` must take arguments `[respond* raise*]` where `respond*` and `raise*` are callback functions to be used by `f`. All callback functions take a single argument, `raise` and `raise*` take a `Throwable` instance.
(async-span span-opts f respond raise)Starts a new span and immediately returns evaluation of function f.
respond/raise are callback functions to be evaluated later on a
success/failure result. The span is ended just before either callback is
evaluated or f itself throws an exception. Does not use nor mutate the
current context. This is a low-level function intended for adaption for use
with any async library that can work with callbacks. span-opts is the same
as for new-span!. f must take arguments [context respond* raise*]
where context is a context containing the new span, respond* and
raise* are callback functions to be used by f. All callback functions
take a single argument, raise and raise* take a Throwable instance.
Starts a new span and immediately returns evaluation of function `f`. `respond`/`raise` are callback functions to be evaluated later on a success/failure result. The span is ended just before either callback is evaluated or `f` itself throws an exception. Does not use nor mutate the current context. This is a low-level function intended for adaption for use with any async library that can work with callbacks. `span-opts` is the same as for [[new-span!]]. `f` must take arguments `[context respond* raise*]` where `context` is a context containing the new span, `respond*` and `raise*` are callback functions to be used by `f`. All callback functions take a single argument, `raise` and `raise*` take a `Throwable` instance.
(cf-span-binding [context span-opts] & body)Returns a CompletableFuture that starts a new span, binds context to the
new context containing the span and evaluates body which is expected give
a CompletableFuture that may use any specified Executor. The span is
ended on completion. Asynchronous functions within body should be defined
using bound-fn or similar to convey bindings.
Returns a `CompletableFuture` that starts a new span, binds `context` to the new context containing the span and evaluates `body` which is expected give a `CompletableFuture` that may use any specified `Executor`. The span is ended on completion. Asynchronous functions within `body` should be defined using `bound-fn` or similar to convey bindings.
(end-span! {:keys [context timestamp] :or {context (context/dyn)}})Low level function that ends a span, previously started by new-span!.
Does not mutate the current context. Takes an options map as follows:
| key | description |
|---|---|
:context | Context containing span to end (default: bound or current context) |
:timestamp | Span end timestamp. Value is either an Instant or vector [amount ^TimeUnit unit] (default: current timestamp). |
Low level function that ends a span, previously started by [[new-span!]]. Does not mutate the current context. Takes an options map as follows: | key | description | |------------|-------------| |`:context` | Context containing span to end (default: bound or current context) |`:timestamp`| Span end timestamp. Value is either an `Instant` or vector `[amount ^TimeUnit unit]` (default: current timestamp).
(get-span)(get-span context)Gets the span from a given context, or the bound or current context if none is given. If no span is found in the context (or no context is available), a non-recording, non-exporting span is returned.
Gets the span from a given context, or the bound or current context if none is given. If no span is found in the context (or no context is available), a non-recording, non-exporting span is returned.
(get-span-context)(get-span-context x)Returns the given SpanContext, or extracts it from the given span or
context. If no argument is given, extract from the bound or current context.
Returns the given `SpanContext`, or extracts it from the given span or context. If no argument is given, extract from the bound or current context.
(get-tracer)(get-tracer {:keys [name version schema-url open-telemetry]
:or {name (:name default-library)
version (:version default-library)
schema-url (:schema-url default-library)}})Builds and returns a io.opentelemetry.api.trace.Tracer instance. May take
an option map as follows:
| key | description |
|---|---|
:name | Name of the instrumentation library, not the instrumented library e.g. "io.opentelemetry.contrib.mongodb" (default: See config.edn resource file). |
:version | Instrumentation library version e.g. "1.0.0" (default: See config.edn resource file). |
:schema-url | URL of OpenTelemetry schema used by this instrumentation library (default: See config.edn resource file). |
:open-telemetry | OpenTelemetry instance to get tracer from (default: global OpenTelemetry instance). |
Builds and returns a `io.opentelemetry.api.trace.Tracer` instance. May take an option map as follows: | key | description | |-----------------|-------------| |`:name` | Name of the *instrumentation* library, not the *instrumented* library e.g. `"io.opentelemetry.contrib.mongodb"` (default: See `config.edn` resource file). |`:version` | Instrumentation library version e.g. `"1.0.0"` (default: See `config.edn` resource file). |`:schema-url` | URL of OpenTelemetry schema used by this instrumentation library (default: See `config.edn` resource file). |`:open-telemetry`| `OpenTelemetry` instance to get tracer from (default: global `OpenTelemetry` instance).
(new-span! span-opts)Low level macro that starts a new span and returns the context containing
the new span. Does not mutate the current context. The span must be ended by
evaluating end-span! to avoid broken traces and memory leaks. Use higher
level helpers with-span!, with-bound-span!, with-span-binding,
async-span, async-bound-span, cf-span-binding or
async-bound-cf-span instead of this macro to reliably manage the context
and end the span.
span-opts is a single expression that may be one of several types.
span-opts as a map specifies all available options as follows:
| key | description |
|---|---|
:tracer | io.opentelemetry.api.trace.Tracer used to create the span (default: default tracer, as set by set-default-tracer!; if no default tracer has been set, one will be set with default config). |
:name | String, keyword or symbol used for (qualified) span name (default: ""). |
:parent | Context used to take parent span. If nil or no span is available in the context, the root context is used instead (default: bound or current context). |
:links | Collection of links to add to span. Each link is [sc] or [sc attr-map], where sc is a SpanContext, Span or Context containing the linked span and attr-map is a map of attributes of the link (default: no links). |
:attributes | Map of additional attributes for the span (default: no attributes). |
:thread | Thread identified as that which started the span, or nil for no thread. Data on this thread is merged with the :attributes value (default: current thread). |
:source | Map describing source code where span is started. Optional keys are :fn, :line, :col and :file (default: :fn, :line and :file where new-span! is expanded). |
:span-kind | Span kind, one of :internal, :server, :client, :producer, :consumer (default: :internal). See also SpanKind. |
:timestamp | Start timestamp for the span. Value is either an Instant or vector [amount ^TimeUnit unit] (default: current timestamp). |
span-opts as a string, keyword or symbol specifies a span with a
(qualified) name. All other options take default values shown above.
span-opts as a vector [name attrs] specifies a span with the given
(qualified) name and map of attributes. All other options take default values
shown above.
Low level macro that starts a new span and returns the context containing the new span. Does not mutate the current context. The span must be ended by evaluating [[end-span!]] to avoid broken traces and memory leaks. Use higher level helpers [[with-span!]], [[with-bound-span!]], [[with-span-binding]], [[async-span]], [[async-bound-span]], [[cf-span-binding]] or [[async-bound-cf-span]] instead of this macro to reliably manage the context and end the span. `span-opts` is a single expression that may be one of several types. `span-opts` as a map specifies all available options as follows: | key | description | |-------------|-------------| |`:tracer` | `io.opentelemetry.api.trace.Tracer` used to create the span (default: default tracer, as set by [[set-default-tracer!]]; if no default tracer has been set, one will be set with default config). |`:name` | String, keyword or symbol used for (qualified) span name (default: `""`). |`:parent` | Context used to take parent span. If `nil` or no span is available in the context, the root context is used instead (default: bound or current context). |`:links` | Collection of links to add to span. Each link is `[sc]` or `[sc attr-map]`, where `sc` is a `SpanContext`, `Span` or `Context` containing the linked span and `attr-map` is a map of attributes of the link (default: no links). |`:attributes`| Map of additional attributes for the span (default: no attributes). |`:thread` | Thread identified as that which started the span, or `nil` for no thread. Data on this thread is merged with the `:attributes` value (default: current thread). |`:source` | Map describing source code where span is started. Optional keys are `:fn`, `:line`, `:col` and `:file` (default: `:fn`, `:line` and `:file` where `new-span!` is expanded). |`:span-kind` | Span kind, one of `:internal`, `:server`, `:client`, `:producer`, `:consumer` (default: `:internal`). See also `SpanKind`. |`:timestamp` | Start timestamp for the span. Value is either an `Instant` or vector `[amount ^TimeUnit unit]` (default: current timestamp). `span-opts` as a string, keyword or symbol specifies a span with a (qualified) name. All other options take default values shown above. `span-opts` as a vector `[name attrs]` specifies a span with the given (qualified) name and map of attributes. All other options take default values shown above.
(set-default-tracer! tracer)Sets the default io.opentelemetry.api.trace.Tracer instance used when
creating spans. Returns tracer. See also get-tracer.
Sets the default `io.opentelemetry.api.trace.Tracer` instance used when creating spans. Returns `tracer`. See also [[get-tracer]].
(span-interceptor context-key span-opts-fn)Returns a Pedestal interceptor that will on entry start a new span and add
the context containing the new span to the interceptor map with key
context-key. span-opts-fn is a function which takes the interceptor
context and returns span-opts as for new-span!. The span is ended on
interceptor exit (either leave or error). Does not use nor set the
current context. This is not specific to HTTP service handling, see
steffan-westcott.clj-otel.api.trace.http/server-span-interceptors for
adding HTTP server span support to HTTP services.
Returns a Pedestal interceptor that will on entry start a new span and add the context containing the new span to the interceptor map with key `context-key`. `span-opts-fn` is a function which takes the interceptor context and returns `span-opts` as for [[new-span!]]. The span is ended on interceptor exit (either `leave` or `error`). Does not use nor set the current context. This is not specific to HTTP service handling, see [[steffan-westcott.clj-otel.api.trace.http/server-span-interceptors]] for adding HTTP server span support to HTTP services.
(with-bound-span! span-opts & body)Starts a new span, sets the bound context to the new context containing the
span and evaluates body. The bound context is restored to its previous
value and the span is ended on completion of body evaluation. It is expected
body provides a synchronous result, use async-span,
async-bound-span, cf-span-binding or async-bound-cf-span instead
for working with asynchronous functions. Does not use nor set the current
context. span-opts is the same as for new-span!. See also
with-span! and with-span-binding.
Starts a new span, sets the bound context to the new context containing the span and evaluates `body`. The bound context is restored to its previous value and the span is ended on completion of body evaluation. It is expected `body` provides a synchronous result, use [[async-span]], [[async-bound-span]], [[cf-span-binding]] or [[async-bound-cf-span]] instead for working with asynchronous functions. Does not use nor set the current context. `span-opts` is the same as for [[new-span!]]. See also [[with-span!]] and [[with-span-binding]].
(with-span! span-opts & body)Starts a new span, sets the current context to the new context containing
the span and evaluates body. The current context is restored to its
previous value and the span is ended on completion of body evaluation.
It is expected body provides a synchronous result, use async-span,
async-bound-span, cf-span-binding or async-bound-cf-span instead
for working with asynchronous functions. span-opts is the same as for
new-span!. See also with-bound-span! and with-span-binding.
Starts a new span, sets the current context to the new context containing the span and evaluates `body`. The current context is restored to its previous value and the span is ended on completion of body evaluation. It is expected `body` provides a synchronous result, use [[async-span]], [[async-bound-span]], [[cf-span-binding]] or [[async-bound-cf-span]] instead for working with asynchronous functions. `span-opts` is the same as for [[new-span!]]. See also [[with-bound-span!]] and [[with-span-binding]].
(with-span-binding [context span-opts] & body)Starts a new span, binds context to the new context containing the span
and evaluates body. The span is ended on completion of body evaluation.
It is expected body provides a synchronous result, use async-span,
async-bound-span, cf-span-binding or async-bound-cf-span instead
for working with asynchronous functions. Does not use nor set the current
context. span-opts is the same as for new-span!. See also
with-span! and with-bound-span!.
Starts a new span, binds `context` to the new context containing the span and evaluates `body`. The span is ended on completion of body evaluation. It is expected `body` provides a synchronous result, use [[async-span]], [[async-bound-span]], [[cf-span-binding]] or [[async-bound-cf-span]] instead for working with asynchronous functions. Does not use nor set the current context. `span-opts` is the same as for [[new-span!]]. See also [[with-span!]] and [[with-bound-span!]].
(wrap-bound-span handler)(wrap-bound-span handler span-opts-fn)Ring middleware to create a span around subsequent request processing.
span-opts-fn is a function which takes a request and returns span-opts
as for new-span!; default is to always use an internal span named
::wrap-span. For an asynchronous request, the context containing the new
span is set as the bound context. The bound context is restored to its
original value when the span ends.
Ring middleware to create a span around subsequent request processing. `span-opts-fn` is a function which takes a request and returns `span-opts` as for [[new-span!]]; default is to always use an internal span named `::wrap-span`. For an asynchronous request, the context containing the new span is set as the bound context. The bound context is restored to its original value when the span ends.
(wrap-span handler)(wrap-span handler span-opts-fn)(wrap-span handler span-opts-fn context-key)Ring middleware to create a span around subsequent request processing.
span-opts-fn is a function which takes a request and returns span-opts
as for new-span!; default is to always use an internal span named
::wrap-span. For an asynchronous request, the context containing the new
span is added to the request map with key context-key, default is
::wrap-span-context.
Ring middleware to create a span around subsequent request processing. `span-opts-fn` is a function which takes a request and returns `span-opts` as for [[new-span!]]; default is to always use an internal span named `::wrap-span`. For an asynchronous request, the context containing the new span is added to the request map with key `context-key`, default is `::wrap-span-context`.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |