@downtrace/protocol 0.7.1 → 0.9.0

package/schema/v0/aggregates.schema.json

@@ -10,7 +10,7 @@
   "properties": {
     "protocol": {
       "type": "string",
-      "enum": ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.7.0"],
+      "enum": ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.7.0", "0.8.0", "0.9.0"],
       "description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
     },
     "agent": {
@@ -29,7 +29,7 @@
       "items": {
         "$ref": "#/$defs/Interval"
       },
-      "description": "The intervals this batch carries. May be empty when the batch carries a profile: the profile has a cadence of its own and hangs off the batch, not off an interval (ADR 0017), so tying its delivery to one meant it was lost whenever a window closed with no traffic — at shutdown, always (gh-375). A batch with neither is refused by the cloud with a reason, which the schema cannot say without making the generated types unusable."
+      "description": "The intervals this batch carries. May be empty whenever the batch carries anything else: a process that serves no requests closes no interval, and nothing else a batch carries hangs off one — tying delivery to an interval lost the profile at every shutdown (gh-375) and every exception of a process with no traffic (gh-627). A batch that carries nothing at all is refused by the cloud with a reason, which the schema cannot say without making the generated types unusable."
     },
     "profile": {
       "$ref": "#/$defs/Profile"
@@ -56,7 +56,11 @@
       "items": {
         "$ref": "#/$defs/LocalTrigger"
       },
-      "description": "Local signals that ask for a capture. `product.md:124` gives the instrumentation «disparar por señales locales»: it sees a process in trouble before any aggregate crosses the cloud, and asking in the batch costs no channel of its own — the answer already carries the orders (ADR 0071). Absent from every sender that predates it and from every batch with nothing to ask. The cloud decides: the same budget, cooldown and concurrency as any other capture (`product.md:122`), and a refusal is silence, because there is nothing the instrumentation would do differently."
+      "description": "Local signals that ask for a capture. `product.md:124` gives the instrumentation «trigger on local signals»: it sees a process in trouble before any aggregate crosses the cloud, and asking in the batch costs no channel of its own — the answer already carries the orders (ADR 0071). Absent from every sender that predates it and from every batch with nothing to ask. The cloud decides: the same budget, cooldown and concurrency as any other capture (`product.md:122`), and a refusal is silence, because there is nothing the instrumentation would do differently."
+    },
+    "ending": {
+      "enum": ["signal", "exit", "idle"],
+      "description": "This batch is the last one: the process is leaving deliberately and has already been handed everything the instrumentation was holding. `signal`, a SIGTERM or SIGINT the instrumentation's own handler saw; `exit`, an application that awaited `shutdown()` before calling `process.exit()`; `idle`, an event loop that emptied. Absent means **this sender did not say**, the same reading as `observers` \u2014 never that it ended badly: an instrumentation older than this never says it, and a process an exception killed says nothing because it cannot. It is the half of ERR-04 the cloud cannot infer \u2014 from outside, every ending looks like batches stopping \u2014 and it carries no instant, because the one that matters is when the batch arrived, which the cloud measures."
     }
   },
   "$defs": {
@@ -94,10 +98,50 @@
         },
         "resources": {
           "$ref": "#/$defs/AgentResources",
-          "description": "What the instrumentation costs and what it has lost, measured by itself. Absent means **this sender did not say**, the same reading as `observers` and `withholding`. `product.md:239` asks for it by name: «recursos internos medidos»."
+          "description": "What the instrumentation costs and what it has lost, measured by itself. Absent means **this sender did not say**, the same reading as `observers` and `withholding`. `product.md:239` asks for it by name: «measured internal resources»."
+        },
+        "errorSources": {
+          "$ref": "#/$defs/ErrorSources",
+          "description": "Which of the sources of error this process has connected, as of the moment this batch is sealed. A source is on its list when the process has, at that moment, the instrumentation that produces it installed; the application calling `captureException` does not make it one without the hook connected. Absent means **this sender did not say**, the same reading as `observers` and `resources`: an instrumentation older than protocol 0.9.0 says nothing, and the two lists left empty are not the same thing, because they are a statement — the sender says it has connected no source of error."
         }
       }
     },
+    "ErrorSources": {
+      "title": "ErrorSources",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["inRequest", "outsideRequest"],
+      "properties": {
+        "inRequest": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/InRequestErrorSource"
+          },
+          "description": "The sources of the errors this process sees inside a request, by the value of `Operation.kind` they arrive as, among the values `x-error` marks as errors: `error`, an instrumented operation failed; `framework`, the exception reached the framework's error path and was turned into a 5xx; `explicit`, the application handed it over itself. No value appears twice."
+        },
+        "outsideRequest": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/OutsideRequestErrorSource"
+          },
+          "description": "The sources of the errors this process sees outside any request, by the value of `ProcessException.kind`: `uncaught`, an exception nothing caught; `unhandled-rejection`, a promise rejected with nothing to handle it; `framework`, one that reached a framework's error path; `explicit`, one the application handed over itself. No value appears twice."
+        }
+      }
+    },
+    "InRequestErrorSource": {
+      "title": "InRequestErrorSource",
+      "type": "string",
+      "enum": ["error", "framework", "explicit"],
+      "description": "A value of `Operation.kind` that its `x-error` marks as an error: the ways an error inside a request arrives, and so the sources that can produce one. A query, an outgoing call and a Redis command are things a route ran, never a source of error."
+    },
+    "OutsideRequestErrorSource": {
+      "title": "OutsideRequestErrorSource",
+      "type": "string",
+      "enum": ["uncaught", "unhandled-rejection", "framework", "explicit"],
+      "description": "A value of `ProcessException.kind`: the ways an error outside any request arrives, and so the sources that can produce one."
+    },
     "InstanceInfo": {
       "title": "InstanceInfo",
       "type": "object",
@@ -460,8 +504,24 @@
       "required": ["kind", "hash", "count", "totalMs"],
       "properties": {
         "kind": {
-          "enum": ["query", "error"],
-          "description": "What kind of operation this is."
+          "enum": ["query", "error", "framework", "explicit", "call", "command"],
+          "x-since": {
+            "query": "0.6.0",
+            "error": "0.6.0",
+            "framework": "0.9.0",
+            "explicit": "0.9.0",
+            "call": "0.9.0",
+            "command": "0.9.0"
+          },
+          "x-error": {
+            "query": false,
+            "error": true,
+            "framework": true,
+            "explicit": true,
+            "call": false,
+            "command": false
+          },
+          "description": "What kind of operation this is. Three are things the route ran: `query`, a query to a database; `call`, an outgoing HTTP call, identified by its method and its host; `command`, a Redis command, identified by its name and its server. The other three are errors, and which one it is says how the instrumentation came to see it: `error`, an instrumented operation failed; `framework`, the exception reached the framework's error path and was turned into a 5xx; `explicit`, the application handed it over itself (ERR-02). `x-since` says which minor first carries each value, which is how a reader tells a kind a sender cannot send from one it did not; `x-error` says which values are errors, which is what a list of errors takes and the rest never reach (ERR-01)."
         },
         "hash": {
           "type": "string",
@@ -472,7 +532,7 @@
         "text": {
           "type": "string",
           "maxLength": 1024,
-          "description": "Normalised text, e.g. `SELECT id FROM products WHERE id = ?`. Optional: a user who would rather not send it keeps the whole analysis, only without the label."
+          "description": "Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `POST api.stripe.com` for a call and `HGETALL cache:6379` for a command. A call's and a command's are a word and the place it went — the method and the host, the command's name and its server — and never a path, a query string, a key or an argument (invariant 5): the schema refuses one with anything after the place, or a slash, a question mark or a hash in it. Optional: a user who would rather not send it keeps the whole analysis, only without the label, and a sender in minimal mode, or one withholding the name of the dependency, sends none."
         },
         "count": {
           "type": "integer",
@@ -494,9 +554,12 @@
           "minimum": 0,
           "description": "Only on the `(other)` bucket: how many distinct operations it merges, so a cap does not become a lie by omission."
         },
+        "context": {
+          "$ref": "#/$defs/ReportedContext"
+        },
         "class": {
           "enum": ["select", "insert", "update", "delete", "other"],
-          "description": "What kind of statement this is, when the sender could not normalise it safely. Its presence is the reason the text is absent: `product.md:104` says a query the normaliser does not understand travels «solo como hash y clase», and this is the class. Never sent together with `text` — they are two answers to the same question. Our word and not the service's: it is decided from the first keyword, which is all that can be told without understanding the rest (gh-344)."
+          "description": "What kind of statement this is, when the sender could not normalise it safely. Its presence is the reason the text is absent: `product.md:104` says a query the normaliser does not understand travels «only as hash and class», and this is the class. Never sent together with `text` — they are two answers to the same question. Our word and not the service's: it is decided from the first keyword, which is all that can be told without understanding the rest (gh-344)."
         }
       },
       "not": {
@@ -505,6 +568,16 @@
           "class": {},
           "text": {}
         }
+      },
+      "if": {
+        "properties": {
+          "kind": { "enum": ["call", "command"] }
+        }
+      },
+      "then": {
+        "properties": {
+          "text": { "type": "string", "pattern": "^[A-Z][A-Z0-9._-]* [^\\s/?#]+$" }
+        }
       }
     },
     "ObserverState": {
@@ -580,11 +653,12 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["kind", "hash", "count"],
-      "description": "Something thrown outside any instrumented operation: an exception nobody caught, or a promise rejected with no `catch`. `product.md:77` asks for «errores **y excepciones**», and these are the two the word «excepciones» names. They live on the batch and not in the profile because they have **no route** — they happen outside a request's life, or after it ended — and filing them under a route that is not theirs would be worse than not having them (gh-341, ADR 0102).",
+      "description": "Something thrown outside any instrumented operation: an exception nobody caught, or a promise rejected with no `catch`. `product.md:77` asks for «errors and exceptions», and these are the two the word «excepciones» names. They live on the batch and not in the profile because they have **no route** — they happen outside a request's life, or after it ended — and filing them under a route that is not theirs would be worse than not having them (gh-341, ADR 0102).",
       "properties": {
         "kind": {
-          "enum": ["uncaught", "unhandled-rejection"],
-          "description": "Which of the two. Two different failures with two different fixes: counting them together hides which one is happening."
+          "enum": ["uncaught", "unhandled-rejection", "framework", "explicit"],
+          "x-since": { "uncaught": "0.7.0", "unhandled-rejection": "0.7.0", "framework": "0.9.0", "explicit": "0.9.0" },
+          "description": "How the process came to see it. `uncaught` and `unhandled-rejection` are two different failures with two different fixes, and counting them together hides which one is happening. `explicit` is an error the application handed over while no request was being served, and `framework` one that reached a framework's error path outside any observed request — a process that is not opening request contexts at all (ERR-02). `x-since` says which minor first carries each value."
         },
         "hash": {
           "type": "string",
@@ -600,10 +674,26 @@
         "count": {
           "type": "integer",
           "minimum": 1,
-          "description": "How many times this signature happened. An instant per occurrence would be a row per crash of a process that crashes in a loop; what a reader asks is how many."
+          "description": "How many times this signature happened since the last delivery this sender heard land. An instant per occurrence would be a row per crash of a process that crashes in a loop; what a reader asks is how many."
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Since 0.9.0: how many times this signature has happened in this instance since it started, a running total every delivery of the signature carries again. It is what lets the cloud tell a delivery it already applied from one that happened again (gh-625): `total - count` is what the sender knows was applied, the cloud keeps the largest total it applied per instance and signature, and it counts only what this delivery adds beyond both — so a delivery sent again after its answer was lost, sent twice, or overtaken by a later one adds nothing, and one that never arrived is counted by the next. It never goes down while `instance.id` stays the same, which is why that id is generated once per process. Absent from every sender older than this, and from a signature past the number a sender keeps totals for: the cloud then counts `count` as delivered, and says so."
+        },
+        "context": {
+          "$ref": "#/$defs/ReportedContext"
         }
       }
     },
+    "ReportedContext": {
+      "title": "ReportedContext",
+      "type": "object",
+      "maxProperties": 8,
+      "propertyNames": { "maxLength": 32 },
+      "additionalProperties": { "type": "string", "maxLength": 64 },
+      "description": "The structural context an application attached to an error it reported (ERR-02, since 0.9.0). Flat and small on purpose: what travels is the shape of the failure, never its contents (invariant 5). Every value has been through the same sanitising as an error message before it got here, so anything that looked like a value is already a `?`, and there is nothing per user in it (IMP-01). It is the context of the **first** occurrence of the signature in this window, because what travels is counted per signature and not per occurrence. Absent is the normal case: an error nobody attached a context to carries none."
+    },
     "LocalTrigger": {
       "type": "object",
       "title": "LocalTrigger",
@@ -664,6 +754,11 @@
           "minimum": 0,
           "description": "Errors inside the instrumentation itself, since the previous batch. It disables itself after enough of them, and a sender that has gone quiet with these climbing is not a quiet service."
         },
+        "droppedExceptions": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Exception events the instrumentation discarded because they did not fit in its caps of distinct signatures — the register's window, and the sender's accumulation while batches do not land — since the previous batch. An occurrence, never a signature: the sender cannot name what it did not admit without remembering it, and remembering is the growth the cap exists to stop. This is what happened and is gone, the same kind of number as droppedBatches, for the errors a process throws outside any request: a batch that says 32 and was handed 35 must not leave the other 3 to be read as errors that did not happen (COB-01, invariant 14)."
+        },
         "bufferBytes": {
           "type": "integer",
           "minimum": 0,
@@ -677,7 +772,7 @@
         "shed": {
           "type": "string",
           "enum": ["nothing", "fine", "profile"],
-          "description": "What the instrumentation has given up because it was costing too much, cheapest loss first. `product.md:241` asks for both halves —«se autolimita» and «lo registra como pérdida de cobertura»— and this is the second. An enum and not free text: it is ours, and it has to be comparable between senders."
+          "description": "What the instrumentation has given up because it was costing too much, cheapest loss first. `product.md:241` asks for both halves —«it throttles itself» and «records it as a loss of coverage»— and this is the second. An enum and not free text: it is ours, and it has to be comparable between senders."
         },
         "shedReason": {
           "type": "string",

package/schema/v0/capture-evidence.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://downtrace.io/schema/v0/capture-evidence.schema.json",
   "title": "CaptureEvidence",
-  "description": "What an instrumentation sends back for a capture the cloud asked for (POST /v0/captures/{id}/evidence). It is the contents of the black box's fine register, frozen: requests with their operations, in order, with starts and ends. Hashes only — the text of a query never travels here (invariant 5). Its own path and not the aggregates batch, because a batch is what goes out every ten seconds and this is a rare event several orders of magnitude larger.",
+  "description": "What an instrumentation sends back for a capture the cloud asked for (POST /v0/captures/{id}/evidence). It is the contents of the black box, frozen: the fine register's requests with their operations, in order, with starts and ends, and the coarse summary of the previous minutes, second by second. Hashes only — the text of a query never travels here (invariant 5). Its own path and not the aggregates batch, because a batch is what goes out every ten seconds and this is a rare event several orders of magnitude larger.",
   "x-evidence-path": "/v0/captures/{id}/evidence",
   "type": "object",
   "additionalProperties": false,
@@ -11,7 +11,7 @@
     "protocol": {
       "type": "string",
       "description": "Protocol version this payload conforms to. Same enum as a batch: every published minor of v0 stays acceptable.",
-      "enum": ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.7.0"]
+      "enum": ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.7.0", "0.8.0", "0.9.0"]
     },
     "instance": {
       "type": "object",
@@ -57,6 +57,9 @@
     },
     "reference": {
       "$ref": "#/$defs/Reference"
+    },
+    "coarse": {
+      "$ref": "#/$defs/CoarseSummary"
     }
   },
   "$defs": {
@@ -86,6 +89,33 @@
           "type": "integer",
           "minimum": 0,
           "description": "Requests that ran more operations than the register keeps per request. Their count is real and their list is not complete."
+        },
+        "shed": {
+          "$ref": "#/$defs/Shed"
+        },
+        "dependenciesTruncated": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Requests whose list of dependencies was truncated. Their count is real and their list is not complete."
+        }
+      }
+    },
+    "Shed": {
+      "type": "object",
+      "title": "Shed",
+      "additionalProperties": false,
+      "required": ["ms", "reason"],
+      "description": "The time inside [startedAt, endedAt] when the instrumentation was not writing the fine detail — neither the register's ring nor the reserve — because it was shedding it. Present when some part of the window was shed, absent when there was no shedding, when the shedding came from configuration (`DOWNTRACE_SHED`, the benchmark) and so the instrumentation never decided it, or when the instrumentation predates the field: a sender older than the field sends nothing, and the cloud stores the absence as such (ADR 0008). The capture is still taken, not refused: the window can end before the shedding does, the coarse register keeps measuring, and the protocol has no way for an instance to refuse an order — saying it in the evidence is what CAP-01 asks for.",
+      "properties": {
+        "ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How long the shedding lasted, in whole milliseconds, rounded up: one millisecond of shedding is still shedding, and the field says so rather than rounding it into silence."
+        },
+        "reason": {
+          "type": "string",
+          "enum": ["latency", "memory"],
+          "description": "The last reason in force inside the window, the same enum as `agent.resources.shedReason` in the batch: why it gave ground. One value and not a list: a window that shed for two reasons is read as the one in force when it ended, which is the one still changing what arrives."
         }
       }
     },
@@ -118,6 +148,11 @@
           "type": "number",
           "minimum": 0
         },
+        "poolWaitMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "How long this request waited for a connection from a pool before it could talk to the dependency at all. **Absent means this request asked no pool**, which is not a wait of zero: zero is a request that asked and was served at once. The pool-saturation trigger compares wait per request, so a route that never queues must not read as one that queues for nothing (invariant 14)."
+        },
         "operations": {
           "type": "array",
           "maxItems": 256,
@@ -133,6 +168,10 @@
         "detailLost": {
           "type": "boolean",
           "description": "This request's operations were overwritten before they were read. Absent means false. Its timing is still true."
+        },
+        "dependenciesTruncated": {
+          "type": "boolean",
+          "description": "This request's list of dependencies did not fit and was truncated to what the register keeps per request. A dependency not in the list is not proven not to have been used (invariant 14). Absent means false."
         }
       }
     },
@@ -143,6 +182,10 @@
       "required": ["hash", "startMs", "endMs"],
       "description": "One operation inside a request. Starts and ends and not durations, because the whole reason for capturing detail is order and overlap, which a duration cannot express (ADR 0068).",
       "properties": {
+        "kind": {
+          "enum": ["query", "error", "framework", "explicit", "call", "command"],
+          "description": "What kind of operation this is, in the words of the batch's `Operation.kind`, whose enum this borrows: a query, an outgoing call or a Redis command the request ran, or one of the kinds of error recorded in it beside what failed. Since 0.9.0. **Absent means the sender did not say**, never a query: an instrumentation older than the field wrote every operation it recorded here without one, the error signatures beside a failed query among them, and a reader that took them for queries would be naming what it was not told."
+        },
         "hash": {
           "type": "string",
           "minLength": 1,
@@ -165,7 +208,7 @@
       "title": "ReferenceSamples",
       "additionalProperties": false,
       "required": ["selection", "population", "samples"],
-      "description": "A few requests of each endpoint kept as something to compare the captured ones against. `product.md:100`: «Comparar requests degradadas con requests de referencia exige conservar ambas; el detalle fino de hace una hora ya no existe». Being earlier does not certify health, which is why every field here is about how they were chosen and none of them says «healthy».",
+      "description": "A few requests of each endpoint kept as something to compare the captured ones against. `product.md:100`: «Comparing degraded requests against reference requests requires keeping both; the fine detail of an hour ago no longer exists». Being earlier does not certify health, which is why every field here is about how they were chosen and none of them says «healthy».",
       "properties": {
         "selection": {
           "type": "string",
@@ -180,7 +223,7 @@
         "routesDropped": {
           "type": "integer",
           "minimum": 0,
-          "description": "Endpoints seen that the register had no room for. Counted rather than silently absent: an endpoint with no samples is not an endpoint with no traffic (invariant 14)."
+          "description": "Routes the register had no row for, folded into one shared row, counted once each. At the register's cap for how many it may remember it is a lower bound: a bounded memory does not count distinct names past its bound, and the volume of what was folded is what the shared row keeps."
         },
         "renewalPaused": {
           "type": "boolean",
@@ -195,6 +238,118 @@
           "description": "The kept requests, in the same shape as the captured ones. An empty array is a real answer: a process that has just started has nothing to compare with yet."
         }
       }
+    },
+    "CoarseSummary": {
+      "type": "object",
+      "title": "CoarseSummary",
+      "additionalProperties": false,
+      "required": ["windowSeconds", "routes", "eventLoop", "routesDropped"],
+      "description": "The coarse half of the black box, frozen: the last few minutes, second by second, so a reader can see how something detected late began (`product.md:94`). Sums and a maximum, never percentiles: the interval aggregate answers the percentile question with exactness, and this answers the shape of the change (`product.md:122`). What an older instrumentation did not send is absent from the evidence, and stored as absent.",
+      "properties": {
+        "windowSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How many seconds the summary covers: the length of the register's window, and the most any of the lists below may hold."
+        },
+        "routesDropped": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Routes the register had no row for, folded into one shared row, counted once each. At the register's cap for how many it may remember it is a lower bound: a bounded memory does not count distinct names past its bound, and the volume of what was folded is what the shared row keeps."
+        },
+        "routes": {
+          "type": "array",
+          "maxItems": 129,
+          "items": {
+            "$ref": "#/$defs/CoarseRoute"
+          },
+          "description": "One entry per route with a row of its own, the last being the shared row for what did not fit, when there is one. A route's series starts at the first second this process saw the route: before it, nobody was watching this route, and inventing silence there would say the route was quiet when the truth is that it was unwatched (invariant 14)."
+        },
+        "eventLoop": {
+          "type": "array",
+          "maxItems": 300,
+          "items": {
+            "$ref": "#/$defs/CoarseEventLoopSecond"
+          },
+          "description": "The process's event loop delay, second by second, in its own series and not attributed to any route: it is the process's, and attributing it to a route would be inventing a measurement. Only the seconds somebody sampled are here: a second with no reading says nothing about the loop, and a zero would say it was idle. An empty array is a real answer: the process had no event loop to sample, or nobody did."
+        }
+      }
+    },
+    "CoarseRoute": {
+      "type": "object",
+      "title": "CoarseRoute",
+      "additionalProperties": false,
+      "required": ["method", "route", "seconds"],
+      "properties": {
+        "method": {
+          "type": "string",
+          "maxLength": 16
+        },
+        "route": {
+          "type": "string",
+          "maxLength": 512,
+          "description": "The route template, never the path with its values in it (invariant 5)."
+        },
+        "seconds": {
+          "type": "array",
+          "maxItems": 300,
+          "items": {
+            "$ref": "#/$defs/CoarseSecond"
+          }
+        }
+      }
+    },
+    "CoarseSecond": {
+      "type": "object",
+      "title": "CoarseSecond",
+      "additionalProperties": false,
+      "required": ["second", "requests", "errors", "latencySumMs", "latencyMaxMs", "calls"],
+      "description": "One second of one route. Sums and a maximum, never a histogram: a histogram per second per route would multiply the memory by its buckets to answer a question the interval already answers.",
+      "properties": {
+        "second": {
+          "type": "integer",
+          "description": "The Unix second this row covers, an integer instant like the ones a batch writes: a reader aligns it with the dates the evidence writes by flooring them."
+        },
+        "requests": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Requests this route answered in this second. Zero is a real answer: a watched second with no traffic, and not an absence."
+        },
+        "errors": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Requests that answered 5xx."
+        },
+        "latencySumMs": {
+          "type": "number",
+          "minimum": 0
+        },
+        "latencyMaxMs": {
+          "type": "number",
+          "minimum": 0
+        },
+        "calls": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Operations the requests of this second ran."
+        }
+      }
+    },
+    "CoarseEventLoopSecond": {
+      "type": "object",
+      "title": "CoarseEventLoopSecond",
+      "additionalProperties": false,
+      "required": ["second", "maxDelayMs"],
+      "properties": {
+        "second": {
+          "type": "integer",
+          "description": "The Unix second this reading covers."
+        },
+        "maxDelayMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "The worst delay sampled in this second: a second that stalled once stalled, and averaging it away is how a stall becomes invisible."
+        }
+      }
     }
   }
 }

package/schema/v0/fixtures/evidence/invalid/coarse-second-without-its-calls.json

@@ -0,0 +1,20 @@
+{
+  "protocol": "0.9.0",
+  "instance": { "id": "i-1" },
+  "startedAt": "2026-09-10T10:04:00.000Z",
+  "endedAt": "2026-09-10T10:05:00.000Z",
+  "coverage": { "observedRequests": 1, "attachedRequests": 0, "detailLost": 0, "truncated": 0 },
+  "requests": [],
+  "coarse": {
+    "windowSeconds": 300,
+    "routesDropped": 0,
+    "routes": [
+      {
+        "method": "GET",
+        "route": "/checkout",
+        "seconds": [{ "second": 1757517900, "requests": 4, "errors": 0, "latencySumMs": 48.2, "latencyMaxMs": 12.1 }]
+      }
+    ],
+    "eventLoop": []
+  }
+}

package/schema/v0/fixtures/evidence/invalid/dependencies-truncated-negative.json

@@ -0,0 +1,14 @@
+{
+  "protocol": "0.9.0",
+  "instance": { "id": "i-1" },
+  "startedAt": "2026-09-10T10:00:00.000Z",
+  "endedAt": "2026-09-10T10:01:00.000Z",
+  "coverage": {
+    "observedRequests": 1,
+    "attachedRequests": 0,
+    "detailLost": 0,
+    "truncated": 0,
+    "dependenciesTruncated": -1
+  },
+  "requests": []
+}

package/schema/v0/fixtures/evidence/invalid/dependencies-truncated-not-a-boolean.json

@@ -0,0 +1,24 @@
+{
+  "protocol": "0.9.0",
+  "instance": { "id": "i-1" },
+  "startedAt": "2026-09-10T10:00:00.000Z",
+  "endedAt": "2026-09-10T10:01:00.000Z",
+  "coverage": {
+    "observedRequests": 1,
+    "attachedRequests": 0,
+    "detailLost": 0,
+    "truncated": 0,
+    "dependenciesTruncated": 1
+  },
+  "requests": [
+    {
+      "method": "GET",
+      "route": "/cart",
+      "status": 200,
+      "startedAt": "2026-09-10T09:59:58.900Z",
+      "durationMs": 88,
+      "operations": [],
+      "dependenciesTruncated": "true"
+    }
+  ]
+}

package/schema/v0/fixtures/evidence/invalid/operation-of-an-unknown-kind.json

@@ -0,0 +1,33 @@
+{
+  "protocol": "0.9.0",
+  "instance": {
+    "id": "7d1e9c6a-4f2b-4c1e-9b0a-2f6d3e8a1c55",
+    "hostname": "web-1",
+    "pid": 4242
+  },
+  "startedAt": "2026-09-10T10:00:00.000Z",
+  "endedAt": "2026-09-10T10:01:00.000Z",
+  "coverage": {
+    "observedRequests": 1,
+    "attachedRequests": 0,
+    "detailLost": 0,
+    "truncated": 0
+  },
+  "requests": [
+    {
+      "method": "POST",
+      "route": "/checkout",
+      "status": 200,
+      "startedAt": "2026-09-10T10:00:03.120Z",
+      "durationMs": 250,
+      "operations": [
+        {
+          "kind": "timeout",
+          "hash": "3e1f0a9c5b7d2468",
+          "startMs": 40,
+          "endMs": 240
+        }
+      ]
+    }
+  ]
+}

package/schema/v0/fixtures/evidence/invalid/shed-with-an-extra-field.json

@@ -0,0 +1,14 @@
+{
+  "protocol": "0.9.0",
+  "instance": { "id": "i-1" },
+  "startedAt": "2026-09-10T10:00:00.000Z",
+  "endedAt": "2026-09-10T10:01:00.000Z",
+  "coverage": {
+    "observedRequests": 0,
+    "attachedRequests": 0,
+    "detailLost": 0,
+    "truncated": 0,
+    "shed": { "ms": 60000, "reason": "latency", "since": "2026-09-10T10:00:00.000Z" }
+  },
+  "requests": []
+}

package/schema/v0/fixtures/evidence/invalid/shed-with-unknown-reason.json

@@ -0,0 +1,14 @@
+{
+  "protocol": "0.9.0",
+  "instance": { "id": "i-1" },
+  "startedAt": "2026-09-10T10:00:00.000Z",
+  "endedAt": "2026-09-10T10:01:00.000Z",
+  "coverage": {
+    "observedRequests": 0,
+    "attachedRequests": 0,
+    "detailLost": 0,
+    "truncated": 0,
+    "shed": { "ms": 60000, "reason": "cpu" }
+  },
+  "requests": []
+}

package/schema/v0/fixtures/evidence/invalid/shed-with-zero-ms.json

@@ -0,0 +1,14 @@
+{
+  "protocol": "0.9.0",
+  "instance": { "id": "i-1" },
+  "startedAt": "2026-09-10T10:00:00.000Z",
+  "endedAt": "2026-09-10T10:01:00.000Z",
+  "coverage": {
+    "observedRequests": 0,
+    "attachedRequests": 0,
+    "detailLost": 0,
+    "truncated": 0,
+    "shed": { "ms": 0, "reason": "latency" }
+  },
+  "requests": []
+}

package/schema/v0/fixtures/evidence/valid/with-coarse.json

@@ -0,0 +1,40 @@
+{
+  "protocol": "0.9.0",
+  "instance": { "id": "7d1e9c6a-4f2b-4c1e-9b0a-2f6d3e8a1c55" },
+  "startedAt": "2026-09-10T10:04:00.000Z",
+  "endedAt": "2026-09-10T10:05:00.000Z",
+  "coverage": { "observedRequests": 3, "attachedRequests": 1, "detailLost": 0, "truncated": 0 },
+  "requests": [
+    {
+      "method": "GET",
+      "route": "/checkout",
+      "status": 500,
+      "startedAt": "2026-09-10T10:04:31.000Z",
+      "durationMs": 912.4,
+      "operations": []
+    }
+  ],
+  "coarse": {
+    "windowSeconds": 300,
+    "routesDropped": 0,
+    "routes": [
+      {
+        "method": "GET",
+        "route": "/checkout",
+        "seconds": [
+          { "second": 1757517900, "requests": 4, "errors": 0, "latencySumMs": 48.2, "latencyMaxMs": 12.1, "calls": 8 },
+          { "second": 1757517901, "requests": 0, "errors": 0, "latencySumMs": 0, "latencyMaxMs": 0, "calls": 0 },
+          {
+            "second": 1757517902,
+            "requests": 7,
+            "errors": 2,
+            "latencySumMs": 910.5,
+            "latencyMaxMs": 431.9,
+            "calls": 21
+          }
+        ]
+      }
+    ],
+    "eventLoop": [{ "second": 1757517901, "maxDelayMs": 0.8 }, { "second": 1757517902, "maxDelayMs": 250.4 }]
+  }
+}