[ereporter] data loss as a first class citizen

Author: hawkw

ereporter/api/src/lib.rs

@@ -25,7 +25,7 @@ pub trait EreporterApi {
     async fn ereports_list(
         request_context: RequestContext<Self::Context>,
         query: Query<PaginationParams<EmptyScanParams, Generation>>,
-    ) -> Result<HttpResponseOk<ResultsPage<Ereport>>, HttpError>;
+    ) -> Result<HttpResponseOk<ResultsPage<Entry>>, HttpError>;
 
     /// Informs the reporter that it may freely discard ereports with sequence
     /// numbers less than or equal to `seq`.
@@ -46,14 +46,42 @@ pub struct SeqPathParam {
     pub seq: Generation,
 }
 
-/// An error report.
+/// An entry in the ereport batch returned by a reporter.
 #[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
-pub struct Ereport {
+pub struct Entry {
     /// UUID of the entity that generated this ereport.
     pub reporter_id: Uuid,
     /// The ereport's sequence number, unique with regards to ereports generated
     /// by the entity with the `reporter_id`.
     pub seq: Generation,
+
+    pub value: EntryKind,
+}
+
+/// Kinds of entry in a batch.
+#[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum EntryKind {
+    /// An ereport.
+    Ereport(Ereport),
+    /// Ereports may have been lost.
+    DataLoss {
+        /// The number of ereports that were discarded, if it is known.
+        ///
+        /// If ereports are dropped because a buffer has reached its capacity,
+        /// the reporter is strongly encouraged to attempt to count the number
+        /// of ereports lost. In other cases, such as a reporter crashing and
+        /// restarting, the reporter may not be capable of determining the
+        /// number of ereports that were lost, or even *if* data loss actually
+        /// occurred. Therefore, a `None` here indicates *possible* data loss,
+        /// while a `Some(u32)` indicates *known* data loss.
+        dropped: Option<u32>,
+    },
+}
+
+/// An error report.
+#[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
+pub struct Ereport {
     /// A string indicating the kind of ereport.
     ///
     /// This may be used by diagnosis engines as an indication of what `facts`

ereporter/src/buffer.rs

@@ -17,13 +17,13 @@ pub(crate) enum ServerReq {
     List {
         start_seq: Option<Generation>,
         limit: usize,
-        tx: oneshot::Sender<Vec<ereporter_api::Ereport>>,
+        tx: oneshot::Sender<Vec<ereporter_api::Entry>>,
     },
 }
 
 pub(crate) struct Buffer {
     pub(crate) seq: Generation,
-    pub(crate) buf: VecDeque<ereporter_api::Ereport>,
+    pub(crate) buf: VecDeque<ereporter_api::Entry>,
     pub(crate) log: slog::Logger,
     pub(crate) id: Uuid,
     pub(crate) ereports: mpsc::Receiver<EreportData>,
@@ -111,12 +111,14 @@ impl Buffer {
     fn push_ereport(&mut self, ereport: EreportData) {
         let EreportData { facts, class, time_created } = ereport;
         let seq = self.seq;
-        self.buf.push_back(ereporter_api::Ereport {
-            facts,
-            class,
-            time_created,
-            reporter_id: self.id,
+        self.buf.push_back(ereporter_api::Entry {
             seq,
+            reporter_id: self.id,
+            value: ereporter_api::EntryKind::Ereport(ereporter_api::Ereport {
+                facts,
+                class,
+                time_created,
+            }),
         });
         self.seq = self.seq.next();
         slog::trace!(

openapi/ereporter.json

@@ -42,7 +42,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/EreportResultsPage"
+                  "$ref": "#/components/schemas/EntryResultsPage"
                 }
               }
             }
@@ -90,21 +90,10 @@
   },
   "components": {
     "schemas": {
-      "Ereport": {
-        "description": "An error report.",
+      "Entry": {
+        "description": "An entry in the ereport batch returned by a reporter.",
         "type": "object",
         "properties": {
-          "class": {
-            "description": "A string indicating the kind of ereport.\n\nThis may be used by diagnosis engines as an indication of what `facts` to expect.",
-            "type": "string"
-          },
-          "facts": {
-            "description": "The set of facts (key-value pairs) associated with this ereport.",
-            "type": "object",
-            "additionalProperties": {
-              "type": "string"
-            }
-          },
           "reporter_id": {
             "description": "UUID of the entity that generated this ereport.",
             "type": "string",
@@ -118,29 +107,65 @@
               }
             ]
           },
-          "time_created": {
-            "description": "The UTC timestamp when this ereport was observed, as determined by the reporter.",
-            "type": "string",
-            "format": "date-time"
+          "value": {
+            "$ref": "#/components/schemas/EntryKind"
           }
         },
         "required": [
-          "class",
-          "facts",
           "reporter_id",
           "seq",
-          "time_created"
+          "value"
+        ]
+      },
+      "EntryKind": {
+        "description": "Kinds of entry in a batch.",
+        "oneOf": [
+          {
+            "description": "An ereport.",
+            "type": "object",
+            "properties": {
+              "ereport": {
+                "$ref": "#/components/schemas/Ereport"
+              }
+            },
+            "required": [
+              "ereport"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "description": "Ereports may have been lost.",
+            "type": "object",
+            "properties": {
+              "data_loss": {
+                "type": "object",
+                "properties": {
+                  "dropped": {
+                    "nullable": true,
+                    "description": "The number of ereports that were discarded, if it is known.\n\nIf ereports are dropped because a buffer has reached its capacity, the reporter is strongly encouraged to attempt to count the number of ereports lost. In other cases, such as a reporter crashing and restarting, the reporter may not be capable of determining the number of ereports that were lost, or even *if* data loss actually occurred. Therefore, a `None` here indicates *possible* data loss, while a `Some(u32)` indicates *known* data loss.",
+                    "type": "integer",
+                    "format": "uint32",
+                    "minimum": 0
+                  }
+                }
+              }
+            },
+            "required": [
+              "data_loss"
+            ],
+            "additionalProperties": false
+          }
         ]
       },
-      "EreportResultsPage": {
+      "EntryResultsPage": {
         "description": "A single page of results",
         "type": "object",
         "properties": {
           "items": {
             "description": "list of items on this page of results",
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/Ereport"
+              "$ref": "#/components/schemas/Entry"
             }
           },
           "next_page": {
@@ -153,6 +178,33 @@
           "items"
         ]
       },
+      "Ereport": {
+        "description": "An error report.",
+        "type": "object",
+        "properties": {
+          "class": {
+            "description": "A string indicating the kind of ereport.\n\nThis may be used by diagnosis engines as an indication of what `facts` to expect.",
+            "type": "string"
+          },
+          "facts": {
+            "description": "The set of facts (key-value pairs) associated with this ereport.",
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "time_created": {
+            "description": "The UTC timestamp when this ereport was observed, as determined by the reporter.",
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "class",
+          "facts",
+          "time_created"
+        ]
+      },
       "Error": {
         "description": "Error information from a response.",
         "type": "object",