1heart(3) Erlang Module Definition heart(3)
2
6 heart - Heartbeat monitoring of an Erlang runtime system.
7
9 This modules contains the interface to the heart process. heart sends
10 periodic heartbeats to an external port program, which is also named
11 heart. The purpose of the heart port program is to check that the Er‐
12 lang runtime system it is supervising is still running. If the port
13 program has not received any heartbeats within HEART_BEAT_TIMEOUT sec‐
14 onds (defaults to 60 seconds), the system can be rebooted.
15 An Erlang runtime system to be monitored by a heart program is to be
17 started with command-line flag -heart (see also erl(1)). The heart
18 process is then started automatically:
19 % erl -heart ...
21 If the system is to be rebooted because of missing heartbeats, or a
23 terminated Erlang runtime system, environment variable HEART_COMMAND
24 must be set before the system is started. If this variable is not set,
25 a warning text is printed but the system does not reboot.
26 To reboot on Windows, HEART_COMMAND can be set to heart -shutdown (in‐
28 cluded in the Erlang delivery) or to any other suitable program that
29 can activate a reboot.
30 The environment variable HEART_BEAT_TIMEOUT can be used to configure
32 the heart time-outs; it can be set in the operating system shell before
33 Erlang is started or be specified at the command line:
34 % erl -heart -env HEART_BEAT_TIMEOUT 30 ...
36 The value (in seconds) must be in the range 10 < X <= 65535.
38 When running on OSs lacking support for monotonic time, heart is sus‐
40 ceptible to system clock adjustments of more than HEART_BEAT_TIMEOUT
41 seconds. When this happens, heart times out and tries to reboot the
42 system. This can occur, for example, if the system clock is adjusted
43 automatically by use of the Network Time Protocol (NTP).
44 If a crash occurs, an erl_crash.dump is not written unless environment
46 variable ERL_CRASH_DUMP_SECONDS is set:
47 % erl -heart -env ERL_CRASH_DUMP_SECONDS 10 ...
49 If a regular core dump is wanted, let heart know by setting the kill
51 signal to abort using environment variable HEART_KILL_SIGNAL=SIGABRT.
52 If unset, or not set to SIGABRT, the default behavior is a kill signal
53 using SIGKILL:
54 % erl -heart -env HEART_KILL_SIGNAL SIGABRT ...
56 If heart should not kill the Erlang runtime system, this can be indi‐
58 cated using the environment variable HEART_NO_KILL=TRUE. This can be
59 useful if the command executed by heart takes care of this, for example
60 as part of a specific cleanup sequence. If unset, or not set to TRUE,
61 the default behaviour will be to kill as described above.
62 % erl -heart -env HEART_NO_KILL 1 ...
64 Furthermore, ERL_CRASH_DUMP_SECONDS has the following behavior on
66 heart:
67 ERL_CRASH_DUMP_SECONDS=0:
69 Suppresses the writing of a crash dump file entirely, thus reboot‐
70 ing the runtime system immediately. This is the same as not setting
71 the environment variable.
72 ERL_CRASH_DUMP_SECONDS=-1:
74 Setting the environment variable to a negative value does not re‐
75 boot the runtime system until the crash dump file is completly
76 written.
77 ERL_CRASH_DUMP_SECONDS=S:
79 heart waits for S seconds to let the crash dump file be written.
80 After S seconds, heart reboots the runtime system, whether the
81 crash dump file is written or not.
82 In the following descriptions, all functions fail with reason badarg if
84 heart is not started.
85
87 heart_option() = check_schedulers
88
90 set_cmd(Cmd) -> ok | {error, {bad_cmd, Cmd}}
91 Types:
93 Cmd = string()
95 Sets a temporary reboot command. This command is used if a
97 HEART_COMMAND other than the one specified with the environment
98 variable is to be used to reboot the system. The new Erlang run‐
99 time system uses (if it misbehaves) environment variable
100 HEART_COMMAND to reboot.
101 Limitations: Command string Cmd is sent to the heart program as
103 an ISO Latin-1 or UTF-8 encoded binary, depending on the file‐
104 name encoding mode of the emulator (see file:native_name_encod‐
105 ing/0). The size of the encoded binary must be less than 2047
106 bytes.
107 clear_cmd() -> ok
109 Clears the temporary boot command. If the system terminates, the
111 normal HEART_COMMAND is used to reboot.
112 get_cmd() -> {ok, Cmd}
114 Types:
116 Cmd = string()
118 Gets the temporary reboot command. If the command is cleared,
120 the empty string is returned.
121 set_callback(Module, Function) ->
123 ok | {error, {bad_callback, {Module, Function}}}
124 Types:
126 Module = Function = atom()
128 This validation callback will be executed before any heartbeat
130 is sent to the port program. For the validation to succeed it
131 needs to return with the value ok.
132 An exception within the callback will be treated as a validation
134 failure.
135 The callback will be removed if the system reboots.
137 clear_callback() -> ok
139 Removes the validation callback call before heartbeats.
141 get_callback() -> {ok, {Module, Function}} | none
143 Types:
145 Module = Function = atom()
147 Get the validation callback. If the callback is cleared, none
149 will be returned.
150 set_options(Options) -> ok | {error, {bad_options, Options}}
152 Types:
154 Options = [heart_option()]
156 Valid options set_options are:
158 check_schedulers:
160 If enabled, a signal will be sent to each scheduler to check
161 its responsiveness. The system check occurs before any
162 heartbeat sent to the port program. If any scheduler is not
163 responsive enough the heart program will not receive its
164 heartbeat and thus eventually terminate the node.
165 Returns with the value ok if the options are valid.
167 get_options() -> {ok, Options} | none
169 Types:
171 Options = [atom()]
173 Returns {ok, Options} where Options is a list of current options
175 enabled for heart. If the callback is cleared, none will be re‐
176 turned.
177Ericsson AB kernel 8.1.3 heart(3)