PROMETHEUS module

Admin Guide

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.

Dependencies

External Libraries or Applications

None

OpenSIPS Modules

The following modules must be loaded before this module:

• httpd module.

Exported Parameters

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”.

Set root parameter

...
modparam("prometheus", "root", "prometheus")
...

prefix(string)

Appends a prefix to each statistic exported.

The default value is “opensips”.

Set prefix parameter

...
modparam("prometheus", "prefix", "opensips_1")
...

group_prefix(string)

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

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

Set group_prefix parameter

...
modparam("prometheus", "group_prefix", "opensips")
...

delimiter(string)

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

The default value is ”_“.

Set delimiter parameter

...
modparam("prometheus", "delimiter", "-")
...

group_label(string)

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

The default value is “group”.

Set group_label parameter

...
modparam("prometheus", "group_label", "grp")
...

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. timestamp core opensips_core_timestamp group_prefix
• 2 - send the group as a label of the statstic. group_label

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

Set group_mode parameter

...
modparam("prometheus", "group_mode", 1)
...

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.

Set statistics parameter

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

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.

Set statistics parameter

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

script_route(string)

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

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

Set script_route parameter

...
modparam("prometheus", "script_route", "my_custom_prometheus_route")
...

script_route_avp_result(string)

Specifies the AVP spec name to be used to for returning custom prometheus information.

The AVP is expected to contain a JSON format, containing an array of arrays of custom statistics to export to prometheus. See section for the format itself.

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

Set script_route parameter

...
modparam("prometheus", "script_route", "my_custom_prometheus_route")
modparam("prometheus", "script_route_avp_result", "$avp(prometheus_out_json)")
...
route[my_custom_prometheus_route] {
  # the OUT JSON needs to contain an array of objects containing a header and a values field
  # the header field to contain the custom prometheus stats header
  # the values field is an array itself, of name/value objects
  # used for individual stats publishing
  $avp(prometheus_out_json) = "
[   {
        "header": "# TYPE opensips_cps gauge",
        "values": [
            {
                "name": "opensips_total_cps",
                "value": 3
            }
        ]
    },
    {
        "header": "# TYPE opensips_disabled_rtpengine gauge",
        "values": [
            {
                "name": "opensips_disabled_rtpengine",
                "value": 0
            }
        ]
    },
]";

}
...

Exported Functions

No function exported to be used from configuration file.

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).

Prometheus Scrape Config

scrape_configs:
  - job_name: opensips

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

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Razvan Crainea (@razvancrainea)	34	18	1345	215
2.	Stefan Darius (@dariusstefan)	10	5	395	58
3.	Maksym Sobolyev (@sobomax)	4	2	2	3
4.	Dudu Ben Moshe	4	1	272	0
5.	Vlad Paiu (@vladpaiu)	3	1	6	6
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

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

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	Feb 2021 - Jun 2026
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

Documentation

Contributors

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

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0