prometheus_boolean.md

Module prometheus_boolean

• Description
• Function Index
• Function Details

Boolean metric, to report booleans and flags.

Behaviours: prometheus_collector, prometheus_metric.

Description

Boolean is a non-standard metric that uses untyped metric underneath.

A Boolean is typically used as a flag i.e. enabled/disabled, online/offline.

Example:

  -module(my_fuse_instrumenter).
  -export([setup/0,
           fuse_event/2]).
  setup() ->
    prometheus_boolean:declare([{name, app_fuse_state},
                                {labels, [name]}, %% fuse name
                                {help, "State of various app fuses."}]),
  fuse_event(Fuse, Event) ->
    case Event of
      ok -> prometheus_boolean:set(app_fuse_state, [Fuse], true);
      blown -> prometheus_boolean:set(app_fuse_state, [Fuse], false);
      _ -> ok
    end.

Function Index

declare/1	Creates a boolean using Spec.
deregister/1	Equivalent to deregister(default, Name).
deregister/2	Removes all boolean series with name Name and removes Metric Family from Registry.
new/1	Creates a boolean using Spec.
remove/1	Equivalent to remove(default, Name, []).
remove/2	Equivalent to remove(default, Name, LabelValues).
remove/3	Removes boolean series identified by Registry, Name and LabelValues.
reset/1	Equivalent to reset(default, Name, []).
reset/2	Equivalent to reset(default, Name, LabelValues).
reset/3	Resets the value of the boolean identified by Registry, Name and LabelValues.
set/2	Equivalent to set(default, Name, [], Value).
set/3	Equivalent to set(default, Name, LabelValues, Value).
set/4	Sets the boolean identified by Registry, Name and LabelValues to Value.
toggle/1	Equivalent to toggle(default, Name, []).
toggle/2	Equivalent to toggle(default, Name, LabelValues, Value).
toggle/3	Toggles the boolean identified by Registry, Name and LabelValues.
value/1	Equivalent to value(default, Name, []).
value/2	Equivalent to value(default, Name, LabelValues).
value/3	Returns the value of the boolean identified by Registry, Name and LabelValues.
values/2

Function Details

declare/1

declare(Spec) -> any()

Creates a boolean using Spec. If a boolean with the same Spec exists returns false.

Raises {missing_metric_spec_key, Key, Spec} error if required Spec key is missing.
Raises {invalid_metric_name, Name, Message} error if metric Name is invalid.
Raises {invalid_metric_help, Help, Message} error if metric Help is invalid.
Raises {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
Raises {invalid_label_name, Name, Message} error if Name isn't a valid label name.

deregister/1

deregister(Name) -> any()

Equivalent to deregister(default, Name).

deregister/2

deregister(Registry, Name) -> any()

Removes all boolean series with name Name and removes Metric Family from Registry.

After this call new/1 for Name and Registry will succeed.

Returns {true, _} if Name was a registered boolean. Otherwise returns {true, _}.

new/1

new(Spec) -> any()

Creates a boolean using Spec.

Raises {missing_metric_spec_key, Key, Spec} error if required Spec key is missing.
Raises {invalid_metric_name, Name, Message} error if metric Name is invalid.
Raises {invalid_metric_help, Help, Message} error if metric Help is invalid.
Raises {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
Raises {invalid_label_name, Name, Message} error if Name isn't a valid label name.
Raises {mf_already_exists, {Registry, Name}, Message} error if a boolean with the same Spec already exists.

remove/1

remove(Name) -> any()

Equivalent to remove(default, Name, []).

remove/2

remove(Name, LabelValues) -> any()

Equivalent to remove(default, Name, LabelValues).

remove/3

remove(Registry, Name, LabelValues) -> any()

Removes boolean series identified by Registry, Name and LabelValues.

Raises {unknown_metric, Registry, Name} error if boolean with name Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

reset/1

reset(Name) -> any()

Equivalent to reset(default, Name, []).

reset/2

reset(Name, LabelValues) -> any()

Equivalent to reset(default, Name, LabelValues).

reset/3

reset(Registry, Name, LabelValues) -> any()

Resets the value of the boolean identified by Registry, Name and LabelValues.

Raises {unknown_metric, Registry, Name} error if boolean with name Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

set/2

set(Name, Value) -> any()

Equivalent to set(default, Name, [], Value).

set/3

set(Name, LabelValues, Value) -> any()

Equivalent to set(default, Name, LabelValues, Value).

set/4

set(Registry, Name, LabelValues, Value0) -> any()

Sets the boolean identified by Registry, Name and LabelValues to Value.

Valid "truthy" values:

• true;
• false;
• 0 -> false;
• number > 0 -> true;
• [] -> false
• non-empty list -> true;
• undefined -> undefined

Other values will generate invalid_value error.

Raises {invalid_value, Value, Message} if Value isn't a boolean or undefined.
Raises {unknown_metric, Registry, Name} error if boolean with named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

toggle/1

toggle(Name) -> any()

Equivalent to toggle(default, Name, []).

toggle/2

toggle(Name, LabelValues) -> any()

Equivalent to toggle(default, Name, LabelValues, Value).

toggle/3

toggle(Registry, Name, LabelValues) -> any()

Toggles the boolean identified by Registry, Name and LabelValues.

If boolean set to undefined, it can't be toggled.

Raises {invalid_value, undefined, Message} if boolean is undefined.
Raises {unknown_metric, Registry, Name} error if boolean with named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

value/1

value(Name) -> any()

Equivalent to value(default, Name, []).

value/2

value(Name, LabelValues) -> any()

Equivalent to value(default, Name, LabelValues).

value/3

value(Registry, Name, LabelValues) -> any()

Returns the value of the boolean identified by Registry, Name and LabelValues. If there is no boolean for LabelValues, returns undefined.

Raises {unknown_metric, Registry, Name} error if boolean named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

values/2

values(Registry, Name) -> any()