deigma (deigma v1.3.0)

Continuous event sampler for Erlang/OTP and Elixir.

deigma samples reported events within continuous one-second windows, steadily adjusting the sampling percentage so the events that seep through stay representative of what's happening in the system while honouring rate limits. The sampling percentage is exposed alongside each event so downstream consumers can reason about the original population. See the README for an overview, configuration and examples.

Summary

Types

ask_opt()

An option accepted by ask/3 and ask/4.

Functions

ask(Category, EventType)

Asks Category to sample an EventType event.

ask/3

Asks Category to sample an EventType event using a custom function or overridden options.

ask(Category, EventType, EventFun, Opts)

Asks Category to sample an EventType event using a custom function and overridden options.

child_spec(Category)

Returns a child spec for a deigma instance named Category, for launching it under your own supervisor.

start(Category)

Starts a deigma instance named Category under the deigma application.

start_link(Category)

Starts a deigma instance named Category under your own supervisor.

stop(Category)

Stops the deigma instance named Category running under the deigma application.

Types

ask_opt()

-type ask_opt() :: {max_rate, non_neg_integer() | infinity}.

An option accepted by ask/3 and ask/4.

Functions

ask(Category, EventType)

-spec ask(Category, EventType) -> {Decision, SamplingPercentage}
             when
                 Category :: atom(),
                 EventType :: term(),
                 Decision :: sample | drop,
                 SamplingPercentage :: float().

Asks Category to sample an EventType event.

Category must be an atom and correspond to an existing deigma instance.
EventType can be any term.

Returns:

{sample, SamplingPercentage} if the event was sampled;
{drop, SamplingPercentage} if the event was dropped.

SamplingPercentage is a floating point number between 0.0 and 1.0 representing the percentage of events that were sampled during the last 1000 milliseconds, including the event reported just now.

See also ask/3 and ask/4.

ask/3

-spec ask(Category, EventType, EventFun | Opts) -> {Decision, SamplingPercentage} | EventFunResult
             when
                 Category :: atom(),
                 EventType :: term(),
                 EventFun :: fun((Timestamp, Decision, SamplingPercentage) -> EventFunResult),
                 Timestamp :: integer(),
                 SamplingPercentage :: float(),
                 Decision :: sample | drop,
                 EventFunResult :: term(),
                 Opts :: [ask_opt()].

Asks Category to sample an EventType event using a custom function or overridden options.

Category must be an atom and correspond to an existing deigma instance.
EventType can be any term.
EventFun is a function called with (Timestamp, Decision, SamplingPercentage):
- Timestamp is the monotonic timestamp, in native units, at which the event was registered;
- Decision is either sample or drop;
- SamplingPercentage is a float between 0.0 and 1.0 (see ask/2).
It runs from within the event window for EventType, so it can be used to fulfil serialisation constraints — at the expense of possibly turning the event window into a bottleneck.
Opts is a list of ask_opt/0 values:
- {max_rate, MaxRate}: don't sample more than MaxRate EventType events per second (defaults to 100).

When called with EventFun, returns (or throws) whatever EventFun returns (or throws). When called with Opts, returns the same as ask/2.

See also ask/2 and ask/4.

ask(Category, EventType, EventFun, Opts)

-spec ask(Category, EventType, EventFun, Opts) -> EventFunResult
             when
                 Category :: atom(),
                 EventType :: term(),
                 EventFun :: fun((Timestamp, Decision, SamplingPercentage) -> EventFunResult),
                 Timestamp :: integer(),
                 SamplingPercentage :: float(),
                 Decision :: sample | drop,
                 EventFunResult :: term(),
                 Opts :: [ask_opt()].

Asks Category to sample an EventType event using a custom function and overridden options.

The arguments are as described in ask/3. Returns (or throws) whatever EventFun returns (or throws).

See also ask/2 and ask/3.

child_spec(Category)

-spec child_spec(Category) -> supervisor:child_spec() when Category :: atom().

Returns a child spec for a deigma instance named Category, for launching it under your own supervisor.

Category must be an atom.

See also start_link/1 and start/1.

start(Category)

-spec start(Category) -> {ok, pid()} | {error, term()} when Category :: atom().

Starts a deigma instance named Category under the deigma application.

Category must be an atom.

See also stop/1, start_link/1 and child_spec/1.

start_link(Category)

-spec start_link(Category) -> {ok, pid()} | {error, term()} when Category :: atom().

Starts a deigma instance named Category under your own supervisor.

Category must be an atom.

See also child_spec/1 and start/1.

stop(Category)

-spec stop(Category) -> ok | {error, not_started} when Category :: atom().

Stops the deigma instance named Category running under the deigma application.

Category must be an atom.

See also start/1.