1 files changed, 208 insertions, 0 deletions
diff --git a/monitor/monitor.cli b/monitor/monitor.cli
new file mode 100644
index 0000000..3a58a1d
--- /dev/null
+++ b/monitor/monitor.cli
@@ -0,0 +1,208 @@
+// file      : monitor/monitor.cli
+// license   : MIT; see accompanying LICENSE file
+
+include <vector>;
+include <string>;
+include <cstddef>; // size_t
+include <cstdint>; // uint16_t
+
+include <mod/module.cli>; // Reuse CLI support types.
+
+"\section=1"
+"\name=brep-monitor"
+"\summary=monitor brep infrastructure"
+
+namespace brep
+{
+  namespace options
+  {
+    {
+      "<options> <brep-config> <toolchain> <name> <version>",
+
+      "\h|SYNOPSIS|
+
+       \c{\b{brep-monitor --help}\n
+          \b{brep-monitor --version}\n
+          \b{brep-monitor} [<options>] <brep-config> <toolchain> [<toolchain>...]}
+
+       \c{<toolchain> = <name>[\b{/}<version>]}
+
+       \h|DESCRIPTION|
+
+       \cb{brep-monitor} analyzes the \cb{brep} internal state and reports the
+       infrastructure issues printing their descriptions to \cb{stderr}.
+
+       The specified \cb{brep} module configuration file (<brep-config>) is
+       used to retrieve information required to access the databases and
+       deduce the expected behavior. Most of this information can be
+       overridden via the command line options.
+
+       Currently, only delayed package builds for the specified toolchains are
+       reported. If toolchain version is omitted then all package builds with
+       this toolchain name are considered.
+
+       \cb{brep-monitor} maintains its own state in the brep \cb{build}
+       database. In particular, it records timestamps of the reported package
+       build delays and optionally omits them from being reported again during
+       the timeout specified with the \cb{--report-timeout} option. If the
+       timeout is unspecified, then the report timestamps are not updated. To
+       report all delays and still update the timestamps specify the zero
+       report timeout.
+
+       By default, a brief report is printed. Use the \cb{--full-report}
+       option to obtain the full report (which may be large).
+
+       Note that \cb{brep-monitor} expects the \cb{build} database schema to
+       have already been created using \l{brep-migrate(1)}."
+    }
+
+    class monitor
+    {
+      "\h|OPTIONS|"
+
+      std::size_t --soft-rebuild-timeout
+      {
+        "<seconds>",
+        "Time to wait (in seconds) before considering a package soft (re)build as
+         delayed. If unspecified, it is the sum of the package rebuild timeout
+         (soft rebuild timeout if the alternative timeout is unspecified and
+         the maximum of two otherwise) and the build result timeout (see
+         the \cb{build-soft-rebuild-timeout}, \cb{build-alt-soft-rebuild-*},
+         and \cb{build-result-timeout} \cb{brep} module configuration options
+         for details). The special zero value disables monitoring of soft
+         rebuilds.
+
+         Note that if both soft and hard rebuilds are disabled in the
+         \cb{brep} module configuration, then \cb{brep-monitor} is unable to
+         come up with a reasonable build timeout on its own. In this case, to
+         monitor the initial package build delays, you may need to specify
+         either \cb{--soft-rebuild-timeout} or \cb{--hard-rebuild-timeout}
+         explicitly.
+
+         Also note that a package that was not built before it was archived is
+         always considered as delayed. However, to distinguish this case from
+         a situation where a package was archived before a configuration have
+         been added, \cb{brep-monitor} needs to observe the package as
+         buildable for this configuration before it is archived. As result, if
+         you run \cb{brep-monitor} periodically (for example, as a cron job),
+         then make sure its running period is less than the tenant archive
+         timeout."
+      }
+
+      std::size_t --hard-rebuild-timeout
+      {
+        "<seconds>",
+        "Time to wait (in seconds) before considering a package hard (re)build
+         as delayed. If unspecified, it is calculated in the same way as for
+         \cb{--soft-rebuild-timeout} but using the
+         \cb{build-hard-rebuild-timeout} and \cb{build-alt-hard-rebuild-*}
+         \cb{brep} module configuration options."
+      }
+
+      std::size_t --report-timeout
+      {
+        "<seconds>",
+        "Time to wait (in seconds) before repeating a report of a package
+         build delay. By default there is no timeout and all reports are
+         repeated."
+      }
+
+      bool --full-report
+      {
+        "Print the list of delayed package builds rather than just their number
+         per build configuration."
+      }
+
+      bool --clean
+      {
+        "Additionally clean the monitor state removing outdated information
+         related to non-existent packages, configurations, etc."
+      }
+
+      // Note that the web service would normally logs in under a different
+      // user (and potentially switch the role afterwords) and so falling back
+      // to brep's user name and password wouldn't make much sense.
+      //
+      std::string --build-db-user|-u
+      {
+        "<user>",
+        "\cb{build} database user name. If unspecified, then operating system
+         (login) name is used."
+      }
+
+      std::string --build-db-password
+      {
+        "<pass>",
+        "\cb{build} database password. If unspecified, then login without
+         password is expected to work."
+      }
+
+      std::string --build-db-name|-n = "brep_package"
+      {
+        "<name>",
+        "\cb{build} database name. If unspecified, then \cb{brep}'s
+         \cb{build-db-name} configuration option value is used."
+      }
+
+      std::string --build-db-host|-h
+      {
+        "<host>",
+        "\cb{build} database host name, address, or socket. If unspecified,
+         then \cb{brep}'s \cb{build-db-host} configuration option value is
+         used."
+      }
+
+      std::uint16_t --build-db-port|-p
+      {
+        "<port>",
+        "\cb{build} database port number. If unspecified, then \cb{brep}'s
+         \cb{build-db-port} configuration option value is used."
+      }
+
+      std::string --pager // String to allow empty value.
+      {
+        "<path>",
+        "The pager program to be used to show long text. Commonly used pager
+         programs are \cb{less} and \cb{more}. You can also specify additional
+         options that should be passed to the pager program with
+         \cb{--pager-option}. If an empty string is specified as the pager
+         program, then no pager will be used. If the pager program is not
+         explicitly specified, then \cb{brep-monitor} will try to use
+         \cb{less}. If it is not available, then no pager will be used."
+      }
+
+      std::vector<std::string> --pager-option
+      {
+        "<opt>",
+        "Additional option to be passed to the pager program. See \cb{--pager}
+         for more information on the pager program. Repeat this option to
+         specify multiple pager options."
+      }
+
+      bool --help {"Print usage information and exit."}
+      bool --version {"Print version and exit."}
+    };
+
+    "\h|EXIT STATUS|
+
+     \dl|
+
+     \li|\cb{0}
+
+     Success.|
+
+     \li|\cb{1}
+
+     Fatal error.|
+
+     \li|\cb{2}
+
+     An instance of \cb{brep-monitor} or some other \cb{brep} utility is
+     already running. Try again.|
+
+     \li|\cb{3}
+
+     Recoverable database error. Try again.||
+    "
+  }
+}