From 756789a3b8f3b8ae609851e18f365bb5863f6f7a Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Wed, 20 Mar 2024 10:52:16 -0400
Subject: [PATCH v1 2/4] docs: Demote "Monitoring Disk Usage" from chapter to
 section.

This chapter is very short, and the immediately preceding chapter is
called "Monitoring Database Activity". So, instead of having a
separate chapter for this, make it the last section of the preceding
chapter instead.
---
 doc/src/sgml/diskusage.sgml  | 144 -----------------------------------
 doc/src/sgml/filelist.sgml   |   1 -
 doc/src/sgml/monitoring.sgml | 143 ++++++++++++++++++++++++++++++++++
 doc/src/sgml/postgres.sgml   |   1 -
 4 files changed, 143 insertions(+), 146 deletions(-)
 delete mode 100644 doc/src/sgml/diskusage.sgml

diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml
deleted file mode 100644
index 75467582e4..0000000000
--- a/doc/src/sgml/diskusage.sgml
+++ /dev/null
@@ -1,144 +0,0 @@
-<!-- doc/src/sgml/diskusage.sgml -->
-
-<chapter id="diskusage">
- <title>Monitoring Disk Usage</title>
-
- <para>
-  This chapter discusses how to monitor the disk usage of a
-  <productname>PostgreSQL</productname> database system.
- </para>
-
- <sect1 id="disk-usage">
-  <title>Determining Disk Usage</title>
-
-  <indexterm zone="disk-usage">
-   <primary>disk usage</primary>
-  </indexterm>
-
-  <para>
-   Each table has a primary heap disk file where most of the data is
-   stored. If the table has any columns with potentially-wide values,
-   there also might be a <acronym>TOAST</acronym> file associated with the table,
-   which is used to store values too wide to fit comfortably in the main
-   table (see <xref linkend="storage-toast"/>).  There will be one valid index
-   on the <acronym>TOAST</acronym> table, if present. There also might be indexes
-   associated with the base table.  Each table and index is stored in a
-   separate disk file &mdash; possibly more than one file, if the file would
-   exceed one gigabyte.  Naming conventions for these files are described
-   in <xref linkend="storage-file-layout"/>.
-  </para>
-
-  <para>
-   You can monitor disk space in three ways:
-   using the SQL functions listed in <xref linkend="functions-admin-dbsize"/>,
-   using the <xref linkend="oid2name"/> module, or
-   using manual inspection of the system catalogs.
-   The SQL functions are the easiest to use and are generally recommended.
-   The remainder of this section shows how to do it by inspection of the
-   system catalogs.
-  </para>
-
-  <para>
-   Using <application>psql</application> on a recently vacuumed or analyzed database,
-   you can issue queries to see the disk usage of any table:
-<programlisting>
-SELECT pg_relation_filepath(oid), relpages FROM pg_class WHERE relname = 'customer';
-
- pg_relation_filepath | relpages
-----------------------+----------
- base/16384/16806     |       60
-(1 row)
-</programlisting>
-   Each page is typically 8 kilobytes. (Remember, <structfield>relpages</structfield>
-   is only updated by <command>VACUUM</command>, <command>ANALYZE</command>, and
-   a few DDL commands such as <command>CREATE INDEX</command>.)  The file path name
-   is of interest if you want to examine the table's disk file directly.
-  </para>
-
-  <para>
-   To show the space used by <acronym>TOAST</acronym> tables, use a query
-   like the following:
-<programlisting>
-SELECT relname, relpages
-FROM pg_class,
-     (SELECT reltoastrelid
-      FROM pg_class
-      WHERE relname = 'customer') AS ss
-WHERE oid = ss.reltoastrelid OR
-      oid = (SELECT indexrelid
-             FROM pg_index
-             WHERE indrelid = ss.reltoastrelid)
-ORDER BY relname;
-
-       relname        | relpages
-----------------------+----------
- pg_toast_16806       |        0
- pg_toast_16806_index |        1
-</programlisting>
-  </para>
-
-  <para>
-   You can easily display index sizes, too:
-<programlisting>
-SELECT c2.relname, c2.relpages
-FROM pg_class c, pg_class c2, pg_index i
-WHERE c.relname = 'customer' AND
-      c.oid = i.indrelid AND
-      c2.oid = i.indexrelid
-ORDER BY c2.relname;
-
-      relname      | relpages
--------------------+----------
- customer_id_index |       26
-</programlisting>
-  </para>
-
-  <para>
-   It is easy to find your largest tables and indexes using this
-   information:
-<programlisting>
-SELECT relname, relpages
-FROM pg_class
-ORDER BY relpages DESC;
-
-       relname        | relpages
-----------------------+----------
- bigtable             |     3290
- customer             |     3144
-</programlisting>
-  </para>
- </sect1>
-
- <sect1 id="disk-full">
-  <title>Disk Full Failure</title>
-
-  <para>
-   The most important disk monitoring task of a database administrator
-   is to make sure the disk doesn't become full.  A filled data disk will
-   not result in data corruption, but it might prevent useful activity
-   from occurring. If the disk holding the WAL files grows full, database
-   server panic and consequent shutdown might occur.
-  </para>
-
-  <para>
-   If you cannot free up additional space on the disk by deleting
-   other things, you can move some of the database files to other file
-   systems by making use of tablespaces. See <xref
-   linkend="manage-ag-tablespaces"/> for more information about that.
-  </para>
-
-  <tip>
-   <para>
-    Some file systems perform badly when they are almost full, so do
-    not wait until the disk is completely full to take action.
-   </para>
-  </tip>
-
-  <para>
-   If your system supports per-user disk quotas, then the database
-   will naturally be subject to whatever quota is placed on the user
-   the server runs as.  Exceeding the quota will have the same bad
-   effects as running out of disk space entirely.
-  </para>
- </sect1>
-</chapter>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index b7d1222e3e..f39b4efe38 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -34,7 +34,6 @@
 <!ENTITY backup        SYSTEM "backup.sgml">
 <!ENTITY charset       SYSTEM "charset.sgml">
 <!ENTITY client-auth   SYSTEM "client-auth.sgml">
-<!ENTITY diskusage     SYSTEM "diskusage.sgml">
 <!ENTITY high-availability      SYSTEM "high-availability.sgml">
 <!ENTITY installation  SYSTEM "installation.sgml">
 <!ENTITY targets-meson  SYSTEM "targets-meson.sgml">
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 8736eac284..eda54b4985 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -7282,4 +7282,147 @@ if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
 
  </sect1>
 
+ <sect1 id="diskusage">
+  <title>Monitoring Disk Usage</title>
+
+  <para>
+   This section discusses how to monitor the disk usage of a
+   <productname>PostgreSQL</productname> database system.
+  </para>
+
+  <sect2 id="disk-usage">
+   <title>Determining Disk Usage</title>
+
+   <indexterm zone="disk-usage">
+    <primary>disk usage</primary>
+   </indexterm>
+
+   <para>
+    Each table has a primary heap disk file where most of the data is
+    stored. If the table has any columns with potentially-wide values,
+    there also might be a <acronym>TOAST</acronym> file associated with the table,
+    which is used to store values too wide to fit comfortably in the main
+    table (see <xref linkend="storage-toast"/>).  There will be one valid index
+    on the <acronym>TOAST</acronym> table, if present. There also might be indexes
+    associated with the base table.  Each table and index is stored in a
+    separate disk file &mdash; possibly more than one file, if the file would
+    exceed one gigabyte.  Naming conventions for these files are described
+    in <xref linkend="storage-file-layout"/>.
+   </para>
+
+   <para>
+    You can monitor disk space in three ways:
+    using the SQL functions listed in <xref linkend="functions-admin-dbsize"/>,
+    using the <xref linkend="oid2name"/> module, or
+    using manual inspection of the system catalogs.
+    The SQL functions are the easiest to use and are generally recommended.
+    The remainder of this section shows how to do it by inspection of the
+    system catalogs.
+   </para>
+
+   <para>
+    Using <application>psql</application> on a recently vacuumed or analyzed
+    database, you can issue queries to see the disk usage of any table:
+<programlisting>
+SELECT pg_relation_filepath(oid), relpages FROM pg_class WHERE relname = 'customer';
+
+ pg_relation_filepath | relpages
+----------------------+----------
+ base/16384/16806     |       60
+(1 row)
+</programlisting>
+    Each page is typically 8 kilobytes. (Remember, <structfield>relpages</structfield>
+    is only updated by <command>VACUUM</command>, <command>ANALYZE</command>, and
+    a few DDL commands such as <command>CREATE INDEX</command>.)  The file path name
+    is of interest if you want to examine the table's disk file directly.
+   </para>
+
+   <para>
+    To show the space used by <acronym>TOAST</acronym> tables, use a query
+    like the following:
+<programlisting>
+SELECT relname, relpages
+FROM pg_class,
+     (SELECT reltoastrelid
+      FROM pg_class
+      WHERE relname = 'customer') AS ss
+WHERE oid = ss.reltoastrelid OR
+      oid = (SELECT indexrelid
+             FROM pg_index
+             WHERE indrelid = ss.reltoastrelid)
+ORDER BY relname;
+
+       relname        | relpages
+----------------------+----------
+ pg_toast_16806       |        0
+ pg_toast_16806_index |        1
+</programlisting>
+   </para>
+
+   <para>
+    You can easily display index sizes, too:
+<programlisting>
+SELECT c2.relname, c2.relpages
+FROM pg_class c, pg_class c2, pg_index i
+WHERE c.relname = 'customer' AND
+      c.oid = i.indrelid AND
+      c2.oid = i.indexrelid
+ORDER BY c2.relname;
+
+      relname      | relpages
+-------------------+----------
+ customer_id_index |       26
+</programlisting>
+   </para>
+
+   <para>
+    It is easy to find your largest tables and indexes using this
+    information:
+<programlisting>
+SELECT relname, relpages
+FROM pg_class
+ORDER BY relpages DESC;
+
+       relname        | relpages
+----------------------+----------
+ bigtable             |     3290
+ customer             |     3144
+</programlisting>
+   </para>
+  </sect2>
+
+  <sect2 id="disk-full">
+   <title>Disk Full Failure</title>
+
+   <para>
+    The most important disk monitoring task of a database administrator
+    is to make sure the disk doesn't become full.  A filled data disk will
+    not result in data corruption, but it might prevent useful activity
+    from occurring. If the disk holding the WAL files grows full, database
+    server panic and consequent shutdown might occur.
+   </para>
+
+   <para>
+    If you cannot free up additional space on the disk by deleting
+    other things, you can move some of the database files to other file
+    systems by making use of tablespaces. See <xref
+    linkend="manage-ag-tablespaces"/> for more information about that.
+   </para>
+
+   <tip>
+    <para>
+     Some file systems perform badly when they are almost full, so do
+     not wait until the disk is completely full to take action.
+    </para>
+   </tip>
+
+   <para>
+    If your system supports per-user disk quotas, then the database
+    will naturally be subject to whatever quota is placed on the user
+    the server runs as.  Exceeding the quota will have the same bad
+    effects as running out of disk space entirely.
+   </para>
+  </sect2>
+ </sect1>
+
 </chapter>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 7c234ff1db..73b497bcf8 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -161,7 +161,6 @@ break is not needed in a wider output rendering.
   &backup;
   &high-availability;
   &monitoring;
-  &diskusage;
   &wal;
   &logical-replication;
   &jit;
-- 
2.39.3 (Apple Git-145)

