Manual for num_connection alarms

doc/src/guide/listeners.asciidoc

@@ -330,7 +330,7 @@ processes.
 
 === Setting connection count alarms
 
-The `alarms` transport options allows you to configure alarms
+The `alarms` transport option allows you to configure alarms
 which will be triggered when the number of connections under a connection
 supervisor reaches or exceeds the defined treshold.
 
@@ -340,7 +340,7 @@ options as values.
 Any term is allowed as an alarm name.
 
 Alarm options, defining the alarm behavior, are again a map with the following
-keys, all of which are mandatory:
+keys:
 
 `type`::
 The alarm type. Currently, `num_connections` is the only allowed type.
@@ -356,7 +356,7 @@ alarm is triggered. Its arguments are the listener name, the alarm
 name, the Pid of the triggering connection supervisor, and the Pids of
 all the connection processes under that supervisor.
 
-`cooldown`::
+`cooldown` (5000)::
 The minimum time to elapse before the alarm can trigger again, in
 milliseconds.
 
@@ -373,8 +373,7 @@ Alarms = #{
                     "Supervisor ~s of listener ~s "
                     "has ~b connections",
                 [Name, Ref, ConnSup, length(ConnPids)])
-        end,
-        cooldown => 5000
+        end
     }
 },
 {ok, _} = ranch:start_listener(tcp_echo,
@@ -386,8 +385,8 @@ Alarms = #{
 In the example code, an alarm named `my_alarm` is defined, which will
 call the given function when the number of connections under a
 connection supervisor reaches or exceeds 100. When the number of
-connections is still (or again) above 100 after 5 seconds, the
-alarm will trigger again.
+connections is still (or again) above 100 after the default cooldown
+period of 5 seconds, the alarm will trigger again.
 
 === When running out of file descriptors
 

doc/src/manual/ranch.asciidoc

@@ -88,6 +88,14 @@ Unique name used to refer to a listener.
 [source,erlang]
 ----
 transport_opts(SocketOpts) = #{
+    alarms               => #{
+                                term() => #{
+                                    type := num_connections,
+                                    treshold := non_neg_integer(),
+                                    callback := fun((ref(), term(), pid(), [pid()]) -> any()),
+                                    cooldown => non_neg_integer()
+                                }
+                            },
     connection_type      => worker | supervisor,
     handshake_timeout    => timeout(),
     max_connections      => max_conns(),
@@ -107,6 +115,38 @@ options and transport-specific socket options.
 
 None of the options are required.
 
+alarms (#{})::
+
+Alarms to call a function when the number of connections under a
+connection supervisor reaches or exceeds a defined treshold.
++
+The map keys are the alarm names, which can be any `term`. The
+associated values are the respective alarm options, again in a map
+with the following keys:
+
+type:::
+
+Must be set to `num_connections`.
+
+treshold:::
+
+Treshold value, which must be a `non_neg_integer`. When the
+number of connections under a connection supervisor reaches
+or exceeds this value, The alarm will trigger and call
+the function defined in the `callback` key (see below).
+
+callback:::
+
+The alarm function, which takes the listener name, the alarm
+name, the pid of the connection supervisor and a list of the pids
+of all connection processes under that supervisor as arguments.
+The return value is ignored.
+
+cooldown (5000):::
+
+The minimum time after which the alarm can be triggered again,
+in milliseconds.
+
 connection_type (worker)::
 
 Type of process that will handle the connection.

src/ranch_conns_sup.erl

@@ -43,7 +43,7 @@
 	handshake_timeout :: timeout(),
 	max_conns = undefined :: ranch:max_conns(),
 	stats_counters_ref :: counters:counters_ref(),
-	alarms = #{} :: #{term() => {undefined | reference(), map()}},
+	alarms = #{} :: #{term() => {map(), undefined | reference()}},
 	logger = undefined :: module()
 }).