Document LSN acronym in WAL Internals

simonat2ndQuadrant · simonat2ndQuadrant · commit ec03f4121cec · 2016-09-05T09:47:49.000+01:00
We previously didn't mention what an LSN actually was.

Simon Riggs and Michael Paquier
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
@@ -380,6 +380,16 @@
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><acronym>LSN</acronym></term>
+    <listitem>
+     <para>
+      Log Sequence Number, see <link linkend="datatype-pg-lsn"><type>pg_lsn</></link>
+      and <link linkend="wal-internals">WAL Internals</link>.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><acronym>MSVC</acronym></term>
     <listitem>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
@@ -724,6 +724,10 @@
  <sect1 id="wal-internals">
   <title>WAL Internals</title>
 
+  <indexterm zone="wal-internals">
+   <primary>LSN</primary>
+  </indexterm>
+
   <para>
    <acronym>WAL</acronym> is automatically enabled; no action is
    required from the administrator except ensuring that the
@@ -732,6 +736,18 @@
    linkend="wal-configuration">).
   </para>
 
+  <para>
+   <acronym>WAL</acronym> records are appended to the <acronym>WAL</acronym>
+   logs as each new record is written. The insert position is described by
+   a Log Sequence Number (<acronym>LSN</acronym>) that is a byte offset into
+   the logs, increasing monotonically with each new record.
+   <acronym>LSN</acronym> values are returned as the datatype
+   <link linkend="datatype-pg-lsn"><type>pg_lsn</></link>. Values can be
+   compared to calculate the volume of <acronym>WAL</acronym> data that
+   separates them, so they are used to measure the progress of replication
+   and recovery.
+  </para>
+
   <para>
    <acronym>WAL</acronym> logs are stored in the directory
    <filename>pg_xlog</filename> under the data directory, as a set of
