[ereporter] data loss as a first class citizen

Author: hawkw

ereporter/api/src/lib.rs

@@ -46,14 +46,41 @@ 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)]
+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

@@ -105,19 +105,6 @@
               "type": "string"
             }
           },
-          "reporter_id": {
-            "description": "UUID of the entity that generated this ereport.",
-            "type": "string",
-            "format": "uuid"
-          },
-          "seq": {
-            "description": "The ereport's sequence number, unique with regards to ereports generated by the entity with the `reporter_id`.",
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/Generation"
-              }
-            ]
-          },
           "time_created": {
             "description": "The UTC timestamp when this ereport was observed, as determined by the reporter.",
             "type": "string",
@@ -127,8 +114,6 @@
         "required": [
           "class",
           "facts",
-          "reporter_id",
-          "seq",
           "time_created"
         ]
       },