1<chapter id="event-notifications" xreflabel="event notifications">
2 <title>Event Notifications</title>
3
4 <indexterm>
5   <primary>event notifications</primary>
6 </indexterm>
7
8 <para>
9  Each time &repmgr; or &repmgrd; perform a significant event, a record
10  of that event is written into the <literal>repmgr.events</literal> table together with
11  a timestamp, an indication of failure or success, and further details
12  if appropriate. This is useful for gaining an overview of events
13  affecting the replication cluster. However note that this table has
14  advisory character and should be used in combination with the &repmgr;
15  and PostgreSQL logs to obtain details of any events.
16 </para>
17 <para>
18  Example output after a primary was registered and a standby cloned
19  and registered:
20  <programlisting>
21    repmgr=# SELECT * from repmgr.events ;
22     node_id |      event       | successful |        event_timestamp        |                                       details
23    ---------+------------------+------------+-------------------------------+-------------------------------------------------------------------------------------
24           1 | primary_register | t          | 2016-01-08 15:04:39.781733+09 |
25           2 | standby_clone    | t          | 2016-01-08 15:04:49.530001+09 | Cloned from host 'repmgr_node1', port 5432; backup method: pg_basebackup; --force: N
26           2 | standby_register | t          | 2016-01-08 15:04:50.621292+09 |
27    (3 rows)</programlisting>
28 </para>
29 <para>
30  Alternatively, use <xref linkend="repmgr-cluster-event"/> to output a
31  formatted list of events.
32 </para>
33 <para>
34  Additionally, event notifications can be passed to a user-defined program
35  or script which can take further action, e.g. send email notifications.
36  This is done by setting the <literal>event_notification_command</literal> parameter in
37  <filename>repmgr.conf</filename>.
38 </para>
39 <para>
40  The following format placeholders are provided for all event notifications:
41 </para>
42
43 <variablelist>
44  <varlistentry>
45   <term><option>%n</option></term>
46   <listitem>
47    <para>
48      node ID
49    </para>
50   </listitem>
51  </varlistentry>
52
53  <varlistentry>
54   <term><option>%e</option></term>
55   <listitem>
56    <para>
57     event type
58    </para>
59   </listitem>
60  </varlistentry>
61
62  <varlistentry>
63   <term><option>%s</option></term>
64   <listitem>
65    <para>
66     success (1) or failure (0)
67    </para>
68   </listitem>
69  </varlistentry>
70  <varlistentry>
71   <term><option>%t</option></term>
72   <listitem>
73    <para>
74     timestamp
75    </para>
76   </listitem>
77  </varlistentry>
78
79  <varlistentry>
80   <term><option>%d</option></term>
81   <listitem>
82    <para>
83     details
84    </para>
85   </listitem>
86  </varlistentry>
87 </variablelist>
88
89 <para>
90  The values provided for <literal>%t</literal> and <literal>%d</literal>
91  may contain spaces, so should be quoted in the provided command
92  configuration, e.g.:
93  <programlisting>
94    event_notification_command='/path/to/some/script %n %e %s "%t" "%d"'</programlisting>
95 </para>
96
97 <para>
98   The following parameters are provided for a subset of event notifications:
99 </para>
100
101 <variablelist>
102  <varlistentry>
103   <term><option>%p</option></term>
104   <listitem>
105    <para>
106     node ID of the current primary (<xref linkend="repmgr-standby-register"/> and <xref linkend="repmgr-standby-follow"/>)
107    </para>
108    <para>
109     node ID of the demoted primary (<xref linkend="repmgr-standby-switchover"/> only)
110    </para>
111   </listitem>
112  </varlistentry>
113  <varlistentry>
114   <term><option>%c</option></term>
115   <listitem>
116    <para>
117     <literal>conninfo</literal> string of the primary node
118     (<xref linkend="repmgr-standby-register"/> and <xref linkend="repmgr-standby-follow"/>)
119    </para>
120   </listitem>
121  </varlistentry>
122
123  <varlistentry>
124   <term><option>%a</option></term>
125   <listitem>
126    <para>
127     name of the current primary node (<xref linkend="repmgr-standby-register"/> and <xref linkend="repmgr-standby-follow"/>)
128    </para>
129   </listitem>
130  </varlistentry>
131
132 </variablelist>
133
134 <para>
135  The values provided for <literal>%c</literal> and <literal>%a</literal>
136  will probably contain spaces, so should always be quoted.
137 </para>
138
139 <para>
140  By default, all notification types will be passed to the designated script;
141  the notification types can be filtered to explicitly named ones using the
142  <varname>event_notifications</varname> parameter, e.g.:
143    <programlisting>
144    event_notifications='primary_register,standby_register,witness_register'</programlisting>
145
146 </para>
147
148 <para>
149   Events generated by the &repmgr; command:
150
151  <itemizedlist spacing="compact" mark="bullet">
152
153   <listitem>
154     <simpara><literal><link linkend="repmgr-primary-register-events">cluster_created</link></literal></simpara>
155   </listitem>
156   <listitem>
157     <simpara><literal><link linkend="repmgr-primary-register-events">primary_register</link></literal></simpara>
158   </listitem>
159   <listitem>
160     <simpara><literal><link linkend="repmgr-primary-unregister-events">primary_unregister</link></literal></simpara>
161   </listitem>
162
163   <listitem>
164    <simpara><literal><link linkend="repmgr-standby-clone-events">standby_clone</link></literal></simpara>
165   </listitem>
166   <listitem>
167    <simpara><literal><link linkend="repmgr-standby-register-events">standby_register</link></literal></simpara>
168   </listitem>
169   <listitem>
170    <simpara><literal><link linkend="repmgr-standby-register-events">standby_register_sync</link></literal></simpara>
171   </listitem>
172   <listitem>
173    <simpara><literal><link linkend="repmgr-standby-unregister-events">standby_unregister</link></literal></simpara>
174   </listitem>
175
176   <listitem>
177    <simpara><literal><link linkend="repmgr-standby-promote-events">standby_promote</link></literal></simpara>
178   </listitem>
179   <listitem>
180    <simpara><literal><link linkend="repmgr-standby-follow-events">standby_follow</link></literal></simpara>
181   </listitem>
182   <listitem>
183     <simpara><literal><link linkend="repmgr-standby-switchover-events">standby_switchover</link></literal></simpara>
184   </listitem>
185
186   <listitem>
187     <simpara><literal><link linkend="repmgr-witness-register-events">witness_register</link></literal></simpara>
188   </listitem>
189   <listitem>
190    <simpara><literal><link linkend="repmgr-witness-unregister-events">witness_unregister</link></literal></simpara>
191   </listitem>
192   <listitem>
193    <simpara><literal><link linkend="repmgr-node-rejoin-events">node_rejoin</link></literal></simpara>
194   </listitem>
195   <listitem>
196    <simpara><literal><link linkend="repmgr-cluster-cleanup-events">cluster_cleanup</link></literal></simpara>
197   </listitem>
198
199  </itemizedlist>
200 </para>
201
202 <para>
203   Events generated by &repmgrd; (streaming replication mode):
204
205   <itemizedlist spacing="compact" mark="bullet">
206   <listitem>
207    <simpara><literal>repmgrd_start</literal></simpara>
208   </listitem>
209   <listitem>
210    <simpara><literal>repmgrd_shutdown</literal></simpara>
211   </listitem>
212   <listitem>
213    <simpara><literal>repmgrd_reload</literal></simpara>
214   </listitem>
215   <listitem>
216    <simpara><literal>repmgrd_failover_promote</literal></simpara>
217   </listitem>
218   <listitem>
219    <simpara><literal>repmgrd_failover_follow</literal></simpara>
220   </listitem>
221   <listitem>
222    <simpara><literal>repmgrd_failover_aborted</literal></simpara>
223   </listitem>
224   <listitem>
225    <simpara><literal>repmgrd_standby_reconnect</literal></simpara>
226   </listitem>
227   <listitem>
228    <simpara><literal>repmgrd_promote_error</literal></simpara>
229   </listitem>
230   <listitem>
231    <simpara><literal>repmgrd_local_disconnect</literal></simpara>
232   </listitem>
233   <listitem>
234    <simpara><literal>repmgrd_local_reconnect</literal></simpara>
235   </listitem>
236   <listitem>
237    <simpara><literal>repmgrd_upstream_disconnect</literal></simpara>
238   </listitem>
239   <listitem>
240    <simpara><literal>repmgrd_upstream_reconnect</literal></simpara>
241   </listitem>
242
243   <listitem>
244    <simpara><literal>standby_disconnect_manual</literal></simpara>
245   </listitem>
246   <listitem>
247    <simpara><literal>standby_failure</literal></simpara>
248   </listitem>
249   <listitem>
250    <simpara><literal>standby_recovery</literal></simpara>
251   </listitem>
252
253   <listitem>
254     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_node_disconnect</link></literal></simpara>
255   </listitem>
256   <listitem>
257     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_node_reconnect</link></literal></simpara>
258   </listitem>
259   <listitem>
260     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_node_new_connect</link></literal></simpara>
261   </listitem>
262   <listitem>
263     <simpara><literal><link linkend="repmgrd-primary-child-disconnection-events">child_nodes_disconnect_command</link></literal></simpara>
264   </listitem>
265
266   </itemizedlist>
267 </para>
268
269 <para>
270  Note that under some circumstances (e.g. when no replication cluster primary
271  could be located), it will not be possible to write an entry into the
272  <literal>repmgr.events</literal>
273  table, in which case executing a script via <varname>event_notification_command</varname>
274  can serve as a fallback by generating some form of notification.
275 </para>
276
277
278</chapter>
279