From 3cb8819523f549da911bf5b78b8ba16cbe8448f1 Mon Sep 17 00:00:00 2001
From: Jim Garlick <garlick.jim@gmail.com>
Date: Thu, 14 Apr 2022 19:10:07 -0700
Subject: [PATCH] flux-job(1), flux-config-job-manager(5): add purge

Problem: job purge functionality is undocumented.

Add an entry for the purge subcommand to flux-job(1),
and add configuration details to flux-config-job-manager(5).
---
 doc/man1/flux-job.rst                | 21 +++++++++++++++++++++
 doc/man5/flux-config-job-manager.rst | 13 +++++++++++++
 doc/test/spell.en.pws                |  1 +
 3 files changed, 35 insertions(+)

diff --git a/doc/man1/flux-job.rst b/doc/man1/flux-job.rst
index b52296eb61a1..a3fa2999ca30 100644
--- a/doc/man1/flux-job.rst
+++ b/doc/man1/flux-job.rst
@@ -20,6 +20,8 @@ SYNOPSIS
 
 **flux** **job** **raiseall** [*OPTIONS*] *type* [*message...*]
 
+**flux** **job** **purge** [*OPTIONS*]
+
 DESCRIPTION
 ===========
 
@@ -90,6 +92,25 @@ type (positional argument) and accepts the following options:
 **-f, --force**
    Confirm the command.
 
+PURGE
+=====
+
+Inactive job data may be purged from the Flux instance with ``flux job purge``.
+The following options may be used to add selection criteria:
+
+**--age-limit=FSD**
+   Purge inactive jobs older than the specified Flux Standard Duration.
+
+**--num-limit=COUNT**
+   Purge the oldest inactive jobs until there are at most COUNT left.
+
+**-f, --force**
+   Confirm the command.
+
+Inactive jobs may also be purged automatically if the job manager is
+configured as described in :man5:`flux-config-job-manager`.
+
+
 RESOURCES
 =========
 
diff --git a/doc/man5/flux-config-job-manager.rst b/doc/man5/flux-config-job-manager.rst
index af8c7243244a..2a06d09749a0 100644
--- a/doc/man5/flux-config-job-manager.rst
+++ b/doc/man5/flux-config-job-manager.rst
@@ -18,6 +18,16 @@ journal-size-limit
    be retained in the in-memory journal used to answer queries.  The default
    is 1000.
 
+inactive-age-limit
+   (optional) String (in RFC 23 Flux Standard Duration format) that specifies
+   the maximum age of inactive jobs retained in the KVS.  The age is computed
+   since the job became inactive.  Once a job is removed from the KVS, its job
+   data is only available via the job-archive, if configured.  Inactive jobs
+   can also be manually purged with :man1:`flux-job` ``purge``.
+
+inactive-num-limit
+   (optional) Integer maximum number of inactive jobs retained in the KVS.
+
 plugins
    (optional) An array of objects defining a list of jobtap plugin directives.
    Each directive follows the format defined in the :ref:`plugin_directive`
@@ -55,6 +65,9 @@ EXAMPLE
 
    journal-size-limit = 10000
 
+   inactive-age-limit = "7d"
+   inactive-num-limit = 10000
+
    plugins = [
       {
         load = "priority-custom.so",
diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws
index 804b12e22d0b..0e22296f18f0 100644
--- a/doc/test/spell.en.pws
+++ b/doc/test/spell.en.pws
@@ -622,3 +622,4 @@ ustar
 xz
 validator
 statedir
+num