Skip to content

Commit

Permalink
dispatcher/load_balancer: Update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@liviuchircu
liviuchircu committed Feb 10, 2017
1 parent f42bb8e commit 549bcb6
Show file tree
Hide file tree
Showing 4 changed files with 229 additions and 63 deletions.
195 changes: 134 additions & 61 deletions modules/dispatcher/README
View file
Expand Up @@ -10,10 +10,14 @@ Ovidiu Sas

<osas@voipembedded.com>

Edited by

Daniel-Constantin Mierla

<team@voice-system.ro>

Edited by

Carsten Bock

BASIS AudioNet GmbH
Expand Down Expand Up @@ -66,6 +70,9 @@ Carsten Bock
1.3.27. priority_col (string)
1.3.28. attrs_col (string)
1.3.29. socket_col (string)
1.3.30. comm_socket_col (string)
1.3.31. fetch_freeswitch_stats (integer)
1.3.32. max_freeswitch_weight (integer)

1.4. Exported Functions

Expand Down Expand Up @@ -132,10 +139,13 @@ Carsten Bock
1.28. Set “priority_col” parameter
1.29. Set “attrs_col” parameter
1.30. Set “socket_col” parameter
1.31. ds_select_dst usage
1.32. ds_count usage
1.33. ds_is_in_list usage
1.34. OpenSIPS config script - sample dispatcher usage
1.31. Set “comm_socket_col” parameter
1.32. Set the fetch_freeswitch_load parameter
1.33. Set the max_freeswitch_weight parameter
1.34. ds_select_dst usage
1.35. ds_count usage
1.36. ds_is_in_list usage
1.37. OpenSIPS config script - sample dispatcher usage

Chapter 1. Admin Guide

Expand Down Expand Up @@ -641,6 +651,69 @@ modparam("dispatcher", "attrs_col", "dstattrs")
modparam("dispatcher", "socket_col", "my_sock")
...

1.3.30. comm_socket_col (string)

The column's name in the database storing an optional
"communication" socket (as string) with the destination uri.

Default value is “comm_socket”.

Example 1.31. Set “comm_socket_col” parameter
...
modparam("dispatcher", "comm_socket_col", "fs_esl_socket")
...

1.3.31. fetch_freeswitch_stats (integer)

If enabled, FreeSWITCH destinations may have dynamic
dispatching weights, determined at runtime, using the
FreeSWITCH Event Socket Layer. For these destinations, the
Event Socket Layer URL must be provisioned into the
"comm_socket" column. Some example values:
"channels=fs://freeswitch.example.com" or
"channels=fs://127.0.0.1:8021". The default ESL port is 8021.

OpenSIPS will establish a connection with the given socket and
periodically update the weights of these destinations using
statistics pushed by the FreeSWITCH box.

Note that the "weight" column value for ESL-enabled
destinations will be ignored. The values for the automatically
calculated weights range between 0 - 100. This is useful when
grouping normal destinations with FreeSWITCH ones.

The weights are updated every 20 seconds, as the stats arrive
from FreeSWITCH. The update formula is shown below (FreeSWITCH
stats are highlighted in bold):

weight = 100 * (Idle-CPU / 100) * (1 - Sessions / Max-Sessions)

Default value is 0 (disabled).

Example 1.32. Set the fetch_freeswitch_load parameter
...
modparam("dispatcher", "fetch_freeswitch_stats", 1)
...

1.3.32. max_freeswitch_weight (integer)

The maximum weight of a FreeSWITCH ESL-enabled destination.
This value is also used during startup/reload, when no stats
from FreeSWITCH are available yet.

NOTE: OpenSIPS internally rounds weights to nearest integer, so
larger max weight values will more accurately represent the
current load on the FreeSWITCH boxes! For example, if you set
this parameter to 1, the box will receive no traffic whenever
its CPU usage goes past 50%!

Default value is 1000.

Example 1.33. Set the max_freeswitch_weight parameter
...
modparam("dispatcher", "max_freeswitch_weight", 5)
...

1.4. Exported Functions

1.4.1. ds_select_dst(set, alg [, (flags M max_results)*])
Expand Down Expand Up @@ -711,7 +784,7 @@ modparam("dispatcher", "socket_col", "my_sock")

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Example 1.31. ds_select_dst usage
Example 1.34. ds_select_dst usage
...
ds_select_dst("1", "0");
...
Expand Down Expand Up @@ -819,7 +892,7 @@ ds_select_dst("$var(part_name):$var(setid)","$var(alg)","$var(flags)");
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
BRANCH_ROUTE, LOCAL_ROUTE, TIMER_ROUTE, EVENT_ROUTE

Example 1.32. ds_count usage
Example 1.35. ds_count usage
...
if (ds_count("1", "a", "$avp(result)")) {
...
Expand Down Expand Up @@ -857,7 +930,7 @@ if (ds_count("$avp(partition) : $avp(set)", "ip", "$avp(result)")) {
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
BRANCH_ROUTE and ONREPLY_ROUTE.

Example 1.33. ds_is_in_list usage
Example 1.36. ds_is_in_list usage
...
if (ds_is_in_list("$si", "$sp")) {
# source IP:PORT is in a dispatcher list
Expand Down Expand Up @@ -949,7 +1022,7 @@ _empty_line_

Next picture displays a sample usage of dispatcher.

Example 1.34. OpenSIPS config script - sample dispatcher usage
Example 1.37. OpenSIPS config script - sample dispatcher usage
...
#
# sample config file for dispatcher module
Expand Down Expand Up @@ -1002,89 +1075,89 @@ Chapter 2. Frequently Asked Questions

2.1.

Does dispatcher provide a fair distribution?
Does dispatcher provide a fair distribution?

There is no guarantee of that. You should do some measurements
to decide what distribution algorithm fits better in your
environment.
There is no guarantee of that. You should do some measurements
to decide what distribution algorithm fits better in your
environment.

2.2.

Is dispatcher dialog stateful?
Is dispatcher dialog stateful?

No. Dispatcher is stateless, although some distribution
algorithms are designed to select same destination for
subsequent requests of the same dialog (e.g., hashing the
call-id).
No. Dispatcher is stateless, although some distribution
algorithms are designed to select same destination for
subsequent requests of the same dialog (e.g., hashing the
call-id).

2.3.

What happened with the ds_is_from_list() function?
What happened with the ds_is_from_list() function?

The function was replaced by the more generic ds_is_in_list()
function that takes as parameters the IP and PORT to test
against the dispatcher list.
The function was replaced by the more generic ds_is_in_list()
function that takes as parameters the IP and PORT to test
against the dispatcher list.

ds_is_from_list() == ds_is_in_list("$si","$sp")
ds_is_from_list() == ds_is_in_list("$si","$sp")

2.4.

How is weight and priority used by the dispatcher in selecting
a destination?
How is weight and priority used by the dispatcher in selecting
a destination?

The weight of a destination is currently used in the hashing
algorithms and it increases the probability of it to be
chosen(if we have two destinations with weights 1 respectively
4 than the second one is 4 times more likely to be selected
than the other). The sum of all weights does not need to add up
to a specific number. Weights are now used in the round-robin
algorithm, a destination is chosen a number of times equal to
its weight consecutively before going to the next destination.
The weight of a destination is currently used in the hashing
algorithms and it increases the probability of it to be
chosen(if we have two destinations with weights 1 respectively
4 than the second one is 4 times more likely to be selected
than the other). The sum of all weights does not need to add up
to a specific number. Weights are now used in the round-robin
algorithm, a destination is chosen a number of times equal to
its weight consecutively before going to the next destination.

The priority field is used at ordering the destinations from a
set. It does not affect the overall probability of a
destination to be chosen. It is reflected when listing the
destination, the field can definetly be used in further
selecting algorithms.
The priority field is used at ordering the destinations from a
set. It does not affect the overall probability of a
destination to be chosen. It is reflected when listing the
destination, the field can definetly be used in further
selecting algorithms.

2.5.

What happened with the list_file module parameter ?
What happened with the list_file module parameter ?

The support for text file (for provisioning destinations) was
dropped. Only the DB support (provisioning via a DB table) is
now available - if you still want to use a text file for
provisioning, use db_text DB driver (DB emulated via text
files)
The support for text file (for provisioning destinations) was
dropped. Only the DB support (provisioning via a DB table) is
now available - if you still want to use a text file for
provisioning, use db_text DB driver (DB emulated via text
files)

2.6.

Where can I find more about OpenSIPS?
Where can I find more about OpenSIPS?

Take a look at http://www.opensips.org/.
Take a look at http://www.opensips.org/.

2.7.

Where can I post a question about this module?
Where can I post a question about this module?

First at all check if your question was already answered on one
of our mailing lists:
* User Mailing List -
http://lists.opensips.org/cgi-bin/mailman/listinfo/users
* Developer Mailing List -
http://lists.opensips.org/cgi-bin/mailman/listinfo/devel
First at all check if your question was already answered on one
of our mailing lists:
* User Mailing List -
http://lists.opensips.org/cgi-bin/mailman/listinfo/users
* Developer Mailing List -
http://lists.opensips.org/cgi-bin/mailman/listinfo/devel

E-mails regarding any stable version should be sent to
<users@lists.opensips.org> and e-mail regarding development
versions or SVN snapshots should be send to
<devel@lists.opensips.org>.
E-mails regarding any stable version should be sent to
<users@lists.opensips.org> and e-mail regarding development
versions or SVN snapshots should be send to
<devel@lists.opensips.org>.

If you want to keep the mail private, send it to
<users@lists.opensips.org>.
If you want to keep the mail private, send it to
<users@lists.opensips.org>.

2.8.

How can I report a bug?
How can I report a bug?

Please follow the guidelines provided at:
https://github.com/OpenSIPS/opensips/issues
Please follow the guidelines provided at:
https://github.com/OpenSIPS/opensips/issues
93 changes: 93 additions & 0 deletions modules/dispatcher/doc/dispatcher_admin.xml
View file
Expand Up @@ -785,6 +785,99 @@ modparam("dispatcher", "socket_col", "my_sock")
</example>
</section>

<section>
<title><varname>comm_socket_col</varname> (string)</title>
<para>
The column's name in the database storing an optional
"communication" socket (as string) with the destination uri.
</para>
<para>
<emphasis>
Default value is <quote>comm_socket</quote>.
</emphasis>
</para>
<example>
<title>Set <quote>comm_socket_col</quote> parameter</title>
<programlisting format="linespecific">
...
modparam("dispatcher", "comm_socket_col", "fs_esl_socket")
...
</programlisting>
</example>
</section>

<section>
<title><varname>fetch_freeswitch_stats</varname> (integer)</title>
<para>
If enabled, FreeSWITCH destinations may have dynamic dispatching weights,
determined at runtime, using the FreeSWITCH Event Socket Layer.
For these destinations, the Event Socket Layer URL must be provisioned
into the "comm_socket" column. Some example values:
<emphasis>"channels=fs://freeswitch.example.com"</emphasis>
or <emphasis>"channels=fs://127.0.0.1:8021"</emphasis>.
The default ESL port is 8021.
</para>
<para>
OpenSIPS will establish a connection with the given socket and
periodically update the weights of these destinations
using statistics pushed by the FreeSWITCH box.
</para>
<para>
Note that the "weight" column value for ESL-enabled destinations
<emphasis> will be ignored</emphasis>. The values for the automatically
calculated weights range between <emphasis role='bold'>0 - 100</emphasis>.
This is useful when grouping normal destinations with FreeSWITCH ones.
</para>
<para>
The weights are updated every 20 seconds, as the stats
arrive from FreeSWITCH. The update formula is shown below (FreeSWITCH stats
are highlighted in bold):
</para>
<para>
<emphasis>weight = 100 * (<emphasis role='bold'>Idle-CPU</emphasis> / 100) * (1 - <emphasis role='bold'>Sessions</emphasis> / <emphasis role='bold'>Max-Sessions</emphasis>)</emphasis>
</para>
<para>
<emphasis>
Default value is <emphasis role='bold'>0</emphasis> (disabled).
</emphasis>
</para>
<example>
<title>Set the <varname>fetch_freeswitch_load</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("dispatcher", "fetch_freeswitch_stats", 1)
...
</programlisting>
</example>
</section>

<section>
<title><varname>max_freeswitch_weight</varname> (integer)</title>
<para>
The maximum weight of a FreeSWITCH ESL-enabled destination. This value
is also used during startup/reload, when no stats from FreeSWITCH are
available yet.
</para>
<para>
NOTE: OpenSIPS internally rounds weights to nearest integer, so larger
max weight values will more accurately represent the current load on the
FreeSWITCH boxes! For example, if you set this parameter to 1, the box
will receive no traffic whenever its CPU usage goes past 50%!
</para>
<para>
<emphasis>
Default value is <emphasis role='bold'>1000</emphasis>.
</emphasis>
</para>
<example>
<title>Set the <varname>max_freeswitch_weight</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("dispatcher", "max_freeswitch_weight", 5)
...
</programlisting>
</example>
</section>

</section>

Expand Down

0 comments on commit 549bcb6

Please sign in to comment.