Add monitoring examples using PostgreSQL and jq.

Suggested by Stephen Frost, Brian Faherty.

doc/example/pgsql-pgbackrest-info.sql

@@ -0,0 +1,30 @@
+-- An example of monitoring pgBackRest from within PostgresSQL
+--
+-- Use copy to export data from the pgBackRest info command into the jsonb
+-- type so it can be queried directly by PostgresSQL.
+
+-- Create monitor schema
+create schema monitor;
+
+-- Get pgBackRest info in JSON format
+create function monitor.pgbackrest_info()
+    returns jsonb AS $$
+declare
+    data jsonb;
+begin
+    -- Create a temp table to hold the JSON data
+    create temp table temp_pgbackrest_data (data jsonb);
+
+    -- Copy data into the table directory from the pgBackRest into command
+    copy temp_pgbackrest_data (data)
+        from program
+            'pgbackrest --output=json info | tr ''\n'' '' ''' (format text);
+
+    select temp_pgbackrest_data.data
+      into data
+      from temp_pgbackrest_data;
+
+    drop table temp_pgbackrest_data;
+
+    return data;
+end $$ language plpgsql;

doc/example/pgsql-pgbackrest-query.sql

@@ -0,0 +1,17 @@
+-- Get last successful backup for each stanza
+--
+-- Requires the monitor.pgbackrest_info function.
+with stanza as
+(
+    select data->'name' as name,
+           data->'backup'->(
+               jsonb_array_length(data->'backup') - 1) as last_backup,
+           data->'archive'->(
+               jsonb_array_length(data->'archive') - 1) as current_archive
+      from jsonb_array_elements(monitor.pgbackrest_info()) as data
+)
+select name,
+       to_timestamp(
+           (last_backup->'timestamp'->>'stop')::numeric) as last_successful_backup,
+       current_archive->>'max' as last_archived_wal
+  from stanza;

doc/xml/release.xml

@@ -83,6 +83,15 @@
 
             <release-doc-list>
                 <release-improvement-list>
+                    <release-item>
+                        <release-item-contributor-list>
+                            <release-item-ideator id="frost.stephen"/>
+                            <release-item-ideator id="faherty.brian"/>
+                        </release-item-contributor-list>
+
+                        <p>Add monitoring examples using <postgres/> and <proper>jq</proper>.</p>
+                    </release-item>
+
                     <release-item>
                         <p>Remove documentation describing <code>info --output=json</code> as experimental.</p>
                     </release-item>
@@ -4360,6 +4369,11 @@
             <contributor-id type="github">anarazel</contributor-id>
         </contributor>
 
+        <contributor id="faherty.brian">
+            <contributor-name-display>Brian Faherty</contributor-name-display>
+            <contributor-id type="github">scrummyin</contributor-id>
+        </contributor>
+
         <contributor id="fiske.keith">
             <contributor-name-display>Keith Fiske</contributor-name-display>
             <contributor-id type="github">keithf4</contributor-id>

doc/xml/user-guide.xml

@@ -964,6 +964,111 @@
         </section>
     </section>
 
+    <!-- *********************************************************************************************************************** -->
+    <section id="monitor" depend="/quickstart/perform-backup">
+        <title>Monitoring</title>
+
+        <p>Monitoring is an important part of any production system.  There are many tools available and <backrest/> can be monitored on any of them with a little work.</p>
+
+        <p><backrest/> can output information about the repository in JSON format which includes a list of all backups for each stanza and WAL archive info.  A script is needed to extract information in a format that the monitoring system can understand.</p>
+
+        <execute-list host="{[host-pg1]}">
+            <title>Get <backrest/> info in JSON format</title>
+
+            <execute show="y">
+                <exe-cmd>pgbackrest --output=json info</exe-cmd>
+            </execute>
+        </execute-list>
+
+        <section id="postgresql">
+            <title>In <postgres/></title>
+
+            <p>The <postgres/> <id>COPY</id> command allows <backrest/> info to be loaded into a table.  The following example wraps that logic in a function that can be used to perform real-time queries.</p>
+
+            <execute-list host="{[host-pg1]}">
+                <title>Load <backrest/> info function for <postgres/></title>
+
+                <execute user="postgres" show="n">
+                    <exe-cmd>mkdir -p /home/postgres/pgbackrest/doc/example</exe-cmd>
+                </execute>
+
+                <execute user="postgres" show="n">
+                    <exe-cmd>cp -r /backrest/doc/example/*
+                        /home/postgres/pgbackrest/doc/example</exe-cmd>
+                </execute>
+
+                <execute output="y">
+                    <exe-cmd>cat
+                        /home/postgres/pgbackrest/doc/example/pgsql-pgbackrest-info.sql</exe-cmd>
+                </execute>
+
+                <execute>
+                    <exe-cmd>psql -f
+                        /home/postgres/pgbackrest/doc/example/pgsql-pgbackrest-info.sql</exe-cmd>
+                </execute>
+            </execute-list>
+
+            <p>Now the <code>monitor.pgbackrest_info()</code> function can be used to determine the last successful backup time and archived WAL for a stanza.</p>
+
+            <execute-list host="{[host-pg1]}">
+                <title>Query last successful backup time and archived WAL</title>
+
+                <execute output="y">
+                    <exe-cmd>cat
+                        /home/postgres/pgbackrest/doc/example/pgsql-pgbackrest-query.sql</exe-cmd>
+                </execute>
+
+                <execute output="y">
+                    <exe-cmd>psql -f
+                        /home/postgres/pgbackrest/doc/example/pgsql-pgbackrest-query.sql</exe-cmd>
+                </execute>
+            </execute-list>
+        </section>
+
+        <section keyword="default" id="jq">
+            <title>Using <proper>jq</proper></title>
+
+            <p><proper>jq</proper> is a command-line utility that can easily extract data from JSON.</p>
+
+            <execute-list host="{[host-pg1]}">
+                <title>Install <proper>jq</proper> utility</title>
+
+                <execute user="root">
+                    <exe-cmd>apt-get install jq</exe-cmd>
+                    <exe-cmd-extra>-y 2>&amp;1</exe-cmd-extra>
+                </execute>
+            </execute-list>
+
+            <p>Now <proper>jq</proper> can be used to query the last successful backup time for a stanza.</p>
+
+            <execute-list host="{[host-pg1]}">
+                <title>Query last successful backup time</title>
+
+                <execute output="y">
+                    <exe-cmd>
+                      pgbackrest --output=json --stanza=demo info |
+                          jq '.[0] | .backup[-1] | .timestamp.stop'
+                    </exe-cmd>
+                </execute>
+            </execute-list>
+
+            <p>Or the last archived WAL.</p>
+
+            <execute-list host="{[host-pg1]}">
+                <title>Query last archived WAL</title>
+
+                <execute output="y">
+                    <exe-cmd>
+                      pgbackrest --output=json --stanza=demo info |
+                          jq '.[0] | .archive[-1] | .max'
+                    </exe-cmd>
+                </execute>
+            </execute-list>
+
+            <p>Note that this syntax requires <proper>jq v1.5</proper>.</p>
+        </section>
+    </section>
+
     <!-- SECTION => RETENTION -->
     <section id="retention" depend="quickstart/perform-backup">
         <title>Retention</title>