steffan-westcott.clj-otel.api.trace.span — com.github.steffan-westcott/clj-otel-api 0.2.4

Functions for manipulating spans.

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:

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).

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:

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).

add-span-data! clj

(add-span-data! {:keys [context name status attributes event ex-data]
                 :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	Name to set span to.
: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.

: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	Event name (required).
:attributes	Map of attributes to attach to 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.

async-bound-span clj macro

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

async-span clj macro

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

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:

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 clj

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

get-span-context clj

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

get-tracer clj

(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).

new-span! clj

(new-span! {:keys [tracer name parent links attributes thread source span-kind
                   timestamp]
            :or {name ""
                 parent (context/dyn)
                 attributes {}
                 thread (Thread/currentThread)
                 source {}}})

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-span-binding and async-span instead of this function to manage the context and reliably end the span. Takes an options map 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	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).

noop-tracer clj

(noop-tracer)

Gets a no-op tracer.

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.

span-interceptor clj

(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 an options map for the new span, 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! clj macro

(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 a span options map, 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.

with-span! clj macro

(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 a span options map, 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.

with-span-binding clj macro

(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 a span options map, 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!.