steffan-westcott.clj-otel.api.metrics.instrument — com.github.steffan-westcott/clj-otel-api 0.2.7

Functions for creating instruments and recording measurements.

Counter clj protocol

Protocol for instruments of type :counter or :up-down-counter that take measurements synchronously.

add! clj

(add! counter delta)

Synchronously adds a delta to counter. delta is an option map as follows:

key	description
:context	Context to associate with delta (default: bound or current context).
:value	long or double value to add to counter (required). Must not be negative for :counter instruments.
:attributes	Map of attributes to attach to delta (default: no attributes).

Gauge clj protocol

Protocol for instruments of type :gauge that take measurements synchronously.

set! clj

(set! gauge measurement)

Synchronously sets a measurement in gauge. measurement is an option map as follows:

key	description
:context	Context to associate with measurement (default: bound or current context).
:value	long or double value to set in gauge (required).
:attributes	Map of attributes to attach to measurement (default: no attributes).

get-default-meter! clj

(get-default-meter!)

Returns the default meter if not nil. Otherwise, gets a meter using defaults and sets this as the default meter.

get-meter clj

(get-meter)

(get-meter {: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.metrics.Meter 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 meter from (default: global OpenTelemetry instance).

Histogram clj protocol

Protocol for instruments of type :histogram.

record! clj

(record! histogram measurement)

Synchronously records a measurement in histogram. measurement is an option map as follows:

key	description
:context	Context to associate with measurement (default: bound or current context).
:value	long or double value to record in histogram (required).
:attributes	Map of attributes to attach to measurement (default: no attributes).

instrument clj

(instrument opts)

(instrument {:keys [meter name instrument-type measurement-type unit description
                    explicit-bucket-boundaries-advice]
             :or {measurement-type :long}}
            observe)

Builds an instrument for taking measurements either synchronously or asynchronously (but not both).

The first parameter opts is an options map as follows:

key	description
:meter	io.opentelemetry.api.metrics.Meter used to create the instrument (default: default meter, as set by set-default-meter!; if no default meter has been set, one will be set with default config).
:name	Name of the instrument. Must be 63 or fewer characters including alphanumeric, _, ., -, and start with a letter (required).
:instrument-type	Type of instrument, one of :counter, :up-down-counter, :histogram or :gauge (required).
:measurement-type	Type of measurement value, either :long or :double (default: :long).
:unit	String describing the unit of measurement (default: no specified unit).
:description	String describing the instrument (default: no description).
:explicit-bucket-boundaries-advice	Seq of increasing longs or doubles, recommended bucket boundaries when building a histogram (default: no advice given).

The 1-arity form of instrument is for building instruments that take measurements synchronously. Counter, up-down counter, gauge and histogram instruments are supported. The built instrument is returned, and measurements are made with the add! (counter/up-down counter), set! (gauge) and record! (histogram) functions.

The 2-arity form of instrument is for building instruments that take measurements asynchronously. Counter, up-down counter and gauge instruments are supported. The second parameter observe is a 0-arity function that will be evaluated periodically to take measurements. To stop, evaluate .close on the AutoCloseable that instrument returns.

observe should return a single map, or a sequence of maps, as follows:

key	description
:value	long or double value to add or record (required).
:attributes	Map of attributes to attach to measurement (default: no attributes).

set-default-meter! clj

(set-default-meter! meter)

Sets the default io.opentelemetry.api.metrics.Meter instance used when creating instruments. Returns meter. See also get-meter.