Prometheus Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. External Libraries or Applications
              1.2.2. OpenSIPS Modules

        1.3. Exported Parameters

              1.3.1. root(string)
              1.3.2. prefix(string)
              1.3.3. group_prefix(string)
              1.3.4. delimiter(string)
              1.3.5. group_label(string)
              1.3.6. group_mode(int)
              1.3.7. statistics(string)
              1.3.8. labels(string)
              1.3.9. script_route(string)

        1.4. Exported Functions

              1.4.1. prometheus_declare_stat(name, [type], [help])

              1.4.2. prometheus_push_stat(value, [label_name],
                      [label_value])

        1.5. Examples

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set root parameter
   1.2. Set prefix parameter
   1.3. Set group_prefix parameter
   1.4. Set delimiter parameter
   1.5. Set group_label parameter
   1.6. Set group_mode parameter
   1.7. Set statistics parameter
   1.8. Set statistics parameter
   1.9. Set script_route parameter
   1.10. prometheus_declare_stat usage
   1.11. prometheus_push_stat usage
   1.12. Prometheus Scrape Config

Chapter 1. Admin Guide

1.1. Overview

   This module provides a HTTP interface for the Prometheus
   monitoring system, allowing it to fetch different statistics
   from OpenSIPS.

   In order to use it, you have to explicitely define the
   statistics you want to provide by listing them in the
   statistics parameter.

   Currently only counter and gauge 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 variable
   parameter of the statistics module.

   Each exported statistic comes with a group label that indicates
   the group it belongs to.

1.2. Dependencies

1.2.1. External Libraries or Applications

   None

1.2.2. OpenSIPS Modules

   The following modules must be loaded before this module:
     * httpd module.

1.3. Exported Parameters

1.3.1. root(string)

   Specifies the root metrics path Promethus uses to query the
   stats: http://[opensips_IP]:[opensips_httpd_port]/[root]

   The default value is "metrics".

   Example 1.1. Set root parameter
...
modparam("prometheus", "root", "prometheus")
...

1.3.2. prefix(string)

   Appends a prefix to each statistic exported.

   The default value is "opensips".

   Example 1.2. Set prefix parameter
...
modparam("prometheus", "prefix", "opensips_1")
...

1.3.3. group_prefix(string)

   Appends a prefix to the name of the group the statistic belongs
   to.

   The default value is "" (no group prefix).

   Example 1.3. Set group_prefix parameter
...
modparam("prometheus", "group_prefix", "opensips")
...

1.3.4. delimiter(string)

   Specifies the delimiter to be used to separate prefix and
   group_prefix.

   The default value is "_".

   Example 1.4. Set delimiter parameter
...
modparam("prometheus", "delimiter", "-")
...

1.3.5. group_label(string)

   Specifies the label used to store the group when group_mode is
   2.

   The default value is "group".

   Example 1.5. Set group_label parameter
...
modparam("prometheus", "group_label", "grp")
...

1.3.6. group_mode(int)

   Specifies how the group of the statistic should be provisioned
   to Prometheus. Available modes are:
     * 0 - do not send the statistics groups.
     * 1 - send the group in the name of the statstic.
       For example, timestamp statistic from the core group would
       be exported as opensips_core_timestamp. Note that the
       group_prefix is still attached to the group's name.
     * 2 - send the group as a label of the statstic.
       The name of the label is specified by the group_label
       parameter.

   The default value is 0 (do not specify the group).

   Example 1.6. Set group_mode parameter
...
modparam("prometheus", "group_mode", 1)
...

1.3.7. statistics(string)

   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 (:) at the end of the
   groups's name.

   If the all value is used, then the module will expose all
   available statistics - therefore any other settings of this
   parameter is useless;

   This parameter can be defined multiple times.

   The default value is empty: no metric is exported.

   Example 1.7. Set statistics parameter
...
# export the number of active dialogs and the load statistics class
modparam("prometheus", "statistics", "active_dialogs load:")
...

1.3.8. labels(string)

   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.

   The format is group: regex, where group represents the group of
   statistics for whom the regular expression should be applied
   for, and regexp is a regular expression used to match the
   statistic's name and convert it to the desired name and labels.

   The regex format is
   /matching_expression/substitution_expression/flags. The
   substitution_expression resulted after the substituion should
   result in a string with the following format: name:labels,
   where name represents the name of the statistic as it will be
   pushed towards Prometheus, and labels the labels, expressed as
   key=value pairs separated by comma, as they are received by
   Prometheus. Note that the labels string resulted is
   concatenated to the other labeles as plain string - no other
   transformations are performed.

   If a statistic's name within the declared group does not match
   the regular, or the resulted format does not comply with the
   name:labels format, the statistics transformations are ignored
   and it shall be printed as a regular statistic, as if the rule
   was not even used.

   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.

   The default value is empty: statistic name is provided.

   Example 1.8. Set statistics parameter
...
# convert duration_gateway to stat duration with gateway as a label
modparam("prometheus", "labels", "group: /^(.*)_(.*)$/\1:gateway=\"\2\"/
")
...

1.3.9. script_route(string)

   Specifies the route name to be used to for adding custom
   prometheus information.

   The default value is "" - no custom route called.

   Example 1.9. Set script_route parameter
...
modparam("prometheus", "script_route", "my_custom_prometheus_route")
...
route[my_custom_prometheus_route] {
        # * the returned JSON needs to contain an array of objects
        #   containing a header and a values field
        # * the header field to contain the custom prometheus stats head
er
        # * the values field is an array itself, of name/value objects
        #   used for individual stats publishing
        return (1, '[{
        "header": "# TYPE opensips_total_cps gauge",
        "values": [
            {
                "name": "opensips_total_cps",
                "value": 3
            }
        ]
    }, {
        "header": "# TYPE opensips_disabled_rtpengine gauge",
        "values": [
            {
                "name": "opensips_disabled_rtpengine",
                "value": 0
            }
        ]
    }]');
}
...

1.4. Exported Functions

1.4.1.  prometheus_declare_stat(name, [type], [help])

   NOTE: this function can only be used in the route declared in
   the script_route parameter.

   Declares a custom statistic exported to Prometheus server. It
   specifies its type and optionally a help string.

   Parameters
     * name (string) - the name of the statistic
       type (string, optional) - the type of the statistic (i.e.
       counter or gauge). If missing the statistic is declared as
       gauge.
       help (string, optional) - an optional value used to
       describe the statistic meaning. If missing, it is not used.

   This function can only be used in the request route declared in
   the script_route parameter.

   Example 1.10. prometheus_declare_stat usage
...
modparam("prometheus", "script_route", "my_custom_prometheus_route")
...
route[my_custom_prometheus_route] {
        ...
        prometheus_declare_stat("opensips_cps");
        prometheus_push_stat(3);
        ...
}

1.4.2.  prometheus_push_stat(value, [label_name], [label_value])

   NOTE: this function can only be used in the route declared in
   the script_route parameter.

   Pushes a custom statistic value and optionally a set of labels
   to the Prometheus server.

   NOTE: a statistic's value should only be pushed after it had
   been declared using the prometheus_declare_stat function.

   Parameters
     * value (integer) - the value of the statistic
       label_name (string, optional) - used to define labels for
       the pushed statistic. If the label_value parameter is
       missing, this parameter is appended to the name of the
       statisic - this means that it should contain the whole set
       of labels for the value (including curly brackets). If the
       label_value is provided as well, then the parameter should
       only contain one label's name.
       label_value (string, optional) - the value that should be
       used for the label_name parameter label.

   This function can only be used in the request route declared in
   the script_route parameter.

   Example 1.11. prometheus_push_stat usage
...
modparam("prometheus", "script_route", "my_custom_prometheus_route")
...
route[my_custom_prometheus_route] {
        ...
        prometheus_declare_stat("opensips_cps");
        prometheus_push_stat(3); # no label is being used
        prometheus_declare_stat("opensips_cc");
        # the next two are equivalent
        prometheus_push_stat(10, "{gateway=\"gw1\"}"); # no label is bei
ng used
        prometheus_push_stat(10, "gateway", "gw1"); # same as the above
        ...
}

1.5. Examples

   In order to have Prometheus query OpenSIPS for statistics, you
   need to tell him where to get statistics from. To do that, you
   should define a scarpe job in Prometheus's scrape_configs
   config, indicating the IP and port you've configured the httpd
   module to listen on (default: 0.0.0.0:8888).

   Example 1.12. Prometheus Scrape Config

scrape_configs:
  - job_name: opensips

    static_configs:
    - targets: ['localhost:8888']


Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
                   Name               DevScore Commits Lines ++ Lines --
   1. Razvan Crainea (@razvancrainea)    37      20      1540     223
   2. Maksym Sobolyev (@sobomax)         4        2       2        3
   3. Dudu Ben Moshe                     4        1      272       0
   4. Vlad Paiu (@vladpaiu)              3        1       6        6
   5. Ovidiu Sas (@ovidiusas)            3        1       6        5
   6. Liviu Chircu (@liviuchircu)        3        1       1        1
   7. OpenSIPS                           3        1       1        1

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                   Name                 Commit Activity
   1. Ovidiu Sas (@ovidiusas)         Apr 2025 - Apr 2025
   2. Razvan Crainea (@razvancrainea) Feb 2021 - Nov 2024
   3. Vlad Paiu (@vladpaiu)           May 2024 - May 2024
   4. Dudu Ben Moshe                  Feb 2024 - Feb 2024
   5. Maksym Sobolyev (@sobomax)      Feb 2023 - Feb 2023
   6. Liviu Chircu (@liviuchircu)     Aug 2022 - Aug 2022
   7. OpenSIPS                        Feb 2021 - Feb 2021

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Ovidiu Sas (@ovidiusas), Razvan Crainea
   (@razvancrainea), Dudu Ben Moshe, Liviu Chircu (@liviuchircu),
   OpenSIPS.

   Documentation Copyrights:

   Copyright © 2021 www.opensips-solutions.com
