Liking cljdoc? Tell your friends :D

steffan-westcott.clj-otel.api.trace.span

Functions for manipulating spans.

Functions for manipulating spans.
raw docstring

add-event!clj

(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!]].
sourceraw docstring

add-exception!clj

(add-exception! exception)
(add-exception! exception
                {:keys [context escaping? attributes]
                 :or {context (context/dyn) escaping? true attributes ex-data}})

Adds an event describing exception to a span. By default, exception data (as per ex-info) are added as attributes to the event. If the exception is escaping the span's scope, the span's status is also set to :error with the exception triage summary as the error description. May take an option map as follows:

keydescription
:contextContext containing span to add exception event to (default: bound or current context).
:escaping?If true, exception is escaping the span's scope; if false, exception is caught within the span's scope and not rethrown (default: true).
:attributesEither 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 `exception` to a span. By default, exception data
(as per `ex-info`) are added as attributes to the event. If the exception is
escaping the span's scope, the span's status is also 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).
|`:escaping?` | If true, exception is escaping the span's scope; if false, exception is caught within the span's scope and not rethrown (default: `true`).
|`: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`).
sourceraw docstring

add-interceptor-exception!clj

(add-interceptor-exception! e)
(add-interceptor-exception!
  e
  {:keys [context escaping? attributes]
   :or {context (context/dyn) escaping? true attributes ex-data}})

Adds an event describing an interceptor exception e to a span. Attributes identifying the interceptor and stage are added to the event. Also, by default exception data (as per ex-info) are added as attributes. If the exception is escaping the span's scope, the span's status is also set to :error with the wrapped exception triage summary as the error description. May take an option map as follows:

keydescription
:contextContext containing span to add exception event to (default: bound or current context)
:escaping?If true, exception is escaping the span's scope; if false, exception is caught within the span's scope and not rethrown (default: true).
:attributesEither 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` to a span. Attributes
identifying the interceptor and stage are added to the event. Also, by
default exception data (as per `ex-info`) are added as attributes. If the
exception is escaping the span's scope, the span's status is also 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)
|`:escaping?` | If true, exception is escaping the span's scope; if false, exception is caught within the span's scope and not rethrown (default: `true`).
|`: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`).
sourceraw docstring

add-span-data!clj

(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

keydescription
:contextContext containing span to add data to (default: bound or current context).
:nameString, keyword or symbol to set as the span name.
:statusOption map (see below) describing span status to set.
:attributesMap of additional attributes to merge in the span.
:eventOption map (see below) describing an event to add to the span.
:ex-dataOption map (see below) describing an exception event to add to the span.
:linksCollection 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

keydescription
:codeStatus code, either :ok or :error (required).
:descriptionStatus description string, only applicable with :error status code.

:event option map

keydescription
:nameString, keyword or symbol to set as the event name.
:attributesMap of attributes to attach to the event.
:timestampEvent timestamp, value is either an Instant or vector [amount ^TimeUnit unit].

:ex-data option map

keydescription
:exceptionException instance (required).
:escaping?Optional value, true if exception is escaping the span's scope, false if exception is caught within the span's scope and not rethrown.
:attributesMap 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).
|`:escaping?` | Optional value, true if exception is escaping the span's scope, false if exception is caught within the span's scope and not rethrown.
|`:attributes`| Map of additional attributes to attach to exception event.
sourceraw docstring

AsSpanOptscljprotocol

as-span-optsclj

(as-span-opts x)

Coerce to span options map for new-span!

Coerce to span options map for `new-span!`
source

async-bound-spancljmacro

(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!, except that the default values for :line, :file and :ns for the :source option map are set from the place async-bound-span is evaluated. 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!]], except that the default values
for `:line`, `:file` and `:ns` for the `:source` option map are set from the
place `async-bound-span` is evaluated. `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.
sourceraw docstring

async-spancljmacro

(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!, except that the default values for :line, :file and :ns for the :source option map are set from the place async-span is evaluated. 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!]], except that the default values
for `:line`, `:file` and `:ns` for the `:source` option map are set from the
place `async-span` is evaluated. `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.
sourceraw docstring

end-span!clj

(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:

keydescription
:contextContext containing span to end (default: bound or current context)
:timestampSpan 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).
sourceraw docstring

get-spanclj

(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.
sourceraw docstring

get-span-contextclj

(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.
sourceraw docstring

get-tracerclj

(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:

keydescription
:nameName of the instrumentation library, not the instrumented library e.g. "io.opentelemetry.contrib.mongodb" (default: See config.edn resource file).
:versionInstrumentation library version e.g. "1.0.0" (default: See config.edn resource file).
:schema-urlURL of OpenTelemetry schema used by this instrumentation library (default: See config.edn resource file).
:open-telemetryOpenTelemetry 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).
sourceraw docstring

new-span!clj

(new-span! span-opts)

Low level function 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 and async-bound-span instead of this function 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:

keydescription
:tracerio.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).
:nameString, keyword or symbol used for (qualified) span name (default: "").
:parentContext 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).
:linksCollection 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).
:attributesMap of additional attributes for the span (default: no attributes).
:threadThread 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).
:sourceMap describing source code where span is started. Optional keys are :fn, :ns, :line and :file (default: {}).
:span-kindSpan kind, one of :internal, :server, :client, :producer, :consumer (default: :internal). See also SpanKind.
:timestampStart 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 function 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]] and [[async-bound-span]] instead of this function 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`, `:ns`, `:line` and `:file` (default: {}).
|`: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.
sourceraw docstring

noop-tracerclj

(noop-tracer)

Gets a no-op tracer.

Gets a no-op tracer.
sourceraw docstring

set-default-tracer!clj

(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]].
sourceraw docstring

span-interceptorclj

(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.
sourceraw docstring

with-bound-span!cljmacro

(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 or async-bound-span instead for working with asynchronous functions. Does not use nor set the current context.

span-opts is the same as for new-span!, except that the default values for :line, :file and :ns for the :source option map are set from the place with-bound-span! is evaluated. 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]] or
[[async-bound-span]] instead for working with asynchronous functions. Does
not use nor set the current context.

`span-opts` is the same as for [[new-span!]], except that the default values
for `:line`, `:file` and `:ns` for the `:source` option map are set from the
place `with-bound-span!` is evaluated. See also [[with-span!]] and
[[with-span-binding]].
sourceraw docstring

with-span!cljmacro

(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 or async-bound-span instead for working with asynchronous functions.

span-opts is the same as for new-span!, except that the default values for :line, :file and :ns for the :source option map are set from the place with-span! is evaluated. 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]]
or [[async-bound-span]] instead for working with asynchronous functions.

`span-opts` is the same as for [[new-span!]], except that the default values
for `:line`, `:file` and `:ns` for the `:source` option map are set from the
place `with-span!` is evaluated. See also [[with-bound-span!]] and
[[with-span-binding]].
sourceraw docstring

with-span-bindingcljmacro

(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 or async-bound-span instead for working with asynchronous functions. Does not use nor set the current context.

span-opts is the same as for new-span!, except that the default values for :line, :file and :ns for the :source option map are set from the place with-span-binding is evaluated. 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]]
or [[async-bound-span]] instead for working with asynchronous functions. Does
not use nor set the current context.

`span-opts` is the same as for [[new-span!]], except that the default values
for `:line`, `:file` and `:ns` for the `:source` option map are set from the
place `with-span-binding` is evaluated. See also [[with-span!]] and
[[with-bound-span!]].
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close