dialoginsight allows you to export dynamic and detailed dialog profiles from OpenSIPs as Prometheus style metrics.

This application does not export standard OpenSIPs statistics. If are looking to export OpenSIPs statistics it has been supported directly by the prometheus module since version 3.2. For older versions you can use opensips_exporter.

• Supports OpenSIPs 3.2+ via the mi_http module and JSON-RPC 2.0
• Export all dialog profiles or only a specific list
• Ability to use dynamic metric labels on exported metrics from the OpenSIPs script.

Configuration is done via a json config file (typically /etc/dialoginsight/config.json) or command line flags.

These may be used as command line flags or as fields in the json configuration.

• listen - Local IP and port for the prometheus exporter to listen on. Metrics are exported under http://listen/metrics (default "127.0.0.1:10337")
• opensips_mi - URL to the mi_http instance for OpenSIPs. (default "http://127.0.0.1:8888/mi")
• export_all - Whether or not to export all dialog profiles from the instance. (default "true")
• export_profiles - List of dialog profiles to export. Used if export_all is set to false. Can also be used with export_all set to true to provide hints about shared and replicated profiles. (Example: [ "myprofile", "sharedprofile/s", "sharedprofile/b" ])
• insight_label - Dialog value starting prefix to indicate it is an insight value (contains labels to process). (default "insight")
• timeout - Timeout duration for OpenSIPs API requests. (default "2s")
• idle_remove - If a metric is idle for this long it will be removed from memory. (default "1m")
• enable_profiling - Enables access to profiling via http://listen/debug/pprof/ (default "false")

• config - Allows specifying the configuration file to use.

Depending on the type of profile they will be exported under either dialoginsight_exported_profile_ (standard OpenSIPs profiles) or dialoginsight_profile_ (extended insight profiles) metric prefixes.

Each profile is exported as its own metric of type dialogs

For example, lets says you have a profile named global that all calls are a part of.

set_dlg_profile("global")

This will be exported as:

dialoginsight_exported_profile_global_dialogs 1

Dialog profiles with values will be exported with a label of name 'value' containing the profile value. For example:

set_dlg_profile("customer", "1234")

Will be exported as:

dialoginsight_exported_profile_customer_dialogs{value="1234"} 1

Currently OpenSIPs reports the name of shared and/or replicated profiles without their tags, but the tags must be included in API calls for them to work correctly. To work around this include the profile name with tags in the export_profiles configuration. This will be used to learn what profiles are shared or replicated and the full name with tags will be used for API calls.

When a profile indicates that it it shared or replicated we will automatically include the shared or replicated labels in the metric with the value of yes. If these labels overlap with insight labels, the insight labels will overwrite them.

Adding insight to the exported profiles allows you to set dynamic metric labels and increase visibility into active calls.

Insight values are profile values that start with insight_label followed by a : and a series of label=value pairs separated by ;

label must follow Prometheus conventions and match the pattern of '^[a-zA-Z_][a-zA-Z0-9_]*'

• If a label is not valid the label=value pair will be silently dropped

value may contain any valid UTF-8 character, except ';'

Example format:

insight: cust=1234;carrier=4567;some_stat=5

The format is very similar to a SIP header whose body contains only a list of parameters with values.

You can can add insight to existing dialog profiles, or use separate profiles.

Lets take our customer example from above

set_dlg_profile("customer", "1234")

Exports as:

dialoginsight_exported_profile_customer_dialogs{value="1234"} 1

Lets add insight to track which source IP the customer is sending from:

set_dlg_profile("customer", "1234")
set_dlg_profile("customer", "insight: cust=1234;scr_ip=$si")

These will be exported as:

dialoginsight_exported_profile_customer_dialogs{value="1234"} 1
dialoginsight_profile_customer_dialogs{cust="1234",src_ip="192.168.168.1"} 1

dialoginsight makes it very easy to create detailed views of your active call dialogs. However one pitfall that you should be aware of is high cardinality. High cardinality can cause performance issues, both with exporting metrics and querying them. Therefore it is important to be mindful of how many potential metrics you may be exporting.

Lets take the example of:

set_dlg_profile("tracking", "insight: cust=1234;carrier=4567")

If you have 100 customers, and 100 carriers, this can potentially result in 10,000 (100*100) unique combinations. While that is not bad by itself, lets say we decide to also track the destination state for U.S. Domestic calls:

set_dlg_profile("tracking", "insight: cust=1234;carrier=4567;called_state=NY")

We now have a potential for 500,000 (100*100*50) unique combinations. This shows how quickly cardinality can grow.

One way to limit cardinality is to use less combinations of labels in a single metric. If we take the example from above, and instead track the called_state by cust and carrier individually:

set_dlg_profile("tracking", "insight: cust=1234;carrier=4567")
set_dlg_profile("cust_called_state", "insight: cust=1234;called_state=NY")
set_dlg_profile("carrier_called_state", "insight: carrier=4567;called_state=NY")

Our potential unique combinations is greatly reduced to 20,000 ((100*100) + (100*50) + (100*50)). You lose granularity in exchange for reduced cardinality.

https://github.com/rrb3942/dialoginsight/issues

MIT

Copyright (c) 2023 Ryan Bullock