@downtrace/protocol 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -11,6 +11,14 @@ declare function captureEvidencePath(id: string): string;
  * Whether an observer is attached (`on`), was not asked for (`off`), or was asked for and could not attach (`unavailable`) — a driver that is not resolvable from the application's root, for instance. The third one is the point: without it, a service that is not being watched looks exactly like a service that has nothing to watch (COB-01, invariant 14).
  */
 type ObserverState = "on" | "off" | "unavailable";
+/**
+ * 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.
+ */
+type InRequestErrorSource = "error" | "framework" | "explicit";
+/**
+ * A value of `ProcessException.kind`: the ways an error outside any request arrives, and so the sources that can produce one.
+ */
+type OutsideRequestErrorSource = "uncaught" | "unhandled-rejection" | "framework" | "explicit";
 /**
  * A batch of per-interval, per-route aggregates sent by an agent to the cloud (POST /v0/aggregates).
  */
@@ -18,12 +26,12 @@ interface AggregatesBatch {
   /**
    * Protocol version this batch conforms to. Every published minor of v0 stays acceptable.
    */
-  protocol: "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.7.0" | "0.8.0";
+  protocol: "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" | "0.10.0";
   agent: AgentInfo;
   instance: InstanceInfo;
   deploy: DeployInfo;
   /**
-   * 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.
+   * 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.
    *
    * @minItems 0
    * @maxItems 6
@@ -43,11 +51,15 @@ interface AggregatesBatch {
    */
   exceptions?: ProcessException[];
   /**
-   * 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.
+   * 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.
    *
    * @maxItems 4
    */
   triggers?: [] | [LocalTrigger] | [LocalTrigger, LocalTrigger] | [LocalTrigger, LocalTrigger, LocalTrigger] | [LocalTrigger, LocalTrigger, LocalTrigger, LocalTrigger];
+  /**
+   * 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` — 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 — from outside, every ending looks like batches stopping — and it carries no instant, because the one that matters is when the batch arrived, which the cloud measures.
+   */
+  ending?: "signal" | "exit" | "idle";
 }
 interface AgentInfo {
   name: string;
@@ -57,6 +69,7 @@ interface AgentInfo {
   observers?: Observers;
   withholding?: Withholding;
   resources?: AgentResources;
+  errorSources?: ErrorSources;
 }
 /**
  * Absent from an instrumentation older than protocol 0.7.0. Absent is not 'nothing is observed': it is 'this one did not say', and the two must not be shown alike.
@@ -85,7 +98,7 @@ interface Withholding {
   dependencies?: number;
 }
 /**
- * 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».
+ * 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».
  */
 interface AgentResources {
   /**
@@ -104,6 +117,10 @@ interface AgentResources {
    * 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.
    */
   internalErrors?: number;
+  /**
+   * 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).
+   */
+  droppedExceptions?: number;
   /**
    * What the black box's registers have allocated, right now. An instant, and arithmetic rather than a measurement: the rings are preallocated.
    */
@@ -113,7 +130,7 @@ interface AgentResources {
    */
   hookMsPerRequest?: number;
   /**
-   * 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.
+   * 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.
    */
   shed?: "nothing" | "fine" | "profile";
   /**
@@ -121,6 +138,19 @@ interface AgentResources {
    */
   shedReason?: "latency" | "memory";
 }
+/**
+ * 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.
+ */
+interface ErrorSources {
+  /**
+   * 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.
+   */
+  inRequest: InRequestErrorSource[];
+  /**
+   * 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.
+   */
+  outsideRequest: OutsideRequestErrorSource[];
+}
 interface InstanceInfo {
   /**
    * Random identifier generated once per process.
@@ -151,7 +181,7 @@ interface Interval {
 interface Endpoint {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "OTHER";
   /**
-   * Normalised route template, e.g. /products/:id, or (other).
+   * Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56).
    */
   route: string;
   count: number;
@@ -230,9 +260,9 @@ interface PostgresStats {
  */
 interface Dependency {
   /**
-   * What kind of dependency this is.
+   * What kind of dependency this is. `mongodb` since 0.10.0: a MongoDB database, whose commands are operations of kind `query` named by the command and the collection (`find users`).
    */
-  kind: "postgres" | "mysql" | "redis" | "http";
+  kind: "postgres" | "mysql" | "mongodb" | "redis" | "http";
   /**
    * Host for outgoing HTTP (`api.stripe.com`); empty when the dependency is a single one, like the application's own database.
    */
@@ -320,7 +350,7 @@ interface Profile {
 interface ProfileEndpoint {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "OTHER";
   /**
-   * Normalised route template, e.g. /products/:id, or (other).
+   * Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56).
    */
   route: string;
   /**
@@ -333,15 +363,15 @@ interface ProfileEndpoint {
  */
 interface Operation {
   /**
-   * What kind of operation this is.
+   * 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).
    */
-  kind: "query" | "error";
+  kind: "query" | "error" | "framework" | "explicit" | "call" | "command";
   /**
    * Stable identity of the operation, or `(other)` for the bucket that holds the rest.
    */
   hash: string;
   /**
-   * 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.
+   * Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `find users` for a MongoDB command — its name and its collection, never the filter or the documents —, `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.
    */
   text?: string;
   /**
@@ -360,11 +390,18 @@ interface Operation {
    * Only on the `(other)` bucket: how many distinct operations it merges, so a cap does not become a lie by omission.
    */
   distinct?: number;
+  context?: ReportedContext;
   /**
-   * 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).
+   * 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).
    */
   class?: "select" | "insert" | "update" | "delete" | "other";
 }
+/**
+ * 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.
+ */
+interface ReportedContext {
+  [k: string]: string;
+}
 /**
  * What the instrumentation has to say about a capture the cloud asked it for. The order travels in the ingest response (ADR 0071) and the answer travels here, on the same cadence and at the same cost: a path of its own would be one more call per capture, and one more thing to authenticate, for a fact that fits in the batch that is already going (gh-378).
  */
@@ -379,13 +416,13 @@ interface CaptureProgress {
   startedAt: number;
 }
 /**
- * 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).
+ * 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).
  */
 interface ProcessException {
   /**
-   * Which of the two. Two different failures with two different fixes: counting them together hides which one is happening.
+   * 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.
    */
-  kind: "uncaught" | "unhandled-rejection";
+  kind: "uncaught" | "unhandled-rejection" | "framework" | "explicit";
   /**
    * Stable identity of the signature, the same shape a query's or an operation error's has (ADR 0017).
    */
@@ -395,9 +432,14 @@ interface ProcessException {
    */
   text?: string;
   /**
-   * 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.
+   * 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.
    */
   count: number;
+  /**
+   * 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.
+   */
+  total?: number;
+  context?: ReportedContext;
 }
 /**
  * One local signal, sustained past its threshold. It asks for detail; it does not claim a cause (invariant 7).
@@ -435,15 +477,23 @@ declare const CALLS_PER_REQUEST_BOUNDARIES_V0: readonly number[];
 /** Number of calls-per-request buckets: boundaries + 1 open-ended bucket. */
 declare const CALLS_PER_REQUEST_BUCKETS_V0 = 8;
 //#endregion
+//#region src/generated/caps.d.ts
+/** The most dependencies one endpoint may carry in a batch. */
+declare const DEPENDENCIES_MAX_ITEMS_V0 = 64;
+/** The most requests a capture's evidence may carry: the ring is sized as this minus the reserves' room (gh-901). */
+declare const EVIDENCE_REQUESTS_MAX_ITEMS_V0 = 4096;
+/** The dependency kinds the schema names, in the order it names them. */
+declare const DEPENDENCY_KINDS_V0: readonly ["postgres", "mysql", "mongodb", "redis", "http"];
+//#endregion
 //#region src/generated/capture-evidence.d.ts
 /**
- * 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.
+ * 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.
  */
 interface CaptureEvidence {
   /**
    * Protocol version this payload conforms to. Same enum as a batch: every published minor of v0 stays acceptable.
    */
-  protocol: "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.7.0" | "0.8.0";
+  protocol: "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" | "0.10.0";
   /**
    * Which process observed this. Several instances of one deployment get the same order on purpose (ADR 0071), so the cloud has to be able to tell two answers apart.
    */
@@ -468,6 +518,7 @@ interface CaptureEvidence {
    */
   requests: CapturedRequest[];
   reference?: ReferenceSamples;
+  coarse?: CoarseSummary;
 }
 /**
  * `product.md:192` asks a capture to declare **both** coverages: what it attached from detail still retained, and what it observed from its effective start. Two numbers, never one — a total would hide that half of it is older than the capture.
@@ -489,6 +540,24 @@ interface CaptureCoverage {
    * Requests that ran more operations than the register keeps per request. Their count is real and their list is not complete.
    */
   truncated: number;
+  shed?: Shed;
+  /**
+   * Requests whose list of dependencies was truncated. Their count is real and their list is not complete. A sender that knows the field sends it, zero included. Absent in an evidence of protocol 0.9.0 or later is zero: @downtrace/agent 0.9.0 omitted it at zero. Absent in an earlier protocol is a sender older than the field, which did not say, and that is not none.
+   */
+  dependenciesTruncated?: number;
+}
+/**
+ * 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.
+ */
+interface Shed {
+  /**
+   * 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.
+   */
+  ms: number;
+  /**
+   * 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.
+   */
+  reason: "latency" | "memory";
 }
 interface CapturedRequest {
   method: string;
@@ -520,11 +589,19 @@ interface CapturedRequest {
    * This request's operations were overwritten before they were read. Absent means false. Its timing is still true.
    */
   detailLost?: boolean;
+  /**
+   * 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.
+   */
+  dependenciesTruncated?: boolean;
 }
 /**
  * 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).
  */
 interface CapturedOperation {
+  /**
+   * 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.
+   */
+  kind?: "query" | "error" | "framework" | "explicit" | "call" | "command";
   /**
    * The fingerprint's hash. Never the text: the profile is where a sender chooses whether to ship the text of its queries, and this path never carries it (invariant 5, ADR 0017).
    */
@@ -536,7 +613,7 @@ interface CapturedOperation {
   endMs: number;
 }
 /**
- * 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».
+ * 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».
  */
 interface ReferenceSamples {
   /**
@@ -548,7 +625,7 @@ interface ReferenceSamples {
    */
   population: number;
   /**
-   * 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).
+   * 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.
    */
   routesDropped?: number;
   /**
@@ -562,6 +639,75 @@ interface ReferenceSamples {
    */
   samples: CapturedRequest[];
 }
+/**
+ * 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.
+ */
+interface CoarseSummary {
+  /**
+   * How many seconds the summary covers: the length of the register's window, and the most any of the lists below may hold.
+   */
+  windowSeconds: number;
+  /**
+   * 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.
+   */
+  routesDropped: number;
+  /**
+   * 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).
+   *
+   * @maxItems 129
+   */
+  routes: CoarseRoute[];
+  /**
+   * 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.
+   *
+   * @maxItems 300
+   */
+  eventLoop: CoarseEventLoopSecond[];
+}
+interface CoarseRoute {
+  method: string;
+  /**
+   * The route template, never the path with its values in it (invariant 5).
+   */
+  route: string;
+  /**
+   * @maxItems 300
+   */
+  seconds: CoarseSecond[];
+}
+/**
+ * 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.
+ */
+interface CoarseSecond {
+  /**
+   * 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.
+   */
+  second: number;
+  /**
+   * Requests this route answered in this second. Zero is a real answer: a watched second with no traffic, and not an absence.
+   */
+  requests: number;
+  /**
+   * Requests that answered 5xx.
+   */
+  errors: number;
+  latencySumMs: number;
+  latencyMaxMs: number;
+  /**
+   * Operations the requests of this second ran.
+   */
+  calls: number;
+}
+interface CoarseEventLoopSecond {
+  /**
+   * The Unix second this reading covers.
+   */
+  second: number;
+  /**
+   * The worst delay sampled in this second: a second that stalled once stalled, and averaging it away is how a stall becomes invisible.
+   */
+  maxDelayMs: number;
+}
 //#endregion
 //#region src/generated/ingest-response.d.ts
 /**
@@ -620,9 +766,9 @@ interface PendingCapture {
 //#endregion
 //#region src/generated/versions.d.ts
 /** Every published minor of v0, oldest first. The cloud never stops accepting one it published (ADR 0008). */
-declare const ACCEPTED_PROTOCOL_VERSIONS_V0: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.7.0", "0.8.0"];
+declare const ACCEPTED_PROTOCOL_VERSIONS_V0: readonly ["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", "0.10.0"];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-declare const PROTOCOL_VERSION = "0.8.0";
+declare const PROTOCOL_VERSION = "0.10.0";
 //#endregion
 //#region src/index.d.ts
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
@@ -686,6 +832,10 @@ declare const AGGREGATES_SCHEMA_V0: {
       };
       description: string;
     };
+    ending: {
+      enum: string[];
+      description: string;
+    };
   };
   $defs: {
     AgentInfo: {
@@ -724,8 +874,48 @@ declare const AGGREGATES_SCHEMA_V0: {
           $ref: string;
           description: string;
         };
+        errorSources: {
+          $ref: string;
+          description: string;
+        };
+      };
+    };
+    ErrorSources: {
+      title: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        inRequest: {
+          type: string;
+          uniqueItems: boolean;
+          items: {
+            $ref: string;
+          };
+          description: string;
+        };
+        outsideRequest: {
+          type: string;
+          uniqueItems: boolean;
+          items: {
+            $ref: string;
+          };
+          description: string;
+        };
       };
     };
+    InRequestErrorSource: {
+      title: string;
+      type: string;
+      enum: string[];
+      description: string;
+    };
+    OutsideRequestErrorSource: {
+      title: string;
+      type: string;
+      enum: string[];
+      description: string;
+    };
     InstanceInfo: {
       title: string;
       type: string;
@@ -1086,6 +1276,22 @@ declare const AGGREGATES_SCHEMA_V0: {
       properties: {
         kind: {
           enum: string[];
+          "x-since": {
+            query: string;
+            error: string;
+            framework: string;
+            explicit: string;
+            call: string;
+            command: string;
+          };
+          "x-error": {
+            query: boolean;
+            error: boolean;
+            framework: boolean;
+            explicit: boolean;
+            call: boolean;
+            command: boolean;
+          };
           description: string;
         };
         hash: {
@@ -1119,6 +1325,9 @@ declare const AGGREGATES_SCHEMA_V0: {
           minimum: number;
           description: string;
         };
+        context: {
+          $ref: string;
+        };
         class: {
           enum: string[];
           description: string;
@@ -1131,6 +1340,21 @@ declare const AGGREGATES_SCHEMA_V0: {
           text: {};
         };
       };
+      if: {
+        properties: {
+          kind: {
+            enum: string[];
+          };
+        };
+      };
+      then: {
+        properties: {
+          text: {
+            type: string;
+            pattern: string;
+          };
+        };
+      };
     };
     ObserverState: {
       title: string;
@@ -1209,6 +1433,12 @@ declare const AGGREGATES_SCHEMA_V0: {
       properties: {
         kind: {
           enum: string[];
+          "x-since": {
+            uncaught: string;
+            "unhandled-rejection": string;
+            framework: string;
+            explicit: string;
+          };
           description: string;
         };
         hash: {
@@ -1227,7 +1457,28 @@ declare const AGGREGATES_SCHEMA_V0: {
           minimum: number;
           description: string;
         };
+        total: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        context: {
+          $ref: string;
+        };
+      };
+    };
+    ReportedContext: {
+      title: string;
+      type: string;
+      maxProperties: number;
+      propertyNames: {
+        maxLength: number;
       };
+      additionalProperties: {
+        type: string;
+        maxLength: number;
+      };
+      description: string;
     };
     LocalTrigger: {
       type: string;
@@ -1289,6 +1540,11 @@ declare const AGGREGATES_SCHEMA_V0: {
           minimum: number;
           description: string;
         };
+        droppedExceptions: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
         bufferBytes: {
           type: string;
           minimum: number;
@@ -1463,6 +1719,9 @@ declare const CAPTURE_EVIDENCE_SCHEMA_V0: {
     reference: {
       $ref: string;
     };
+    coarse: {
+      $ref: string;
+    };
   };
   $defs: {
     Coverage: {
@@ -1492,6 +1751,33 @@ declare const CAPTURE_EVIDENCE_SCHEMA_V0: {
           minimum: number;
           description: string;
         };
+        shed: {
+          $ref: string;
+        };
+        dependenciesTruncated: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+      };
+    };
+    Shed: {
+      type: string;
+      title: string;
+      additionalProperties: boolean;
+      required: string[];
+      description: string;
+      properties: {
+        ms: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        reason: {
+          type: string;
+          enum: string[];
+          description: string;
+        };
       };
     };
     CapturedRequest: {
@@ -1544,6 +1830,10 @@ declare const CAPTURE_EVIDENCE_SCHEMA_V0: {
           type: string;
           description: string;
         };
+        dependenciesTruncated: {
+          type: string;
+          description: string;
+        };
       };
     };
     CapturedOperation: {
@@ -1553,6 +1843,10 @@ declare const CAPTURE_EVIDENCE_SCHEMA_V0: {
       required: string[];
       description: string;
       properties: {
+        kind: {
+          enum: string[];
+          description: string;
+        };
         hash: {
           type: string;
           minLength: number;
@@ -1606,6 +1900,118 @@ declare const CAPTURE_EVIDENCE_SCHEMA_V0: {
         };
       };
     };
+    CoarseSummary: {
+      type: string;
+      title: string;
+      additionalProperties: boolean;
+      required: string[];
+      description: string;
+      properties: {
+        windowSeconds: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        routesDropped: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        routes: {
+          type: string;
+          maxItems: number;
+          items: {
+            $ref: string;
+          };
+          description: string;
+        };
+        eventLoop: {
+          type: string;
+          maxItems: number;
+          items: {
+            $ref: string;
+          };
+          description: string;
+        };
+      };
+    };
+    CoarseRoute: {
+      type: string;
+      title: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        method: {
+          type: string;
+          maxLength: number;
+        };
+        route: {
+          type: string;
+          maxLength: number;
+          description: string;
+        };
+        seconds: {
+          type: string;
+          maxItems: number;
+          items: {
+            $ref: string;
+          };
+        };
+      };
+    };
+    CoarseSecond: {
+      type: string;
+      title: string;
+      additionalProperties: boolean;
+      required: string[];
+      description: string;
+      properties: {
+        second: {
+          type: string;
+          description: string;
+        };
+        requests: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        errors: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        latencySumMs: {
+          type: string;
+          minimum: number;
+        };
+        latencyMaxMs: {
+          type: string;
+          minimum: number;
+        };
+        calls: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+      };
+    };
+    CoarseEventLoopSecond: {
+      type: string;
+      title: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        second: {
+          type: string;
+          description: string;
+        };
+        maxDelayMs: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+      };
+    };
   };
 };
 /** Index of the bucket a latency (ms) falls into: first boundary >= latency, else the open-ended last bucket. */
@@ -1613,4 +2019,4 @@ declare function latencyBucket(ms: number): number;
 /** Index of the bucket a call count falls into: first boundary >= count, else the open-ended last bucket. */
 declare function callsPerRequestBucket(calls: number): number;
 //#endregion
-export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, type AgentInfo, type AgentResources, type AggregatesBatch, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, CAPTURE_EVIDENCE_PATH, CAPTURE_EVIDENCE_SCHEMA_V0, type CaptureCoverage, type CaptureEvidence, type CaptureProgress, type CapturedOperation, type CapturedRequest, type Dependency, type DeployInfo, type Endpoint, INGEST_RESPONSE_SCHEMA_V0, type IngestResponse, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, type LocalTrigger, type ObserverState, type Observers, type Operation, PROTOCOL_VERSION, type PendingCapture, type PostgresStats, type Profile, type ProfileEndpoint, type RuntimeHealth, type StatusClasses, callsPerRequestBucket, captureEvidencePath, latencyBucket };
+export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, type AgentInfo, type AgentResources, type AggregatesBatch, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, CAPTURE_EVIDENCE_PATH, CAPTURE_EVIDENCE_SCHEMA_V0, type CaptureCoverage, type CaptureEvidence, type CaptureProgress, type CapturedOperation, type CapturedRequest, DEPENDENCIES_MAX_ITEMS_V0, DEPENDENCY_KINDS_V0, type Dependency, type DeployInfo, EVIDENCE_REQUESTS_MAX_ITEMS_V0, type Endpoint, INGEST_RESPONSE_SCHEMA_V0, type IngestResponse, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, type LocalTrigger, type ObserverState, type Observers, type Operation, PROTOCOL_VERSION, type PendingCapture, type PostgresStats, type Profile, type ProfileEndpoint, type RuntimeHealth, type StatusClasses, callsPerRequestBucket, captureEvidencePath, latencyBucket };