@downtrace/protocol 0.7.1 → 0.8.0

package/README.md

@@ -26,6 +26,8 @@ Since **0.7.0** `agent` may also carry `observers`: which of `pg`, `http`, `redi
 
 Also since **0.7.0**, `RuntimeHealth` requires none of its fields and at least one of them. It used to demand all six, which made the one language-dependent corner of the protocol: a Go runtime has garbage collection, a heap and a resident set, and no event loop, so it could either invent one or send none of the three it does have. Relaxing a constraint is additive — a sender reporting all six still validates.
 
+Since **0.8.0** a captured request may carry `poolWaitMs`: how long it waited for a connection from a pool before it could talk to the dependency at all. The instrumentation measures this per request already, and a consumer that only sees the total time cannot tell a slow database from one it never got to talk to. **Absent means the request asked no pool**, which is not a wait of zero — zero is a request that asked and was served at once — and the two have to stay apart, because a route that never queues must not read as one that queues for nothing.
+
 Also since **0.7.0**, a capture's evidence has a contract of its own: `schema/v0/capture-evidence.schema.json`, exported as `CAPTURE_EVIDENCE_SCHEMA_V0` with the types `CaptureEvidence`, `CapturedRequest`, `CapturedOperation` and `CaptureCoverage`, and its path as `CAPTURE_EVIDENCE_PATH` / `captureEvidencePath(id)`. It is the black box's fine detail, frozen: requests with their operations, in order, with **starts and ends** rather than durations — order and overlap are the whole reason for capturing detail. Hashes only; the text of a query never travels here. And it declares **two coverages**, never a total: what it observed from its effective start, and what it attached from detail still retained.
 
 And since **0.7.0** that evidence may carry `reference`: a few requests per endpoint the instrumentation kept as something to compare the captured ones against, with `selection` —an enum, because a sender writing «representative» in a free string means nothing— the `population` they were drawn from, and `renewalPaused` when requests were observed that it deliberately did not consider. A sample has the same shape as a captured request. Being earlier does not make one healthy, and nothing here says it does: `product.md:100`.

package/dist/index.d.ts

@@ -18,7 +18,7 @@ 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";
+  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";
   agent: AgentInfo;
   instance: InstanceInfo;
   deploy: DeployInfo;
@@ -443,7 +443,7 @@ 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";
+  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";
   /**
    * 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.
    */
@@ -502,6 +502,10 @@ interface CapturedRequest {
    */
   startedAt: string;
   durationMs: number;
+  /**
+   * 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).
+   */
+  poolWaitMs?: number;
   /**
    * What it ran, in the order it started them. Empty means it ran nothing — unless `detailLost` says the list was overwritten, which is why that flag is on the request and not only in the totals.
    *
@@ -616,9 +620,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"];
+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"];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-declare const PROTOCOL_VERSION = "0.7.0";
+declare const PROTOCOL_VERSION = "0.8.0";
 //#endregion
 //#region src/index.d.ts
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
@@ -1519,6 +1523,11 @@ declare const CAPTURE_EVIDENCE_SCHEMA_V0: {
           type: string;
           minimum: number;
         };
+        poolWaitMs: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
         operations: {
           type: string;
           maxItems: number;

package/dist/index.js

@@ -24,7 +24,8 @@ var aggregates_schema_default = {
 				"0.4.0",
 				"0.5.0",
 				"0.6.0",
-				"0.7.0"
+				"0.7.0",
+				"0.8.0"
 			],
 			"description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
 		},
@@ -824,7 +825,8 @@ var capture_evidence_schema_default = {
 				"0.4.0",
 				"0.5.0",
 				"0.6.0",
-				"0.7.0"
+				"0.7.0",
+				"0.8.0"
 			]
 		},
 		"instance": {
@@ -938,6 +940,11 @@ var capture_evidence_schema_default = {
 					"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,
@@ -1178,10 +1185,11 @@ const ACCEPTED_PROTOCOL_VERSIONS_V0 = [
 	"0.4.0",
 	"0.5.0",
 	"0.6.0",
-	"0.7.0"
+	"0.7.0",
+	"0.8.0"
 ];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-const PROTOCOL_VERSION = "0.7.0";
+const PROTOCOL_VERSION = "0.8.0";
 //#endregion
 //#region src/index.ts
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downtrace/protocol",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Downtrace ingestion protocol: JSON Schema, fixtures and generated TypeScript types",
   "type": "module",
   "exports": {

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"],
       "description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
     },
     "agent": {

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

@@ -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"]
     },
     "instance": {
       "type": "object",
@@ -118,6 +118,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,