prometheus_admin.xml

<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module provides a HTTP interface for the
		<ulink url='https://prometheus.io/'>Prometheus</ulink>
		monitoring system, allowing it to fetch different
		statistics from OpenSIPS.
	</para>
	<para>
		In order to use it, you have to explicitely define the
		statistics you want to provide by listing them in the
		<xref linkend="param_statistics"/> parameter.
	</para>
	<para>
		Currently only <emphasis>counter</emphasis> and <emphasis>gauge</emphasis>
		metrics types are supported by the module, and whether to choose
		one or the other for a specific statistic is dictated by the way that
		statistic was defined either internally, or explicitely through the
		<emphasis>variable</emphasis> parameter of the <emphasis>statistics</emphasis>
		module.
	</para>
	<para>
		Each exported statistic comes with a <emphasis>group</emphasis> label that
		indicates the group it belongs to.
	</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>External Libraries or Applications</title>
		<para>None
		</para>
	</section>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
		<itemizedlist>
		<listitem>
			<para><emphasis>httpd</emphasis> module.</para>
		</listitem>
		</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_root" xreflabel="root">
		<title><varname>root</varname>(string)</title>
		<para>
		Specifies the root metrics path Promethus uses to query the stats:
		http://[opensips_IP]:[opensips_httpd_port]/[root]
		</para>
		<para>
		<emphasis>The default value is "metrics".</emphasis>
		</para>
		<example>
		<title>Set <varname>root</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("prometheus", "root", "prometheus")
...
</programlisting>
		</example>
	</section>

	<section id="param_prefix" xreflabel="prefix">
		<title><varname>prefix</varname>(string)</title>
		<para>
		Appends a prefix to each statistic exported.
		</para>
		<para>
		<emphasis>The default value is "opensips".</emphasis>
		</para>
		<example>
		<title>Set <varname>prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("prometheus", "prefix", "opensips_1")
...
</programlisting>
		</example>
	</section>

	<section id="param_group_prefix" xreflabel="group_prefix">
		<title><varname>group_prefix</varname>(string)</title>
		<para>
		Appends a prefix to the name of the group the statistic belongs to.
		</para>
		<para>
		<emphasis>The default value is "" (no group prefix).</emphasis>
		</para>
		<example>
		<title>Set <varname>group_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("prometheus", "group_prefix", "opensips")
...
</programlisting>
		</example>
	</section>

	<section id="param_delimiter" xreflabel="delimiter">
		<title><varname>delimiter</varname>(string)</title>
		<para>
		Specifies the delimiter to be used to separate <emphasis>prefix</emphasis>
		and <emphasis>group_prefix</emphasis>.
		</para>
		<para>
		<emphasis>The default value is "_".</emphasis>
		</para>
		<example>
		<title>Set <varname>delimiter</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("prometheus", "delimiter", "-")
...
</programlisting>
		</example>
	</section>

	<section id="param_group_label" xreflabel="group_label">
		<title><varname>group_label</varname>(string)</title>
		<para>
		Specifies the label used to store the group when <emphasis>group_mode</emphasis> is 2.
		</para>
		<para>
		<emphasis>The default value is "group".</emphasis>
		</para>
		<example>
		<title>Set <varname>group_label</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("prometheus", "group_label", "grp")
...
</programlisting>
		</example>
	</section>

	<section id="param_group_mode" xreflabel="group_mode">
		<title><varname>group_mode</varname>(int)</title>
		<para>
		Specifies how the group of the statistic should be provisioned to
		Prometheus. Available modes are:
		<itemizedlist>
		<listitem>
			<para><emphasis>0</emphasis> - do not send the statistics groups.</para>
		</listitem>
		<listitem>
			<para><emphasis>1</emphasis> - send the group in the name of the statstic.</para>
			For example, <emphasis>timestamp</emphasis> statistic from the <emphasis>core</emphasis>
			group would be exported as <emphasis>opensips_core_timestamp</emphasis>. Note that the
			<emphasis>group_prefix</emphasis> is still attached to the group's name.
		</listitem>
		<listitem>
			<para><emphasis>2</emphasis> - send the group as a label of the statstic.</para>
			The name of the label is specified by the <emphasis>group_label</emphasis> parameter.
		</listitem>
		</itemizedlist>
		</para>
		<para>
		<emphasis>The default value is 0 (do not specify the group).</emphasis>
		</para>
		<example>
		<title>Set <varname>group_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("prometheus", "group_mode", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_statistics" xreflabel="statistics">
		<title><varname>statistics</varname>(string)</title>
		<para>
			The statistics that are being exported by OpenSIPS, separated by space.
			The list can also contain statistics groups's names - to do that, you shall
			add a colon (<emphasis>:</emphasis>) at the end of the groups's name.
		</para>
		<para>
			If the <emphasis>all</emphasis> value is used, then the module will expose
			all available statistics - therefore any other settings of this parameter
			is useless;
		</para>
		<para>
			This parameter can be defined multiple times.
		</para>
		<para>
		<emphasis>The default value is empty: no metric is exported.</emphasis>
		</para>
		<example>
		<title>Set <varname>statistics</varname> parameter</title>
		<programlisting format="linespecific">
...
# export the number of active dialogs and the load statistics class
modparam("prometheus", "statistics", "active_dialogs load:")
...
</programlisting>
		</example>
	</section>
	<section id="param_labels" xreflabel="labels">
		<title><varname>labels</varname>(string)</title>
		<para>
			Rules that define how to convert the name of a statistic
			within a group to obtain the name and set of labels to be
			pushed in Prometheus.
		</para>
		<para>
			The format is <emphasis>group: regex</emphasis>, where
			<emphasis>group</emphasis> represents the group of statistics
			for whom the regular expression should be applied for, and
			<emphasis>regexp</emphasis> is a regular expression used to
			match the statistic's name and convert it to the desired name
			and labels.
		</para>
		<para>
			The <emphasis>regex</emphasis> format is
			<emphasis>/matching_expression/substitution_expression/flags</emphasis>.
			The <emphasis>substitution_expression</emphasis> resulted after
			the substituion should result in a string with the following
			format: <emphasis>name:labels</emphasis>, where
			<emphasis>name</emphasis> represents the name of the statistic
			as it will be pushed towards Prometheus, and <emphasis>labels</emphasis>
			the labels, expressed as <emphasis>key=value</emphasis> pairs
			separated by comma, as they are received by Prometheus.
			<emphasis>Note</emphasis> that the <emphasis>labels</emphasis>
			string resulted is concatenated to the other labeles as
			plain string - no other transformations are performed.
		</para>
		<para>
			If a statistic's name within the declared group does not match the
			regular, or the resulted format does not comply with the
			<emphasis>name:labels</emphasis> format, the statistics transformations
			are ignored and it shall be printed as a regular statistic, as if
			the rule was not even used.
		</para>
		<para>
			This parameter can be defined multiple times, even for a single group.
			However, if the statistic matches multiple regular expressions, only
			the first regular expression that matches is considered. The order
			they are checked is the order declared in the script.
		</para>
		<para>
		<emphasis>The default value is empty: statistic name is provided.</emphasis>
		</para>
		<example>
		<title>Set <varname>statistics</varname> parameter</title>
		<programlisting format="linespecific">
...
# convert duration_gateway to stat duration with gateway as a label
modparam("prometheus", "statistics", "group: /^(.*)_(.*)$/\1:gateway=\"\2\"/")
...
</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
		<para>
		No function exported to be used from configuration file.
		</para>
	</section>

	<section>
	<title>Examples</title>
		<para>
			In order to have Prometheus query &osips; for statistics, you need to
			tell him where to get statistics from. To do that, you should define
			a scarpe job in Prometheus's <emphasis>scrape_configs</emphasis> config,
			indicating the IP and port you've configured the <emphasis>httpd</emphasis>
			module to listen on (default: <emphasis>0.0.0.0:8888</emphasis>).
		</para>
		<example>
		<title>Prometheus Scrape Config</title>
		<programlisting format="linespecific">
<![CDATA[
scrape_configs:
  - job_name: opensips

    static_configs:
    - targets: ['localhost:8888']
]]>
</programlisting>
	</example>
	</section>

</chapter>