xfs: create event queuing, formatting, and discovery infrastructure

Create the basic infrastructure that we need to report health events to
userspace.  We need a compact form for recording critical information
about an event and queueing them; a means to notice that we've lost some
events; and a means to format the events into something that userspace
can handle.

Here, we've chosen json to export information to userspace.  The
structured key-value nature of json gives us enormous flexibility to
modify the schema of what we'll send to userspace because we can add new
keys at any time.  Userspace can use whatever json parsers are available
to consume the events and will not be confused by keys they don't
recognize.

Note that we do NOT allow sending json back to the kernel, nor is there
any intent to do that.

Signed-off-by: Darrick J. Wong <djwong@kernel.org>

diff --git a/libxfs/xfs_fs.h b/libxfs/xfs_fs.h
index afbe6bf0915b038cba9b51f77896e04760f57d45..2c302cf30762da4035033f3bce718a2e38f21e57 100644 (file)
--- a/libxfs/xfs_fs.h
+++ b/libxfs/xfs_fs.h
@@ -1101,6 +1101,14 @@ struct xfs_health_monitor {
        __u64   pad2[2];        /* zeroes */
 };
 
+/* Return all health status events, not just deltas */
+#define XFS_HEALTH_MONITOR_VERBOSE     (1ULL << 0)
+
+#define XFS_HEALTH_MONITOR_ALL         (XFS_HEALTH_MONITOR_VERBOSE)
+
+/* Return events in JSON format */
+#define XFS_HEALTH_MONITOR_FMT_JSON    (1)
+
 /*
  * ioctl commands that are used by Linux filesystems
  */

diff --git a/libxfs/xfs_healthmon.schema.json b/libxfs/xfs_healthmon.schema.json
new file mode 100644 (file)
index 0000000..2136b4b
--- /dev/null
+++ b/libxfs/xfs_healthmon.schema.json
@@ -0,0 +1,63 @@
+{
+       "$comment": [
+               "SPDX-License-Identifier: GPL-2.0-or-later",
+               "Copyright (C) 2024 Oracle.  All Rights Reserved.",
+               "Author: Darrick J. Wong <djwong@kernel.org>",
+               "",
+               "This schema file describes the format of the json objects",
+               "readable from the fd returned by the XFS_IOC_HEALTHMON",
+               "ioctl."
+       ],
+
+       "$schema": "https://json-schema.org/draft/2020-12/schema",
+       "$id": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/fs/xfs/libxfs/xfs_healthmon.schema.json",
+
+       "title": "XFS Health Monitoring Events",
+
+       "$comment": "Events must be one of the following types:",
+       "oneOf": [
+               {
+                       "$ref": "#/$events/lost"
+               }
+       ],
+
+       "$comment": "Simple data types are defined here.",
+       "$defs": {
+               "time_ns": {
+                       "title": "Time of Event",
+                       "description": "Timestamp of the event, in nanoseconds since the Unix epoch.",
+                       "type": "integer"
+               }
+       },
+
+       "$comment": "Event types are defined here.",
+       "$events": {
+               "lost": {
+                       "title": "Health Monitoring Events Lost",
+                       "$comment": [
+                               "Previous health monitoring events were",
+                               "dropped due to memory allocation failures",
+                               "or queue limits."
+                       ],
+                       "type": "object",
+
+                       "properties": {
+                               "type": {
+                                       "const": "lost"
+                               },
+                               "time_ns": {
+                                       "$ref": "#/$defs/time_ns"
+                               },
+                               "domain": {
+                                       "const": "mount"
+                               }
+                       },
+
+                       "required": [
+                               "type",
+                               "time_ns",
+                               "domain"
+                       ]
+               }
+       }
+}