# &adminguide;

## Overview

This module generates suitable metrics for a Prometheus monitoring platform.

It answers Prometheus pull requests (HTTP requests to /metrics URL).

The module generates metrics based on &kamailio; statistics, and also the user can create his own metrics (currently counters, gauges and histograms).

The xHTTP_PROM module uses the xHTTP module to handle HTTP requests. Read the documentation of the xHTTP module for more details.

NOTE: This module is based on xHTTP_RPC one.

IMPORTANT: This module uses private memory to generate HTTP responses, and shared memory to store all the metrics. Remember to increase size of private and shared memory if you use a huge amount of metrics.

Prometheus URLs:

- https://prometheus.io/
- https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels
- https://prometheus.io/docs/instrumenting/exposition_formats/

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- xhttp -- xHTTP.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None

## Parameters

### `xhttp_prom_buf_size` (integer)

Specifies the maximum length of the buffer (in bytes) used to write the metric reply information in order to build the HTML response.

Default value is 0 (auto set to 1/3 of the size of the configured pkg mem).

#### Set `xhttp_prom_buf_size` parameter

    ...
    modparam("xhttp_prom", "xhttp_prom_buf_size", 1024)
    ...

### `xhttp_prom_timeout` (integer)

Specifies a timeout in minutes. A metric not used during this timeout is automatically deleted. Listing metrics does not count as using them.

If set to 0 timeout is disabled. Negative values are not allowed.

Default value is 60 minutes.

#### Set `xhttp_prom_timeout` parameter

    ...
    # Set timeout to 10 hours
    modparam("xhttp_prom", "xhttp_prom_timeout", 600)
    ...

### `xhttp_prom_stats` (str)

Specifies which internal statistics from &kamailio; to show.

Possible values:

- all - Show whole &kamailio; statistics

- group_name: - Show all statistics for a group

- statistic_name - Show a specific statistic. It automatically finds the group.

Default value is "", meaning do not display any &kamailio; statistics.

IMPORTANT: &kamailio; internal statistics are parsed to convert - into _, so they accomplish with Prometheus guidelines for metric names. https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels User generated statistics and label names are not parsed.

#### Set `xhttp_prom_stats` parameter

    ...
    # show all kamailio statistics.
    modparam("xhttp_prom", "xhttp_prom_stats", "all")

    # show statistics for sl group.
    modparam("xhttp_prom", "xhttp_prom_stats", "sl:")

    # Show statistic for 200_replies in sl group.
    modparam("xhttp_prom", "xhttp_prom_stats", "200_replies")

    # Do not display internal &kamailio; statistics. This is the default option.
    modparam("xhttp_prom", "xhttp_prom_stats", "")
    ...

### `xhttp_prom_pkg_stats` (integer)

Enable or disable internal &kamailio; pkg memory statistics.

If not 0, pkg memory statistics will be displayed.

Default value is 0 (no pkg memory statistics).

#### Set `xhttp_prom_pkg_stats` parameter

    ...
    # enable pkg stats
    modparam("xhttp_prom", "xhttp_prom_pkg_stats", 1)
    ...

### `xhttp_prom_uptime_stat` (integer)

Enable or disable &kamailio; uptime statistic.

If not 0, uptime statistic will be displayed.

Default value is 0 (no uptime statistic).

#### Set `xhttp_prom_uptime_stat` parameter

    ...
    # enable uptime statistic
    modparam("xhttp_prom", "xhttp_prom_uptime_stat", 1)
    ...

### `xhttp_prom_beginning` (str)

Specifies beginning of string the metrics are build with.

It defaults to "kamailio_", so if not specified every metric will start with "kamailio_".

Void string "" is also allowed, meaning no prefix string for every metric name.

#### Set `xhttp_prom_beginning` parameter

    ...
    # All metrics will start with "my_metric_".
    modparam("xhttp_prom", "xhttp_prom_beginning", "my_metric_")

    # No string at the beginning.
    modparam("xhttp_prom", "xhttp_prom_beginning", "");
    ...

### `xhttp_prom_metadata_flags` (integer)

Flags to enable Prometheus metadata lines in the output. The flags are defined as a bitmask on an integer value. Bits have the following meaning:

- 1 - include TYPE metadata string for user defined metrics. Metrics generated from Kamailio statistics are untyped and can't have TYPE metadata.

  #### `xhttp_prom_metadata_flags` TYPE example

      # Enable TYPE metadata and define some metrics.
      modparam("xhttp_prom", "xhttp_prom_beginning", "my_metric_")
      modparam("xhttp_prom", "xhttp_prom_metadata_flags", 1)
      modparam("xhttp_prom", "prom_counter", "name=cnt01")
      modparam("xhttp_prom", "prom_gauge", "name=gg01")
      modparam("xhttp_prom", "prom_histogram", "name=histo01")

      In this case the generated Prometheus output may look something like this:

      # TYPE my_metric_cnt01 counter
      my_metric_cnt01 0
      # TYPE my_metric_gg01 gauge
      my_metric_gg01 0
      # TYPE my_metric_hist01 histogram
      my_metric_hist01_sum 0.0
      my_metric_hist01_count 0

- 2 - include HELP metadata string for user defined metrics. HELP metadata for a metric will only be generated if the help string is defined in metric specification. See description of the help attribute in `prom_counter`.

  #### `xhttp_prom_metadata_flags` HELP example

      # Enable TYPE and HELP metadata and define some metrics (with and without HELP).
      modparam("xhttp_prom", "xhttp_prom_beginning", "my_metric_")
      modparam("xhttp_prom", "xhttp_prom_metadata_flags", 3)
      modparam("xhttp_prom", "prom_counter", "name=cnt01")
      modparam("xhttp_prom", "prom_gauge", "name=gg01; help='Some help string for the gauge'")

      In this case the generated Prometheus output may look something like this:

      # TYPE my_metric_cnt01 counter
      my_metric_cnt01 0
      # HELP my_metric_gg01 Some help string for the gauge
      # TYPE my_metric_gg01 gauge
      my_metric_gg01 0

Default value is 0 (no metadata in the output).

#### Set `xhttp_prom_metadata_flags` parameter

    ...
    # There will be no metadata in the output (it's the default)
    modparam("xhttp_prom", "xhttp_prom_metadata_flags", 0)

    # Only the TYPE metadata entry will be included in the output.
    modparam("xhttp_prom", "xhttp_prom_metadata_flags", 1)

    # If there's HELP metadata defined for the metric, it will be included in the output.
    modparam("xhttp_prom", "xhttp_prom_metadata_flags", 2)

    # Both TYPE and HELP metadata lines are allowed in the output.
    modparam("xhttp_prom", "xhttp_prom_metadata_flags", 3)
    ...

### `xhttp_prom_tags` (str)

Specifies additional tags for the metrics. These can be useful for evaluating the metrics afterwards.

It defaults to an empty string which means that no metric tags will be added.

A comma separated list of key-value pairs connected by equal signs.

#### Set `xhttp_prom_tags` parameter

    ...
    # Add one tag to every metric
    modparam("xhttp_prom", "xhttp_prom_tags", "host_job=foo")

    # Add multiple tags to every metric
    modparam("xhttp_prom", "xhttp_prom_tags", "tag_bar=foo,host_job=wurst");
    ...

### `prom_counter` (str)

Create a counter metric.

This function declares a counter but the actual counter is only created when using it (by adding to or resetting it)

It takes a list of attribute=value separated by semicolon, the attributes can be name and label.

- name - name of the counter. This attribute is mandatory. It is used to generate the metric name. Each name is unique, no metric shall repeat a name.

- label - names of labels in the counter. Optional. Only one label parameter at most allowed in counters. Each label name is separated by : without spaces. At most only three label names allowed in each label parameter.

  #### `prom_counter` label example

      # Create two labels called method and handler
      label = method:handler
      This would generate  {method="whatever", handler="whatever2"} when building
      the metric.

- help - HELP metadata string for the counter. Optional. If HELP string is defined for the metric and metadata generation is enabled (see `xhttp_prom_metadata_flags` parameter), then it will be included in the generated output. Be careful using special characters in the help string. Prometheus requires some characters in the HELP to be quoted, but this module doesn't process the provided HELP string in any way. The provided HELP string will be included in the output as is.

#### Set `prom_counter` parameter

    ...

    # Create cnt_first counter with no labels.
    modparam("xhttp_prom", "prom_counter", "name=cnt_first;");

    # Create cnt_second counter with no labels.
    modparam("xhttp_prom", "prom_counter", "name=cnt_second;");

    # Create cnt_third counter with label method
    modparam("xhttp_prom", "prom_counter", "name=cnt_third; label=method");

    # Create cnt_fourth counter with label method and HELP string
    modparam("xhttp_prom", "prom_counter", "name=cnt_fourth; label=method; help='Total number of SIP requests'");

    These lines declare the counter but the actual metric will be created when
    using it by prom_counter_inc or prom_counter_reset functions.

    ...

### `prom_gauge` (str)

Create a gauge metric.

This function declares the gauge but the actual gauge is only created when using it (by setting or resetting it)

It takes a list of attribute=value separated by semicolon, the attributes can be name and value.

- name - name of the gauge. This attribute is mandatory. It is used to generate the metric name. Each name is unique, no metric shall repeat a name.

- label - names of labels in the gauge. Optional. Only one label parameter at most allowed in gauges. Each label name is separated by : without spaces. At most only three label names allowed inside each label parameter.

  #### `prom_gauge` label example

      # Create two labels called method and handler
      label = method:handler
      This would generate  {method="whatever", handler="whatever2"} when building
      the metric.

- help - HELP metadata string for the gauge. Optional. See description for the help attribute in `prom_counter` parameter. Everything is the same for `prom_gauge` help.

#### Set `prom_gauge` parameter

    ...

    # Create gg_first gauge with no labels
    modparam("xhttp_prom", "prom_gauge", "name=gg_first;");

    # Create gg_second gauge with no labels
    modparam("xhttp_prom", "prom_gauge", "name=gg_second;");

    # Create gg_third gauge with two labels method and handler:
    modparam("xhttp_prom", "prom_gauge", "name=gg_third; label=method:handler;");

    ...

### `prom_histogram` (str)

Create a histogram metric.

This function declares a histogram but the actual histogram is only created when observing it.

It takes a list of attribute=value separated by semicolon, the attributes can be name, label and buckets.

- name - name of the histogram. This attribute is mandatory. It is used to generate the metric name. Each name is unique, no metric shall repeat a name.

- label - names of labels in the histogram. Optional. Only one label parameter at most allowed in histograms. Each label name is separated by : without spaces. At most only three label names allowed in each label parameter.

  #### `prom_histogram` label example

      # Create two labels called method and handler
      label = method:handler
      This would generate  {method="whatever", handler="whatever2"} when building
      the metric.

- buckets - specifies upper bounds for buckets in the histogram. This attribute is optional.

  Bucket values are separated by ":". Each value has to be a number.

  "+Inf" upper bucket is always automatically included.

  At least one bucket value is needed (other than +Inf).

  Every bucket value has to increase in the list.

  If no buckets specified, default bucket list is set to these values:

  [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]

- help - HELP metadata string for the histogram. Optional. See description for the help attribute in `prom_counter` parameter. Everything is the same for `prom_histogram` help.

#### Set `prom_histogram` parameter

    ...

    # Create my_histo histogram with no labels and default buckets.
    modparam("xhttp_prom", "prom_histogram", "name=my_histo;");

    # Create second_histo histogram with one label and default buckets.
    # modparam("xhttp_prom", "prom_histogram", "name=second_histo; label=my_lbl");

    # Create a histogram with no labels and buckets 3.1, 5, 6.5
    modparam("xhttp_prom", "prom_histogram", "name=histo_third; buckets=3.1:5:6.5");

    # Create a histogram with a label and buckets 3.1, 5, 6.5
    modparam("xhttp_prom", "prom_histogram", "name=histo_fourth; label=lbl; buckets=3.1:5:6.5");

    These lines declare the histogram but the actual metric will be created when
    using it by prom_histogram_observe function.

    ...

## Functions

### `prom_counter_reset(name, l0, l1, l2)`

Get a counter based on its name and labels and reset its value to 0. Name parameter is mandatory. Values of labels are optional (from none up to three). Name in prom_counter_reset has to match same name in prom_counter parameter. Number of labels in prom_counter_reset has to match number of labels in prom_counter parameter. First time a counter is used with this reset function the counter is created if it does not exist already.

This function accepts pseudovariables on its parameters.

Available via KEMI framework as counter_reset_l0, counter_reset_l1, counter_reset_l2 and counter_reset_l3.

#### `prom_counter_reset` usage

    ...
    # Definition of counter with prom_counter with labels method and IP
    modparam("xhttp_prom", "prom_counter", "name=cnt01; label=method:IP;");
    ...
    # Reset cnt01 counter with two values "push" and "192.168.0.1" in labels to zero.
    # First time we execute this function the counter will be created.
    prom_counter_reset("cnt01", "push", "192.168.0.1");
    ...
    # A metric like this will appear when listing this counter:
    kamailio_cnt01 {method="push", IP="192.168.0.1"} 0 1234567890
    ...

### `prom_gauge_reset(name, l0, l1, l2)`

Get a gauge based on its name and labels and reset its value to 0. Name parameter is mandatory. Values of labels are optional (from none up to three). Name in prom_gauge_reset has to match same name in prom_gauge parameter. Number of labels in prom_gauge_reset has to match number of labels in prom_gauge parameter. First time a gauge is used with this reset function the gauge is created if it does not exist already.

This function accepts pseudovariables on its parameters.

Available via KEMI framework as gauge_reset_l0, gauge_reset_l1, gauge_reset_l2 and gauge_reset_l3.

#### `prom_gauge_reset` usage

    ...
    # Definition of gauge with prom_gauge with labels method and IP
    modparam("xhttp_prom", "prom_gauge", "name=cnt01; label=method:IP;");
    ...
    # Reset cnt01 gauge with two values "push" and "192.168.0.1" in labels to zero.
    # First time we execute this function the gauge will be created.
    prom_gauge_reset("cnt01", "push", "192.168.0.1");
    ...
    # A metric like this will appear when listing this gauge:
    kamailio_cnt01 {method="push", IP="192.168.0.1"} 0 1234567890
    ...

### `prom_counter_inc(name, number, l0, l1, l2)`

Get a counter identified by its name and labels and increase its value by a number. If counter does not exist it creates the counter, initializes it to zero and adds the number.

Name is mandatory, number is mandatory. Number has to be positive or zero (integer). l0, l1, l2 are values of labels and are optional.

name value and number of labels have to match a previous counter definition with prom_counter.

This function accepts pseudovariables on its parameters.

Available via KEMI framework as counter_inc_l0, counter_inc_l1, counter_inc_l2 and counter_inc_l3.

#### `prom_counter_inc` usage

    ...
    # Definition of cnt01 counter with no labels.
    modparam("xhttp_prom", "prom_counter", "name=cnt01;");
    ...
    # Add 10 to value of cnt01 counter (with no labels) If counter does not exist it gets created.
    prom_counter_inc("cnt01", "10");
    ...

    # Definition of cnt02 counter with two labels method and IP
    modparam("xhttp_prom", "prom_counter", "name=cnt02; label=method:IP;");
    ...
    # Add 15 to value of cnt02 counter with labels method and IP. It creates the counter if it does not exist.
    prom_counter_inc("cnt02", "15", "push", "192.168.0.1");
    # When listed the metric it will show a line like this:
    kamailio_cnt02 {method="push", IP="192.168.0.1"} 15 1234567890
    ...

### `prom_gauge_inc(name, number, l0, l1, l2)`

Get a gauge identified by its name and labels and increase (or decrease, if amount is negative) its value by a given amount. If gauge does not exist it creates the gauge and assigns the value to it.

Name and number are mandatory. Number is a string that will be parsed as a float. l0, l1, l2 are values of labels and are optional.

name value and number of labels have to match a previous gauge definition with prom_gauge.

This function accepts pseudovariables on its parameters.

Available via KEMI framework as gauge_set_l0, gauge_set_l1, gauge_set_l2 and gauge_set_l3.

#### `prom_gauge_inc` usage

    ...
    # Definition of gg01 gauge with no labels.
    modparam("xhttp_prom", "prom_gauge", "name=gg01;");
    ...
    # Increase the value of gg01 by 12.5 (with no labels).
    # Gauges start at zero and after the update gg01 will have value 12.5.
    prom_gauge_inc("gg01", "12.5");
    ...
    # Decrease the value of gg01 by 22.5.
    # After the update gg01 will have value -10.
    prom_gauge_inc("gg01", "-22.5");
    ...

### `prom_gauge_set(name, number, l0, l1, l2)`

Get a gauge identified by its name and labels and set its value to a number. If gauge does not exist it creates the gauge and assigns the value to it.

Name is mandatory, number is mandatory. Number is a string that will be parsed as a float. l0, l1, l2 are values of labels and are optional.

name value and number of labels have to match a previous gauge definition with prom_gauge.

This function accepts pseudovariables on its parameters.

Available via KEMI framework as gauge_set_l0, gauge_set_l1, gauge_set_l2 and gauge_set_l3.

#### `prom_gauge_set` usage

    ...
    # Definition of gg01 gauge with no labels.
    modparam("xhttp_prom", "prom_gauge", "name=gg01;");
    ...
    # Assign -12.5 to value of gg01 gauge (with no labels) If gauge does not exist it gets created
    prom_gauge_set("gg01", "-12.5");
    ...

    # Definition of gg02 gauge with two labels method and IP
    modparam("xhttp_prom", "prom_gauge", "name=gg02; label=method:IP;");
    ...
    # Assign 2.8 to value of gg02 gauge with labels method and IP. It creates the gauge if it does not exist.
    prom_gauge_set("gg02", "2.8", "push", "192.168.0.1");
    # When listed the metric it will show a line like this:
    kamailio_gg02 {method="push", IP="192.168.0.1"} 2.8 1234567890
    ...

### `prom_histogram_observe(name, number, l0, l1, l2)`

Get a histogram identified by its name and labels and observe a value in it. If histogram does not exist it creates the histogram and accumulate the value in its buckets, counter and sum.

Name is mandatory, number is mandatory. Number is a string that will be parsed as a float. l0, l1, l2 are values of labels and are optional.

name value and number of labels have to match a previous histogram definition with prom_histogram.

This function accepts pseudovariables on its parameters.

Available via KEMI framework as histogram_observe_l0, histogram_observe_l1, histogram_observe_l2 and histogram_observe_l3.

#### `prom_histogram_observe` usage

    ...
    # Definition of hist01 histogram with no labels and default buckets.
    modparam("xhttp_prom", "prom_histogram", "name=hist01;");
    ...
    # Observe -12.5 value in hist01 histogram (with no labels). If histogram does not exist it gets created:
    prom_histogram_observe("hist01", "-12.5");
    ...

    # Definition of hist02 histogram with two labels method and IP and buckets [2.3, 5.8, +Inf]:
    modparam("xhttp_prom", "prom_histogram", "name=hist02; label=method:IP; buckets=2.3:5.8");
    ...
    # Observe 2.8 value in hist02 histogram with labels method and IP.
    # It creates the histogram if it does not exist.
    prom_histogram_observe("hist02", "2.8", "push", "192.168.0.1");
    # When listed the metric it will show lines like this:
    hist02_bucket{method="push", IP="192.168.0.1", le="2.300000"} 0 1592574659768
    hist02_bucket{method="push", IP="192.168.0.1", le="5.800000"} 1 1592574659768
    hist02_bucket{method="push", IP="192.168.0.1", le="+Inf"} 1 1592574659768
    hist02_sum{method="push", IP="192.168.0.1"} 2.800000 1592574659768
    hist02_count{method="push", IP="192.168.0.1"} 1 1592574659768

    ...

### `prom_dispatch()`

Handle the HTTP request and generate a response.

Available via KEMI framework as xhttp_prom.dispatch

#### `prom_dispatch` usage

    ...
    # Needed to use SIP frames as HTTP ones.
    tcp_accept_no_cl=yes
    ...
    # xhttp module depends on sl one.
    loadmodule "sl.so"
    loadmodule "xhttp.so"
    loadmodule "xhttp_prom.so"
    ...
    # show all kamailio statistics.
    modparam("xhttp_prom", "xhttp_prom_stats", "all")
    ...
    event_route[xhttp:request] {
    	$var(xhttp_prom_root) = $(hu{s.substr,0,8});
    	if ($var(xhttp_prom_root) == "/metrics")
    		prom_dispatch();
    	else
    		xhttp_reply("200", "OK", "text/html",
            		"<html><body>Wrong URL $hu</body></html>");
    }
    ...

#### `prom_dispatch` usage (more complete)

Another example with counters and gauge:

    ...
    # Needed to use SIP frames as HTTP ones.
    tcp_accept_no_cl=yes

    # xhttp module depends on sl one.
    loadmodule "sl.so"
    loadmodule "xhttp.so"
    loadmodule "xhttp_prom.so"

    # show &kamailio; statistics for sl group
    modparam("xhttp_prom", "xhttp_prom_stats", "sl:")

    # Define two counters and a gauge
    modparam("xhttp_prom", "prom_counter", "name=cnt_first;");
    modparam("xhttp_prom", "prom_counter", "name=cnt_second; label=method:IP");
    modparam("xhttp_prom", "prom_gauge", "name=gg_first; label=handler");

    event_route[xhttp:request] {
    	$var(xhttp_prom_root) = $(hu{s.substr,0,8});
    	if ($var(xhttp_prom_root) == "/metrics") {
    	    prom_counter_reset("cnt_first");
    		prom_counter_inc("cnt_second", "10", "push", "192.168.0.1");
    		prom_gauge_set("gg_first", "5.2", "my_handler");
    		prom_dispatch();
    	} else
    		xhttp_reply("200", "OK", "text/html",
            		"<html><body>Wrong URL $hu</body></html>");
    }
    ...

    We can manually check the result with a web browser:
    We assume &kamailio; runs in localhost and port is set to default (same as SIP: 5060)
    http://localhost:5060
    ...

    # User defined metrics
    kamailio_cnt_first 0 1554839325427
    kamailio_cnt_second {method="push", IP="192.168.0.1"} 10 1554839325427
    kamailio_gg_first{handler="my_handler"} 5.2 1554839325427

    # Kamailio internal statistics
    kamailio_sl_1xx_replies 0 1554839325427
    kamailio_sl_200_replies 15 1554839325427
    kamailio_sl_202_replies 0 1554839325427
    kamailio_sl_2xx_replies 0 1554839325427
    kamailio_sl_300_replies 0 1554839325427
    kamailio_sl_301_replies 0 1554839325427
    kamailio_sl_302_replies 0 1554839325427
    kamailio_sl_3xx_replies 0 1554839325427
    kamailio_sl_400_replies 0 1554839325427
    kamailio_sl_401_replies 0 1554839325427
    kamailio_sl_403_replies 0 1554839325427
    kamailio_sl_404_replies 0 1554839325427
    kamailio_sl_407_replies 0 1554839325427
    kamailio_sl_408_replies 0 1554839325427
    kamailio_sl_483_replies 0 1554839325427
    kamailio_sl_4xx_replies 0 1554839325427
    kamailio_sl_500_replies 0 1554839325427
    kamailio_sl_5xx_replies 0 1554839325427
    kamailio_sl_6xx_replies 0 1554839325427
    kamailio_sl_failures 0 1554839325427
    kamailio_sl_received_ACKs 0 1554839325427
    kamailio_sl_sent_err_replies 0 1554839325427
    kamailio_sl_sent_replies 15 1554839325427
    kamailio_sl_xxx_replies 0 1554839325461
    ...

### `prom_check_uri()`

Check if path of HTTP URL equals /metrics. This avoids us to check hu variable from xHTTP module.

NOTE: Remember not to block /metrics URL in xHTTP module

Available via KEMI framework as xhttp_prom.check_uri

#### `prom_check_uri` usage

    ...
    # Needed to use SIP frames as HTTP ones.
    tcp_accept_no_cl=yes
    ...
    # xhttp module depends on sl one.
    loadmodule "sl.so"
    loadmodule "xhttp.so"
    loadmodule "xhttp_prom.so"
    ...
    # show all kamailio statistics.
    modparam("xhttp_prom", "xhttp_prom_stats", "all")
    ...
    event_route[xhttp:request] {
    	if (prom_check_uri())
    		prom_dispatch();
    	else
    		xhttp_reply("200", "OK", "text/html",
            		"<html><body>Wrong URL $hu</body></html>");
    }
    ...

## RPC Commands

### `xhttp_prom.counter_reset`

Set a counter to zero.

Name: xhttp_prom.counter_reset

Parameters:

- name: name of the counter (mandatory)

- l0: value of the first label (optional)

- l1: value of second label (optional)

- l2: value of the third label (optional)

#### `xhttp_prom.counter_reset` usage

    		  ...
    		  &kamctl; rpc xhttp_prom.counter_reset "cnt01" "push" "192.168.0.1"
    		  ...

### `xhttp_prom.counter_inc`

Add a number to a counter based on its name and labels.

Name: xhttp_prom.counter_inc

Parameters:

- name: name of the counter (mandatory)

- number: integer to add to counter value. Negative values not allowed.

- l0: value of the first label (optional)

- l1: value of second label (optional)

- l2: value of the third label (optional)

#### `xhttp_prom.counter_inc` usage

    		  ...
    		  &kamctl; rpc xhttp_prom.counter_inc "cnt01" 15 "push" "192.168.0.1"
    		  ...

### `xhttp_prom.gauge_reset`

Set gauge value to zero. Select gauge based on its name and labels.

Name: xhttp_prom.gauge_reset

Parameters:

- name: name of the gauge (mandatory)

- l0: value of the first label (optional)

- l1: value of second label (optional)

- l2: value of the third label (optional)

#### `xhttp_prom.gauge_reset` usage

    		  ...
    		  &kamctl; rpc xhttp_prom.gauge_reset "gg01" "push" "192.168.0.1"
    		  ...

### `xhttp_prom.gauge_inc`

Increase (or decrease) a gauge by a number. Select the gauge by its name and labels.

Name: xhttp_prom.gauge_inc

Parameters:

- name: name of the gauge (mandatory)

- number: float value to add to the gauge value (mandatory)

- l0: value of the first label (optional)

- l1: value of second label (optional)

- l2: value of the third label (optional)

#### `xhttp_prom.gauge_inc` usage

    		  ...
    		  &kamctl; rpc xhttp_prom.gauge_inc "gg01" -- -5.2
    		  ...

### `xhttp_prom.gauge_set`

Set a gauge to a number. Select the gauge by its name and labels.

Name: xhttp_prom.gauge_set

Parameters:

- name: name of the gauge (mandatory)

- number: float value to set the gauge to (mandatory)

- l0: value of the first label (optional)

- l1: value of second label (optional)

- l2: value of the third label (optional)

#### `xhttp_prom.gauge_set` usage

    		  ...
    		  &kamctl; rpc xhttp_prom.gauge_set "gg01" -- -5.2
    		  ...

### `xhttp_prom.histogram_observe`

Observe a number in a histogram. Select the histogram by its name and labels.

Name: xhttp_prom.histogram_observe

Parameters:

- name: name of the histogram (mandatory)

- number: float value to observe in the histogram (mandatory)

- l0: value of the first label (optional)

- l1: value of second label (optional)

- l2: value of the third label (optional)

#### `xhttp_prom.histogram_observe` usage

    		  ...
    		  &kamctl; rpc xhttp_prom.histogram_observe "hist01" -- -5.2
    		  ...

### `xhttp_prom.metric_list_print`

List of all user defined metrics.

Name: xhttp_prom.metric_list_print

Parameters:none

NOTE:: If you list a lot of metrics you may need to increase buffer size of your RPC transport layer.

#### `xhttp_prom.metric_list_print` usage

    		  ...
    		  &kamctl; rpc xhttp_prom.metric_list_print
    		  ...