prometheus_boolean (prometheus v6.0.0)

View Source

Boolean metric, to report booleans and flags.

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.

Summary

Functions

declare(Spec)

Creates a boolean using Spec.

deregister(Name)

Equivalent to deregister(default, Name).

deregister(Registry, Name)

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

new(Spec)

Creates a boolean using Spec.

remove(Name)

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

remove(Name, LabelValues)

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

Removes boolean series identified by Registry, Name and LabelValues.

reset(Name)

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

reset(Name, LabelValues)

Equivalent to reset(default, Name, LabelValues).

reset(Registry, Name, LabelValues)

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

set(Name, Value)

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

set(Name, LabelValues, Value)

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

set(Registry, Name, LabelValues, Value)

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

toggle(Name)

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

toggle(Name, LabelValues)

Equivalent to toggle(default, Name, LabelValues).

toggle(Registry, Name, LabelValues)

Toggles the boolean identified by Registry, Name and LabelValues.

value(Name)

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

value(Name, LabelValues)

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

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

values(Registry, Name)

Functions

declare(Spec)

-spec declare(prometheus_metric:spec()) -> boolean().

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.
  • {invalid_metric_name, Name, Message} error if metric Name is invalid.
  • {invalid_metric_help, Help, Message} error if metric Help is invalid.
  • {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
  • {invalid_label_name, Name, Message} error if Name isn't a valid label name.

deregister(Name)

-spec deregister(prometheus_metric:name()) -> {boolean(), boolean()}.

Equivalent to deregister(default, Name).

deregister(Registry, Name)

-spec deregister(prometheus_registry:registry(), prometheus_metric:name()) -> {boolean(), boolean()}.

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

-spec new(prometheus_metric:spec()) -> ok.

Creates a boolean using Spec.

Raises:

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

remove(Name)

-spec remove(prometheus_metric:name()) -> boolean().

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

remove(Name, LabelValues)

-spec remove(prometheus_metric:name(), prometheus_metric:label_values()) -> boolean().

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

-spec remove(Registry, Name, LabelValues) -> boolean()
                when
                    Registry :: prometheus_registry:registry(),
                    Name :: prometheus_metric:name(),
                    LabelValues :: prometheus_metric:label_values().

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.
  • {invalid_metric_arity, Present, Expected} error if labels count mismatch.

reset(Name)

-spec reset(prometheus_metric:name()) -> boolean().

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

reset(Name, LabelValues)

-spec reset(prometheus_metric:name(), prometheus_metric:label_values()) -> boolean().

Equivalent to reset(default, Name, LabelValues).

reset(Registry, Name, LabelValues)

-spec reset(Registry, Name, LabelValues) -> boolean()
               when
                   Registry :: prometheus_registry:registry(),
                   Name :: prometheus_metric:name(),
                   LabelValues :: prometheus_metric:label_values().

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.
  • {invalid_metric_arity, Present, Expected} error if labels count mismatch.

set(Name, Value)

-spec set(prometheus_metric:name(), prometheus:prometheus_boolean()) -> ok.

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

set(Name, LabelValues, Value)

-spec set(Name, LabelValues, Value) -> ok
             when
                 Name :: prometheus_metric:name(),
                 LabelValues :: prometheus_metric:label_values(),
                 Value :: prometheus:prometheus_boolean().

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

set(Registry, Name, LabelValues, Value)

-spec set(Registry, Name, LabelValues, Value) -> ok
             when
                 Registry :: prometheus_registry:registry(),
                 Name :: prometheus_metric:name(),
                 LabelValues :: prometheus_metric:label_values(),
                 Value :: prometheus:prometheus_boolean().

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.
  • {unknown_metric, Registry, Name} error if boolean with named Name can't be found in Registry.
  • {invalid_metric_arity, Present, Expected} error if labels count mismatch.

toggle(Name)

-spec toggle(prometheus_metric:name()) -> ok.

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

toggle(Name, LabelValues)

-spec toggle(prometheus_metric:name(), prometheus_metric:label_values()) -> ok.

Equivalent to toggle(default, Name, LabelValues).

toggle(Registry, Name, LabelValues)

-spec toggle(Registry, Name, LabelValues) -> ok
                when
                    Registry :: prometheus_registry:registry(),
                    Name :: prometheus_metric:name(),
                    LabelValues :: prometheus_metric:label_values().

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.
  • {unknown_metric, Registry, Name} error if boolean with named Name can't be found in Registry.
  • {invalid_metric_arity, Present, Expected} error if labels count mismatch.

value(Name)

-spec value(prometheus_metric:name()) -> boolean() | undefined.

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

value(Name, LabelValues)

-spec value(prometheus_metric:name(), prometheus_metric:label_values()) -> boolean() | undefined.

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

-spec value(Registry, Name, LabelValues) -> boolean() | undefined
               when
                   Registry :: prometheus_registry:registry(),
                   Name :: prometheus_metric:name(),
                   LabelValues :: prometheus_metric:label_values().

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.
  • {invalid_metric_arity, Present, Expected} error if labels count mismatch.

values(Registry, Name)

-spec values(prometheus_registry:registry(), prometheus_metric:name()) -> [{list(), boolean()}].