Caracola.OverloadControl (Caracola v0.1.0-rc.1)

Copy Markdown View Source

SIP overload control (RFC 7339) with the loss-based algorithm: an overloaded server tells its clients, in the Via of its responses, the percentage of requests they should stop sending it, and the clients do.

defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.OverloadControl],
    sip: [listen: "sip:all:5060", max_calls: 10_000],
    overload_control: [start: 0.8]
end

As server

Requests whose top Via has the oc parameter come from clients supporting overload control. Their responses get, in that Via, the current reduction (oc, a percentage, 0 when not overloaded), oc-algo="loss", oc-validity (:validity milliseconds) and an increasing oc-seq.

The reduction is the highest of:

  • the one set with set_loss/3, for example from the load of the application;
  • the one from the number of calls of the service: from 0 when they are the :start fraction of the max_calls of the sip configuration (0.8 by default), to 100 when they reach it. nil disables it.

As client

Requests sent by the service (as user agent or proxy) get oc and oc-algo="loss" in their Via. When a response has a reduction for a server (identified by its IP address), that percentage of the new requests (without To tag, except ACK and CANCEL) sent to it during the validity are not sent: they fail with {:error, :service_unavailable} (see Caracola.UAC), and a proxy tries the next destination, as when a destination can not be reached (see Caracola.Dispatcher).

Requests not sent emit the [:caracola, :overload_control, :drop] telemetry event, with the :service, the :ip of the server and its :loss as metadata.

Configuration

Under the :overload_control key:

  • :start - fraction of max_calls at which the reduction starts (default 0.8), nil to only use set_loss/3.
  • :validity - milliseconds the reduction sent to clients is valid (default 500).

Summary

Functions

Forgets the reductions asked by servers to a service, and the one it set.

The reduction the service asks its clients for now.

The reduction a server (by IP address) asked the service for, if still valid.

Sets the reduction (0 to 100) the service asks its clients for, for time milliseconds (or until changed).

Functions

clear(service)

@spec clear(module()) :: :ok

Forgets the reductions asked by servers to a service, and the one it set.

loss(service)

@spec loss(module()) :: 0..100

The reduction the service asks its clients for now.

server_loss(service, ip)

@spec server_loss(module(), :inet.ip_address()) :: 0..100

The reduction a server (by IP address) asked the service for, if still valid.

set_loss(service, loss, time \\ :infinity)

@spec set_loss(module(), 0..100, pos_integer() | :infinity) :: :ok

Sets the reduction (0 to 100) the service asks its clients for, for time milliseconds (or until changed).