| 1 |
Ptimer Module |
| 2 |
|
| 3 |
Tyler Moore |
| 4 |
|
| 5 |
dOpenSource |
| 6 |
<[email protected]> |
| 7 |
|
| 8 |
Edited by |
| 9 |
|
| 10 |
Tyler Moore |
| 11 |
|
| 12 |
dOpenSource |
| 13 |
<[email protected]> |
| 14 |
|
| 15 |
Copyright © 2025 Tyler Moore, dOpenSource |
| 16 |
__________________________________________________________________ |
| 17 |
|
| 18 |
Table of Contents |
| 19 |
|
| 20 |
1. Admin Guide |
| 21 |
|
| 22 |
1. Overview |
| 23 |
2. Dependencies |
| 24 |
|
| 25 |
2.1. Module Dependencies |
| 26 |
2.2. External Dependencies |
| 27 |
|
| 28 |
3. Parameters |
| 29 |
|
| 30 |
3.1. default_type (int) |
| 31 |
3.2. default_interval (str) |
| 32 |
3.3. default_nworkers (int) |
| 33 |
3.4. timer (str) |
| 34 |
3.5. start (str) |
| 35 |
3.6. loop (str) |
| 36 |
3.7. end (str) |
| 37 |
|
| 38 |
4. Pseudo Variables |
| 39 |
|
| 40 |
4.1. $ptimer(...) |
| 41 |
|
| 42 |
5. RPC Commands |
| 43 |
|
| 44 |
5.1. ptimer.list |
| 45 |
5.2. ptimer.pause |
| 46 |
5.3. ptimer.continue |
| 47 |
5.4. ptimer.start |
| 48 |
5.5. ptimer.loop |
| 49 |
5.6. ptimer.end |
| 50 |
|
| 51 |
6. Example Usages |
| 52 |
|
| 53 |
6.1. Call Rate Shaping |
| 54 |
|
| 55 |
6.1.1. Global Traffic Shaping |
| 56 |
6.1.2. Per Customer Traffic Shaping |
| 57 |
|
| 58 |
6.2. Adaptive Routing |
| 59 |
6.3. Dynamic Timers |
| 60 |
|
| 61 |
6.3.1. Queue Control |
| 62 |
6.3.2. Hot-Reload Tasks |
| 63 |
|
| 64 |
Chapter 1. Admin Guide |
| 65 |
|
| 66 |
Table of Contents |
| 67 |
|
| 68 |
1. Overview |
| 69 |
2. Dependencies |
| 70 |
|
| 71 |
2.1. Module Dependencies |
| 72 |
2.2. External Dependencies |
| 73 |
|
| 74 |
3. Parameters |
| 75 |
|
| 76 |
3.1. default_type (int) |
| 77 |
3.2. default_interval (str) |
| 78 |
3.3. default_nworkers (int) |
| 79 |
3.4. timer (str) |
| 80 |
3.5. start (str) |
| 81 |
3.6. loop (str) |
| 82 |
3.7. end (str) |
| 83 |
|
| 84 |
4. Pseudo Variables |
| 85 |
|
| 86 |
4.1. $ptimer(...) |
| 87 |
|
| 88 |
5. RPC Commands |
| 89 |
|
| 90 |
5.1. ptimer.list |
| 91 |
5.2. ptimer.pause |
| 92 |
5.3. ptimer.continue |
| 93 |
5.4. ptimer.start |
| 94 |
5.5. ptimer.loop |
| 95 |
5.6. ptimer.end |
| 96 |
|
| 97 |
6. Example Usages |
| 98 |
|
| 99 |
6.1. Call Rate Shaping |
| 100 |
|
| 101 |
6.1.1. Global Traffic Shaping |
| 102 |
6.1.2. Per Customer Traffic Shaping |
| 103 |
|
| 104 |
6.2. Adaptive Routing |
| 105 |
6.3. Dynamic Timers |
| 106 |
|
| 107 |
6.3.1. Queue Control |
| 108 |
6.3.2. Hot-Reload Tasks |
| 109 |
|
| 110 |
1. Overview |
| 111 |
|
| 112 |
This module implements precise timers, which are not limited in |
| 113 |
precision by the kamailio tick frequency. |
| 114 |
|
| 115 |
All timers in this module are implemented as background processes, |
| 116 |
using system time for synchronization. |
| 117 |
|
| 118 |
Each timer can have 3 config routes associated with it: |
| 119 |
* start - the route to execute when the timer starts |
| 120 |
* loop - the route to execute continuously (every interval) |
| 121 |
* end - the route to execute when the timer ends |
| 122 |
|
| 123 |
A faked SIP message is given as parameter to called functions, so all |
| 124 |
functions available for REQUEST_ROUTE can be used. Additionally, the |
| 125 |
message state is preserved from start to end of the timer. |
| 126 |
|
| 127 |
2. Dependencies |
| 128 |
|
| 129 |
2.1. Module Dependencies |
| 130 |
2.2. External Dependencies |
| 131 |
|
| 132 |
2.1. Module Dependencies |
| 133 |
|
| 134 |
The following modules must be loaded before this module: |
| 135 |
* No dependencies on other Kamailio modules. |
| 136 |
|
| 137 |
2.2. External Dependencies |
| 138 |
|
| 139 |
The following libraries or applications must be installed before |
| 140 |
running Kamailio with this module loaded: |
| 141 |
* None. |
| 142 |
|
| 143 |
3. Parameters |
| 144 |
|
| 145 |
3.1. default_type (int) |
| 146 |
3.2. default_interval (str) |
| 147 |
3.3. default_nworkers (int) |
| 148 |
3.4. timer (str) |
| 149 |
3.5. start (str) |
| 150 |
3.6. loop (str) |
| 151 |
3.7. end (str) |
| 152 |
|
| 153 |
3.1. default_type (int) |
| 154 |
|
| 155 |
The default timer type (if not present on the "timer" parameter). |
| 156 |
|
| 157 |
If not set, defaults to 1, basic timers. |
| 158 |
|
| 159 |
Can be one of: |
| 160 |
* 0 - basic timer A simple sleep / execute timer. |
| 161 |
* 1 - sync timer Synchronizes time each loop, accounting for |
| 162 |
execution time drift. This type of timer will use a nanosecond |
| 163 |
precision time functions when sleeping / syncing, and the interval |
| 164 |
will be scaled for you. |
| 165 |
* 2 - slice timer A basic timer that slices given tasks into chunks |
| 166 |
for each loop iteration. The current slice and number of tasks are |
| 167 |
available via the pseudo variables. Tasks are split using an |
| 168 |
interval splitting algorithm: |
| 169 |
tasks(i) = ⌊((i + 1) * n) / k⌋ − ⌊(i * n) / k⌋ |
| 170 |
Where, n = total tasks, k = number of slices, and i = current slice |
| 171 |
index. For simplicity, the number of tasks assigned to each worker |
| 172 |
is roughly: |
| 173 |
tasks = n / k |
| 174 |
with the integer remainder evenly distributed. Further slicing per |
| 175 |
worker is possible within the start the route. |
| 176 |
* 3 - synced slice timer This type of timer combines the |
| 177 |
functionality of a sync timer and slice timer. |
| 178 |
|
| 179 |
Example: set default_type parameter |
| 180 |
... |
| 181 |
|
| 182 |
# set the default type to basic timers |
| 183 |
modparam("ptimer", "default_type", 0) |
| 184 |
# set the default type to sync timers |
| 185 |
modparam("ptimer", "default_type", 1) |
| 186 |
# set the default type to slice timers |
| 187 |
modparam("ptimer", "default_type", 2) |
| 188 |
# set the default type to synced slice timers |
| 189 |
modparam("ptimer", "default_type", 3) |
| 190 |
|
| 191 |
... |
| 192 |
|
| 193 |
3.2. default_interval (str) |
| 194 |
|
| 195 |
The default interval to execute loop route for timers (if not present |
| 196 |
on the "timer" parameter). Suffix with "s", "ms", or "us" for an |
| 197 |
interval in seconds, milliseconds, or microseconds. If a number is |
| 198 |
given without a suffix, the number will be treated as seconds. Defaults |
| 199 |
to default_interval. |
| 200 |
|
| 201 |
If not set, defaults to 1s. |
| 202 |
|
| 203 |
Example: set default_interval parameter |
| 204 |
... |
| 205 |
|
| 206 |
# set the default interval to 300 seconds |
| 207 |
modparam("ptimer", "default_interval", "300") |
| 208 |
# set the default interval to 10 seconds |
| 209 |
modparam("ptimer", "default_interval", "10s") |
| 210 |
# set the default interval to 10 milliseconds |
| 211 |
modparam("ptimer", "default_interval", 100ms) |
| 212 |
# set the default interval to 100 microseconds |
| 213 |
modparam("ptimer", "default_interval", 10ous) |
| 214 |
|
| 215 |
... |
| 216 |
|
| 217 |
3.3. default_nworkers (int) |
| 218 |
|
| 219 |
The default number of workers to run per timer (if not present on the |
| 220 |
"timer" parameter). |
| 221 |
|
| 222 |
Example: set default_nworkers parameter |
| 223 |
... |
| 224 |
|
| 225 |
# set the default number of timer workers to 8 |
| 226 |
modparam("ptimer", "default_nworkers", 8) |
| 227 |
|
| 228 |
... |
| 229 |
|
| 230 |
3.4. timer (str) |
| 231 |
|
| 232 |
The definition of a timer. The value of the parameter must have the |
| 233 |
following format: |
| 234 |
* "name=_str_;type=_int_;interval=_str_;nworkers=_int_;ntasks=_int_;n |
| 235 |
slices=_int_" |
| 236 |
|
| 237 |
The parameter can be set multiple times to define more timers in same |
| 238 |
configuration file. |
| 239 |
* name - name of the timer. This attribute is required. |
| 240 |
* type - type of timer to use (see default_type for more info). This |
| 241 |
attribute is optional, defaults to default_type. |
| 242 |
* interval - interval at which the timer workers will execute the |
| 243 |
loop route. See default_interval for more information. |
| 244 |
* nworkers - the number of worker processes to spawn for this timer. |
| 245 |
Defaults to default_nworkers. |
| 246 |
* ntasks - number of tasks each worker will process. If static, you |
| 247 |
can use this parameter, otherwise you can set it within the start |
| 248 |
route. This attribute is optional. |
| 249 |
* nslices - number of slices to split ntasks into. This attribute, |
| 250 |
although set on other timers, only effects tasks when used on a |
| 251 |
slice timer. |
| 252 |
|
| 253 |
Example: set timer parameter |
| 254 |
... |
| 255 |
|
| 256 |
# basic timer looping every 1 sec |
| 257 |
modparam("ptimer", "timer", "name=t1;interval=1s;type=0") |
| 258 |
# sync timer that processes 25 tasks every 100 ms |
| 259 |
modparam("ptimer", "timer", "name=t2;interval=100ms;type=1;ntasks=25") |
| 260 |
# slice timer that processes 10% of the tasks from queue of 2500 every 10 sec |
| 261 |
modparam("ptimer", "timer", "name=t3;interval=10s;type=2;nslices=10;ntasks=2500" |
| 262 |
) |
| 263 |
# basic timer that runs the loop route on 8 different worker processes every 100 |
| 264 |
us |
| 265 |
modparam("ptimer", "timer", "name=t4;interval=100us;type=1;nworkers=8") |
| 266 |
|
| 267 |
... |
| 268 |
|
| 269 |
3.5. start (str) |
| 270 |
|
| 271 |
Route to be executed when timer stars. The value of the parameter must |
| 272 |
have the following format: |
| 273 |
* "timer=_str_;route=_str_" |
| 274 |
|
| 275 |
The start route is optional, only one start route can be set per timer. |
| 276 |
* timer - name of the timer. |
| 277 |
* route - the name of the route block to be executed, or the name of |
| 278 |
the function from kemi script. The kemi function receives a string |
| 279 |
parameter with the value being the name of the module. |
| 280 |
|
| 281 |
The start route is the typical place to put code that sets up for the |
| 282 |
loop route. One can modify some of the pseudo variables in this route, |
| 283 |
such as ntasks. Dynamic or external values can be obtained and stored |
| 284 |
here, i.e. from an htable, database, etc... Variables and AVPs set here |
| 285 |
will remain in-tact in the subsequent loop and end routes. If the start |
| 286 |
route returns -1 the timer will jump execution to the end route. |
| 287 |
|
| 288 |
Example: set start parameter |
| 289 |
... |
| 290 |
|
| 291 |
modparam("ptimer", "timer", "name=t1;interval=10") |
| 292 |
modparam("ptimer", "start", "timer=t1;route=TIMER_START") |
| 293 |
modparam("ptimer", "loop", "timer=t1;route=TIMER_LOOP") |
| 294 |
|
| 295 |
route[TIMER_START] { |
| 296 |
$ptimer(ntasks) = 1000; |
| 297 |
} |
| 298 |
|
| 299 |
... |
| 300 |
|
| 301 |
route[TIMER_LOOP] { |
| 302 |
$var(i) = 0; |
| 303 |
while($var(i) < $ptimer(ntasks)) { |
| 304 |
xlog("L_INFO", "handled task $var(i)\n"); |
| 305 |
$var(i) = $var(i) + 1; |
| 306 |
} |
| 307 |
} |
| 308 |
|
| 309 |
... |
| 310 |
|
| 311 |
3.6. loop (str) |
| 312 |
|
| 313 |
Route to be executed on timer interval. The value of the parameter must |
| 314 |
have the following format: |
| 315 |
* "timer=_str_;route=_str_" |
| 316 |
|
| 317 |
Each timer requires a loop route, only one loop route can be set per |
| 318 |
timer. |
| 319 |
* timer - name of the timer. |
| 320 |
* route - the name of the route block to be executed, or the name of |
| 321 |
the function from kemi script. The kemi function receives a string |
| 322 |
parameter with the value being the name of the module. |
| 323 |
|
| 324 |
The loop route is executed every interval, continuously. This is |
| 325 |
typically where you would process the tasks. If the loop route returns |
| 326 |
-1 the timer will jump execution to the end route. |
| 327 |
|
| 328 |
Example: set loop parameter |
| 329 |
... |
| 330 |
|
| 331 |
modparam("ptimer", "timer", "name=t1;interval=10") |
| 332 |
modparam("ptimer", "loop", "timer=t1;route=TIMER_LOOP") |
| 333 |
|
| 334 |
... |
| 335 |
|
| 336 |
route[TIMER_LOOP] { |
| 337 |
xlog("L_INFO", "timer $ptimer(name) executed at $TF\n"); |
| 338 |
} |
| 339 |
|
| 340 |
... |
| 341 |
|
| 342 |
Example: use loop parameter with Kemi engine |
| 343 |
... |
| 344 |
|
| 345 |
modparam("ptimer", "timer", "name=t1;interval=10") |
| 346 |
modparam("ptimer", "loop", "timer=t1;route=timer_loop") |
| 347 |
|
| 348 |
... |
| 349 |
|
| 350 |
-- ptimer event callback function implemented in Lua |
| 351 |
function timer_loop(evname) |
| 352 |
KSR.info("===== ptimer module triggered event\n"); |
| 353 |
return 1; |
| 354 |
end |
| 355 |
|
| 356 |
... |
| 357 |
|
| 358 |
3.7. end (str) |
| 359 |
|
| 360 |
Route to be executed when timer ends. The value of the parameter must |
| 361 |
have the following format: |
| 362 |
* "timer=_str_;route=_str_" |
| 363 |
|
| 364 |
The end route is optional, only one end route can be set per timer. |
| 365 |
* timer - name of the timer. |
| 366 |
* route - the name of the route block to be executed, or the name of |
| 367 |
the function from kemi script. The kemi function receives a string |
| 368 |
parameter with the value being the name of the module. |
| 369 |
|
| 370 |
The end route runs after the timer ends. Typically this would the place |
| 371 |
to lgog or store data about the tasks processed. After the end route |
| 372 |
completes, the environment is cleared, and the worker is paused. |
| 373 |
|
| 374 |
Example: set end parameter |
| 375 |
... |
| 376 |
|
| 377 |
modparam("ptimer", "timer", "name=t1;interval=100ms") |
| 378 |
modparam("ptimer", "start", "timer=t1;route=TIMER_START") |
| 379 |
modparam("ptimer", "loop", "timer=t1;route=TIMER_LOOP") |
| 380 |
modparam("ptimer", "end", "timer=t1;route=TIMER_END") |
| 381 |
|
| 382 |
... |
| 383 |
|
| 384 |
route[TIMER_START] { |
| 385 |
$var(tasks_done) = 0; |
| 386 |
} |
| 387 |
|
| 388 |
route[TIMER_LOOP] { |
| 389 |
$var(tasks_done) = $var(tasks_done) + 1; |
| 390 |
} |
| 391 |
|
| 392 |
route[TIMER_END] { |
| 393 |
xlog("L_INFO", "tasks handled $var(tasks_done)\n"); |
| 394 |
} |
| 395 |
|
| 396 |
... |
| 397 |
|
| 398 |
4. Pseudo Variables |
| 399 |
|
| 400 |
4.1. $ptimer(...) |
| 401 |
|
| 402 |
4.1. $ptimer(...) |
| 403 |
|
| 404 |
Access to timer / worker attributes. |
| 405 |
|
| 406 |
This PV is only available within ptimer executed routes. |
| 407 |
|
| 408 |
The following attributes are available: |
| 409 |
* name - name of the timer executing this route. This attribute is |
| 410 |
read-only. |
| 411 |
* type - type of timer executing this route. This attribute is |
| 412 |
read-only. |
| 413 |
* interval - interval for this timer. This attribute is r/w inside |
| 414 |
the start route, and r/o elsewhere. |
| 415 |
* nworkers - number of workers spawned for this timer. This attribute |
| 416 |
is read-only. |
| 417 |
* worker - current worker processing this route. This attribute is |
| 418 |
read-only. |
| 419 |
* pid - pid of current worker processing this route. This attribute |
| 420 |
is read-only. |
| 421 |
* ntasks - total number of tasks assigned to this timer. This |
| 422 |
attribute is r/w inside the start route, and r/o elsewhere. |
| 423 |
* tasks - number of tasks assigned to this worker. This attribute is |
| 424 |
r/w inside the start route, and r/o elsewhere. |
| 425 |
* nslices - number of slices this timer will slice tasks into. This |
| 426 |
attribute is r/w inside the start route, and r/o elsewhere. |
| 427 |
* slice - current slice this worker is processing. This attribute is |
| 428 |
r/w inside the start route, and r/o elsewhere. |
| 429 |
|
| 430 |
5. RPC Commands |
| 431 |
|
| 432 |
5.1. ptimer.list |
| 433 |
5.2. ptimer.pause |
| 434 |
5.3. ptimer.continue |
| 435 |
5.4. ptimer.start |
| 436 |
5.5. ptimer.loop |
| 437 |
5.6. ptimer.end |
| 438 |
|
| 439 |
5.1. ptimer.list |
| 440 |
|
| 441 |
List the loaded timers and their current state. |
| 442 |
|
| 443 |
5.2. ptimer.pause |
| 444 |
|
| 445 |
Pause execution of timer worker(s). |
| 446 |
|
| 447 |
5.3. ptimer.continue |
| 448 |
|
| 449 |
Continue execution of timer worker(s). |
| 450 |
|
| 451 |
5.4. ptimer.start |
| 452 |
|
| 453 |
Jump execution of timer worker(s) to the start route. This will |
| 454 |
inherently continue execution if the worker was paused. |
| 455 |
|
| 456 |
5.5. ptimer.loop |
| 457 |
|
| 458 |
Jump execution of timer worker(s) to the loop route. This will |
| 459 |
inherently continue execution if the worker was paused. |
| 460 |
|
| 461 |
5.6. ptimer.end |
| 462 |
|
| 463 |
Jump execution of timer worker(s) to the end route. This will |
| 464 |
inherently continue execution if the worker was paused. |
| 465 |
|
| 466 |
6. Example Usages |
| 467 |
|
| 468 |
6.1. Call Rate Shaping |
| 469 |
|
| 470 |
6.1.1. Global Traffic Shaping |
| 471 |
6.1.2. Per Customer Traffic Shaping |
| 472 |
|
| 473 |
6.2. Adaptive Routing |
| 474 |
6.3. Dynamic Timers |
| 475 |
|
| 476 |
6.3.1. Queue Control |
| 477 |
6.3.2. Hot-Reload Tasks |
| 478 |
|
| 479 |
6.1. Call Rate Shaping |
| 480 |
|
| 481 |
These examples use the ptimer module to limit a customer's CPS (calls |
| 482 |
per second), while smoothing out CPS spikes from the customer's SIP |
| 483 |
server. "Call rate shaping" and "traffic shaping" will be used |
| 484 |
interchangeably in this section. |
| 485 |
|
| 486 |
Traffic shaping can be useful in cases where a customer has temporary |
| 487 |
CPS spikes, or the customer has an under-performing queueing solution |
| 488 |
they can not change. This is most apparent when the rate limiting |
| 489 |
solution your upstream provider uses does not average CPS (common from |
| 490 |
my experience, typically 1s sliding window). Short bursts in CPS from |
| 491 |
one of your customers will therefore be blocked, and could even block |
| 492 |
your other customers calls from being delivered. |
| 493 |
|
| 494 |
The solution to short CPS bursts is queueing your customers calls, and |
| 495 |
throttling call delivery within the CPS limit allocated to you by your |
| 496 |
upstream provider. When a CPS spike occurs, calls that went over the |
| 497 |
limit will stay in the queue until the next iteration, and relayed to |
| 498 |
your upstream, spaced in time to stay within the limit. If a CPS burst |
| 499 |
lasts for an extended period of time, calls continue to enqueue and |
| 500 |
continue to process at the rate limit, until stale calls in the queue |
| 501 |
hit the transaction timeout, typically configured via fr_timer modparam |
| 502 |
in the tm module. You can tune the timeout of queued calls by changing |
| 503 |
transaction timeouts. |
| 504 |
|
| 505 |
The hard part with call rate shaping is timing precisely when requests |
| 506 |
from the queue are processed, in order to stay within the CPS limit, |
| 507 |
and spread out network congestion. Hence, ptimer is a good fit to time |
| 508 |
the call queue processing (or any time sensitive tasks). |
| 509 |
|
| 510 |
6.1.1. Global Traffic Shaping |
| 511 |
|
| 512 |
In this example we want to set a global rate limit of 1000 CPS, and |
| 513 |
throttle short CPS bursts so our customers get a higher delivery rate. |
| 514 |
|
| 515 |
We will split the tasks in the queue such that our timer processes 10% |
| 516 |
of the queue across 8 workers, every 100ms (1/10 the measurement |
| 517 |
period). Resulting in calls from the queue being smoothed out over that |
| 518 |
1sec, and staying within our constraint of 1K CPS at any point in time. |
| 519 |
|
| 520 |
Example Implementation: |
| 521 |
... |
| 522 |
|
| 523 |
loadmodule "mqueue.so" |
| 524 |
loadmodule "ptimer.so" |
| 525 |
|
| 526 |
... |
| 527 |
|
| 528 |
# global call queue |
| 529 |
modparam("mqueue", "mqueue", "name=call_queue") |
| 530 |
# synced slice timer |
| 531 |
# each worker processes 12-13 calls every 100ms (during max load) |
| 532 |
modparam("ptimer", "timer", "name=queue_timer;type=3;interval=100ms;nworkers=8;n |
| 533 |
tasks=1000;nslices=80") |
| 534 |
modparam("ptimer", "start", "timer=queue_timer;route=QUEUE_START") |
| 535 |
modparam("ptimer", "loop", "timer=queue_timer;route=QUEUE_LOOP") |
| 536 |
|
| 537 |
... |
| 538 |
|
| 539 |
request_route { |
| 540 |
... |
| 541 |
|
| 542 |
# routing choices / message changes here |
| 543 |
|
| 544 |
route(QUEUE_CALL); |
| 545 |
} |
| 546 |
|
| 547 |
route[QUEUE_CALL] { |
| 548 |
if(t_suspend()) { |
| 549 |
xlog("L_INFO", "queued call for transaction [$T(id_index):$T(id_label)]\ |
| 550 |
n"); |
| 551 |
mq_add("call_queue", "T(id_index)", "$T(id_label)"); |
| 552 |
exit; |
| 553 |
} |
| 554 |
|
| 555 |
xlog("L_ERR", "failed queuing call $ci\n"); |
| 556 |
sl_reply_error(); |
| 557 |
exit; |
| 558 |
} |
| 559 |
|
| 560 |
route[RELAY] { |
| 561 |
... |
| 562 |
|
| 563 |
if(!t_relay()) { |
| 564 |
send_reply_error(); |
| 565 |
} |
| 566 |
} |
| 567 |
|
| 568 |
route[QUEUE_START] { |
| 569 |
# start each worker on a different slice |
| 570 |
$ptimer(slice) = $ptimer(worker) * 10; |
| 571 |
} |
| 572 |
|
| 573 |
route[QUEUE_LOOP] { |
| 574 |
$var(i) = 0; |
| 575 |
while($var(i) < $ptimer(tasks)) { |
| 576 |
if(mq_fetch("call_queue")) { |
| 577 |
if(!t_continue("$mqk(call_queue)", "$mqv(call_queue)", "RELAY")) { |
| 578 |
xlog("L_ERR", "failed resuming transaction [$mqk(myq):$mqv(myq)] |
| 579 |
\n"); |
| 580 |
} |
| 581 |
} |
| 582 |
$var(i) = $var(i) + 1; |
| 583 |
} |
| 584 |
} |
| 585 |
|
| 586 |
... |
| 587 |
|
| 588 |
6.1.2. Per Customer Traffic Shaping |
| 589 |
|
| 590 |
In this example we want to set a different rate limit for each of our |
| 591 |
customers. Customer 0-2 we sold 8,20,50 CPS respectively. Again, we |
| 592 |
will throttle short CPS bursts so our customers get a higher delivery |
| 593 |
rate. |
| 594 |
|
| 595 |
To achieve this we will allocate each customer a queue and worker of |
| 596 |
their own. Similar to the global example, we will split the queue tasks |
| 597 |
into 10% chunks to evenlu distribute within each second (100ms |
| 598 |
interval). |
| 599 |
|
| 600 |
Example Implementation: |
| 601 |
... |
| 602 |
|
| 603 |
loadmodule "mqueue.so" |
| 604 |
loadmodule "ptimer.so" |
| 605 |
|
| 606 |
... |
| 607 |
|
| 608 |
# customer call queues |
| 609 |
# we could alternative have another data source to look up this queue in start r |
| 610 |
oute |
| 611 |
modparam("mqueue", "mqueue", "name=customer_0") |
| 612 |
modparam("mqueue", "mqueue", "name=customer_1") |
| 613 |
modparam("mqueue", "mqueue", "name=customer_2") |
| 614 |
# synced slice timers for each customer |
| 615 |
# we could allocate more workers per customer if needed |
| 616 |
# if we wanted to lookup the quueue with a different identifier |
| 617 |
# we would also define a start route here |
| 618 |
modparam("ptimer", "timer", "name=customer_0;type=3;interval=100ms;nworkers=1;nt |
| 619 |
asks=8;nslices=10") |
| 620 |
modparam("ptimer", "loop", "timer=customer_0;route=QUEUE_LOOP") |
| 621 |
modparam("ptimer", "timer", "name=customer_1;type=3;interval=100ms;nworkers=1;nt |
| 622 |
asks=8;nslices=10") |
| 623 |
modparam("ptimer", "loop", "timer=customer_1;route=QUEUE_LOOP") |
| 624 |
modparam("ptimer", "timer", "name=customer_2;type=3;interval=100ms;nworkers=1;nt |
| 625 |
asks=8;nslices=10") |
| 626 |
modparam("ptimer", "loop", "timer=customer_2;route=QUEUE_LOOP") |
| 627 |
|
| 628 |
... |
| 629 |
|
| 630 |
request_route { |
| 631 |
... |
| 632 |
|
| 633 |
# routing choices / message changes here |
| 634 |
|
| 635 |
route(QUEUE_CALL); |
| 636 |
} |
| 637 |
|
| 638 |
route[QUEUE_CALL] { |
| 639 |
if(t_suspend()) { |
| 640 |
xlog("L_INFO", "queued call for transaction [$T(id_index):$T(id_label)]\ |
| 641 |
n"); |
| 642 |
mq_add("call_queue", "T(id_index)", "$T(id_label)"); |
| 643 |
exit; |
| 644 |
} |
| 645 |
|
| 646 |
xlog("L_ERR", "failed queuing call $ci\n"); |
| 647 |
sl_reply_error(); |
| 648 |
exit; |
| 649 |
} |
| 650 |
|
| 651 |
route[RELAY] { |
| 652 |
... |
| 653 |
|
| 654 |
if(!t_relay()) { |
| 655 |
send_reply_error(); |
| 656 |
} |
| 657 |
} |
| 658 |
|
| 659 |
route[QUEUE_LOOP] { |
| 660 |
$var(i) = 0; |
| 661 |
while($var(i) < $ptimer(tasks)) { |
| 662 |
if(mq_fetch("$ptimer(name)")) { |
| 663 |
if(!t_continue("$mqk(call_queue)", "$mqv(call_queue)", "RELAY")) { |
| 664 |
xlog("L_ERR", "failed resuming transaction [$mqk(myq):$mqv(myq)] |
| 665 |
\n"); |
| 666 |
} |
| 667 |
} |
| 668 |
$var(i) = $var(i) + 1; |
| 669 |
} |
| 670 |
} |
| 671 |
|
| 672 |
... |
| 673 |
|
| 674 |
6.2. Adaptive Routing |
| 675 |
|
| 676 |
In this example we demonstrate how ptimer can be used to dynamically |
| 677 |
update destinations in a route set based on admin defined metrics. The |
| 678 |
end goal is to guarantee we are providing the level of service we |
| 679 |
promised the customer. |
| 680 |
|
| 681 |
We will use the following metrics (they could be anything you want): |
| 682 |
* MOS - Mean Opinion Score |
| 683 |
* CCR - Call Completion Ratio |
| 684 |
* NER - Network Effectiveness Ratio |
| 685 |
|
| 686 |
For brevity, assume updating the metrics is done elsewhere. |
| 687 |
|
| 688 |
Example Implementation: |
| 689 |
... |
| 690 |
|
| 691 |
loadmodule "dispatcher.so" |
| 692 |
loadmodule "htable.so" |
| 693 |
loadmodule "ptimer.so" |
| 694 |
|
| 695 |
... |
| 696 |
|
| 697 |
# how we will grab the dst info |
| 698 |
modparam("dispatcher", "flags", 2) |
| 699 |
modparam("dispatcher", "xavp_dst", "ds_dst") |
| 700 |
modparam("dispatcher", "xavp_ctx", "ds_ctx") |
| 701 |
# where the metrics are stored (could be anywhere w/ fast access) |
| 702 |
# key format: setid-uri-metric |
| 703 |
modparam("htable", "htable", "dst_kpi=>size=8") |
| 704 |
# where the customer SLA are stored (what we promised the customer) |
| 705 |
modparam("htable", "htable", "min_kpi=>size=8") |
| 706 |
# basic timer, each worker is handling one destination set (setid 0-2) |
| 707 |
# we use the timer worker number to associate the dst set (0-2) |
| 708 |
# that association could be mapped elsewhere and looked up in start route |
| 709 |
modparam("ptimer", "timer", "name=route_optimizer;type=0;interval=500ms;nworkers |
| 710 |
=3") |
| 711 |
modparam("ptimer", "start", "timer=route_optimizer;route=OPTIMIZE_ROUTES_START") |
| 712 |
modparam("ptimer", "loop", "timer=route_optimizer;route=OPTIMIZE_ROUTES_LOOP") |
| 713 |
|
| 714 |
... |
| 715 |
|
| 716 |
route[OPTIMIZE_ROUTES_START] { |
| 717 |
# grab the metric minimums when starting timer |
| 718 |
$var(min_mos) = (int)$sht(min_kpi=>mos); |
| 719 |
$var(min_ccr) = (int)$sht(min_kpi=>ccr); |
| 720 |
$var(min_ner) = (int)$sht(min_kpi=>ner); |
| 721 |
# sanity check |
| 722 |
if(!ds_list_exists("$ptimer(worker)")) { |
| 723 |
return -1; |
| 724 |
} |
| 725 |
# store all the destinations prior to modifying their state |
| 726 |
# this is our local copy used in the loop route |
| 727 |
ds_select("$ptimer(worker)", "8"); |
| 728 |
} |
| 729 |
|
| 730 |
route[OPTIMIZE_ROUTES_LOOP] { |
| 731 |
# remove / add from dst set based on metrics |
| 732 |
$var(i) = 0; |
| 733 |
while($var(i) < $xavp(ds_ctx=>cnt)) { |
| 734 |
$var(prefix) = "$ptimer(worker)-$xavp(ds_dst[$var(i)]=>uri)"; |
| 735 |
if ( |
| 736 |
$sht(dst_kpi=>$var(prefix)-mos) < $var(min_mos) || |
| 737 |
$sht(dst_kpi=>$var(prefix)-ccr) < $var(min_ccr) || |
| 738 |
$sht(dst_kpi=>$var(prefix)-ner) < $var(min_ner) |
| 739 |
) { |
| 740 |
ds_mark_addr("i", "$ptimer(worker)", "$xavp(ds_dst[$var(i)]=>uri)"); |
| 741 |
} else { |
| 742 |
ds_mark_addr("a", "$ptimer(worker)", "$xavp(ds_dst[$var(i)]=>uri)"); |
| 743 |
} |
| 744 |
$var(i) = $var(i) + 1; |
| 745 |
} |
| 746 |
} |
| 747 |
|
| 748 |
... |
| 749 |
|
| 750 |
6.3. Dynamic Timers |
| 751 |
|
| 752 |
These examples use the execution jumping features of ptimer to handle |
| 753 |
common management use cases. |
| 754 |
|
| 755 |
6.3.1. Queue Control |
| 756 |
|
| 757 |
In this example we demonstrate how we can hot-swap the worker |
| 758 |
processing a queue. This could be used to change routing to an IVR |
| 759 |
during holiday, pause during maintenance, to revert new routing logic. |
| 760 |
|
| 761 |
Example Implementation: |
| 762 |
... |
| 763 |
|
| 764 |
loadmodule "mqueue.so" |
| 765 |
loadmodule "ptimer.so" |
| 766 |
|
| 767 |
... |
| 768 |
|
| 769 |
# call queue |
| 770 |
modparam("mqueue", "mqueue", "name=call_queue") |
| 771 |
# basic timer handling normal business hours |
| 772 |
modparam("ptimer", "timer", "name=normal_timer;type=1;interval=100ms") |
| 773 |
modparam("ptimer", "loop", "timer=normal_timer;route=NORMAL_QUEUE_START") |
| 774 |
modparam("ptimer", "loop", "timer=normal_timer;route=HANDLE_QUEUE") |
| 775 |
# basic timer handling holiday / after hours |
| 776 |
modparam("ptimer", "timer", "name=holiday_timer;type=1;interval=100ms") |
| 777 |
modparam("ptimer", "loop", "timer=holiday_timer;route=HOLIDAY_QUEUE_START") |
| 778 |
modparam("ptimer", "loop", "timer=holiday_timer;route=HANDLE_QUEUE") |
| 779 |
|
| 780 |
... |
| 781 |
|
| 782 |
request_route { |
| 783 |
... |
| 784 |
|
| 785 |
route(QUEUE_CALL); |
| 786 |
} |
| 787 |
|
| 788 |
route[QUEUE_CALL] { |
| 789 |
if(t_suspend()) { |
| 790 |
xlog("L_INFO", "queued call for transaction [$T(id_index):$T(id_label)]\ |
| 791 |
n"); |
| 792 |
mq_add("call_queue", "T(id_index)", "$T(id_label)"); |
| 793 |
exit; |
| 794 |
} |
| 795 |
|
| 796 |
xlog("L_ERR", "failed queuing call $ci\n"); |
| 797 |
sl_reply_error(); |
| 798 |
exit; |
| 799 |
} |
| 800 |
|
| 801 |
route[RELAY_PSTN] { |
| 802 |
$du = "sip:1.1.1.1:5060"; |
| 803 |
|
| 804 |
if(!t_relay()) { |
| 805 |
send_reply_error(); |
| 806 |
} |
| 807 |
} |
| 808 |
|
| 809 |
route[RELAY_IVR] { |
| 810 |
$du = "sip:9.9.9.9:5060"; |
| 811 |
|
| 812 |
if(!t_relay()) { |
| 813 |
send_reply_error(); |
| 814 |
} |
| 815 |
} |
| 816 |
|
| 817 |
route[NORMAL_QUEUE_START] { |
| 818 |
$var(relay) = "RELAY_PSTN"; |
| 819 |
} |
| 820 |
|
| 821 |
route[HOLIDAY_QUEUE_START] { |
| 822 |
$var(relay) = "RELAY_IVR"; |
| 823 |
# by default do not loop |
| 824 |
return -1; |
| 825 |
} |
| 826 |
|
| 827 |
route[HANDLE_QUEUE] { |
| 828 |
$var(c) = mq_size("$ptimer(name)"); |
| 829 |
$var(i) = 0; |
| 830 |
while($var(i) < $var(c)) { |
| 831 |
if (mq_fetch("call_queue")) { |
| 832 |
if (!t_continue("$mqk(call_queue)", "$mqv(call_queue)", "$var(relay) |
| 833 |
")) { |
| 834 |
xlog("L_ERR", "failed resuming transaction [$mqk(myq):$mqv(myq)] |
| 835 |
\n"); |
| 836 |
} |
| 837 |
} |
| 838 |
$var(i) = $var(i) + 1; |
| 839 |
} |
| 840 |
} |
| 841 |
|
| 842 |
... |
| 843 |
|
| 844 |
External Program: |
| 845 |
# holiday starts |
| 846 |
kamcmd ptimer.pause normal_timer |
| 847 |
kamcmd ptimer.continue holiday_timer |
| 848 |
|
| 849 |
# holiday ends |
| 850 |
kamcmd ptimer.pause holiday_timer |
| 851 |
kamcmd ptimer.continue normal_timer |
| 852 |
|
| 853 |
6.3.2. Hot-Reload Tasks |
| 854 |
|
| 855 |
In this example we demonstrate how we can load new data for the timer |
| 856 |
to process without reloading. This flexibility means we can load new |
| 857 |
tasks from any data source directly into the background worker process. |
| 858 |
|
| 859 |
Example Implementation: |
| 860 |
... |
| 861 |
|
| 862 |
loadmodule "http_client.so" |
| 863 |
loadmodule "jansson.so" |
| 864 |
loadmodule "ptimer.so" |
| 865 |
|
| 866 |
... |
| 867 |
|
| 868 |
# synced slice timer that pulls data from an HTTP API |
| 869 |
modparam("ptimer", "timer", "name=t1;type=3;interval=100ms;nslices=10") |
| 870 |
modparam("ptimer", "loop", "timer=t1;route=GET_DATA") |
| 871 |
modparam("ptimer", "loop", "timer=t1;route=HANDLE_DATA") |
| 872 |
|
| 873 |
... |
| 874 |
|
| 875 |
route[GET_DATA] { |
| 876 |
# data pulled for this example: {"data":[{"a":100},{"a":200}], "len", 2} |
| 877 |
http_client_get("http://api.example.com/data", "$var(res)"); |
| 878 |
# "ntasks" will be sliced by the timer into "tasks" available in loop |
| 879 |
jansson_get("len", "$var(res)", "$ptimer(ntasks)"); |
| 880 |
jansson_get("data", "$var(res)", "$var(data)"); |
| 881 |
jansson_xdecode("$var(data)", "worker_data"); |
| 882 |
} |
| 883 |
|
| 884 |
route[HANDLE_DATA] { |
| 885 |
$var(i) = 0; |
| 886 |
while($var(i) < $ptimer(tasks)) { |
| 887 |
# do something with the data |
| 888 |
xlog("L_INFO", "a = $xavp(worker_data[$var(i)]=>a)\n"); |
| 889 |
$var(i) = $var(i) + 1; |
| 890 |
} |
| 891 |
} |
| 892 |
|
| 893 |
... |
| 894 |
|
| 895 |
Another Program: |
| 896 |
# could be within xhttp (as postback) or some other program |
| 897 |
# when the data is updated we jump the timer back to start route |
| 898 |
kamcmd ptimer.start t1 |