@downtrace/protocol 0.3.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ The ingestion contract between Downtrace agents and the Downtrace cloud, as a JS
 
 - `schema/v0/aggregates.schema.json` — the contract. Everything else derives from it.
 - `schema/v0/fixtures/{valid,invalid}/` — examples every implementation must accept and reject.
-- Exports: `PROTOCOL_VERSION`, `AGGREGATES_PATH`, `AGGREGATES_SCHEMA_V0`, `LATENCY_BOUNDARIES_V0`, `LATENCY_BUCKETS_V0`, `latencyBucket()`, `CALLS_PER_REQUEST_BOUNDARIES_V0`, `CALLS_PER_REQUEST_BUCKETS_V0`, `callsPerRequestBucket()`, and the types `AggregatesBatch`, `Interval`, `Endpoint`, `LatencyHistogram`, `Dependency`, `PostgresStats`, …
+- Exports: `PROTOCOL_VERSION`, `ACCEPTED_PROTOCOL_VERSIONS_V0`, `AGGREGATES_PATH`, `AGGREGATES_SCHEMA_V0`, `LATENCY_BOUNDARIES_V0`, `LATENCY_BUCKETS_V0`, `latencyBucket()`, `CALLS_PER_REQUEST_BOUNDARIES_V0`, `CALLS_PER_REQUEST_BUCKETS_V0`, `callsPerRequestBucket()`, and the types `AggregatesBatch`, `Interval`, `Endpoint`, `LatencyHistogram`, `Dependency`, `PostgresStats`, …
 
 ## v0 in one sentence
 
@@ -16,7 +16,9 @@ Since **0.2.0** an endpoint may also carry `postgres`: how many queries each req
 
 ## How the protocol changes
 
-Fields are only ever **added**, and always optional. Each addition bumps the minor version, and the batch's `protocol` field is an enum of every published minor, so a cloud that speaks 0.2 still accepts an agent that speaks 0.1. Removing or renaming a field, or moving a histogram's bucket bounds, would be a major version on a new path. Bucket bounds are declared in the schema itself (`x-latency-boundaries-ms`, `x-queries-per-request-boundaries`), so they are part of the generated contract rather than a constant someone has to keep in sync.
+**The package version is the protocol version.** `@downtrace/protocol@0.5.0` speaks protocol `0.5.0`, and CI refuses to publish a release where the two disagree, so you can read the contract off the version in your lockfile. A release that changes the package without touching the contract moves the patch segment only.
+
+Fields are only ever **added**, and always optional. Each addition bumps the minor version, and the batch's `protocol` field is an enum of every published minor, so a cloud that speaks 0.2 still accepts an agent that speaks 0.1. Removing or renaming a field, or moving a histogram's bucket bounds, would be a major version on a new path. Bucket bounds are declared in the schema itself (`x-latency-boundaries-ms`, `x-calls-per-request-boundaries`), and so are the versions themselves, so they are part of the generated contract rather than a constant someone has to keep in sync.
 
 ## Source
 

package/dist/index.d.ts

@@ -6,7 +6,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";
+  protocol: "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0" | "0.5.0";
   agent: AgentInfo;
   instance: InstanceInfo;
   deploy: DeployInfo;
@@ -157,6 +157,10 @@ interface Dependency {
    * Calls that failed.
    */
   errors: number;
+  /**
+   * Time requests spent waiting to be able to talk to this dependency, on top of the time spent talking to it: a saturated connection pool shows up here and nowhere else. Optional; agents that cannot see it omit it.
+   */
+  waitMs?: number;
 }
 /**
  * Health of the agent's own process during the interval. Optional: an agent that does not measure it omits it. Per interval, not per route, because it belongs to the process.
@@ -211,12 +215,13 @@ 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/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"];
+/** The newest published minor: what an up-to-date agent stamps on every batch. */
+declare const PROTOCOL_VERSION = "0.5.0";
+//#endregion
 //#region src/index.d.ts
-/**
- * Version of the ingestion protocol this package speaks. Every published minor of v0 stays acceptable to the
- * cloud, so an agent on an older minor keeps working: fields are only ever added, and always optional (ADR 0008).
- */
-declare const PROTOCOL_VERSION = "0.4.0";
 /** Path, relative to the ingest URL, that receives AggregatesBatch payloads. */
 declare const AGGREGATES_PATH = "/v0/aggregates";
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
@@ -577,6 +582,11 @@ declare const AGGREGATES_SCHEMA_V0: {
           minimum: number;
           description: string;
         };
+        waitMs: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
       };
     };
   };
@@ -586,4 +596,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 { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, type AgentInfo, type AggregatesBatch, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, type Dependency, type DeployInfo, type Endpoint, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, PROTOCOL_VERSION, type PostgresStats, type RuntimeHealth, type StatusClasses, callsPerRequestBucket, latencyBucket };
+export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, type AgentInfo, type AggregatesBatch, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, type Dependency, type DeployInfo, type Endpoint, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, PROTOCOL_VERSION, type PostgresStats, type RuntimeHealth, type StatusClasses, callsPerRequestBucket, latencyBucket };

package/dist/index.js

@@ -20,7 +20,8 @@ var aggregates_schema_default = {
 				"0.1.0",
 				"0.2.0",
 				"0.3.0",
-				"0.4.0"
+				"0.4.0",
+				"0.5.0"
 			],
 			"description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
 		},
@@ -450,6 +451,11 @@ var aggregates_schema_default = {
 					"type": "integer",
 					"minimum": 0,
 					"description": "Calls that failed."
+				},
+				"waitMs": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Time requests spent waiting to be able to talk to this dependency, on top of the time spent talking to it: a saturated connection pool shows up here and nowhere else. Optional; agents that cannot see it omit it."
 				}
 			}
 		}
@@ -509,12 +515,19 @@ const CALLS_PER_REQUEST_BOUNDARIES_V0 = [
 /** Number of calls-per-request buckets: boundaries + 1 open-ended bucket. */
 const CALLS_PER_REQUEST_BUCKETS_V0 = 8;
 //#endregion
+//#region src/generated/versions.ts
+/** Every published minor of v0, oldest first. The cloud never stops accepting one it published (ADR 0008). */
+const ACCEPTED_PROTOCOL_VERSIONS_V0 = [
+	"0.1.0",
+	"0.2.0",
+	"0.3.0",
+	"0.4.0",
+	"0.5.0"
+];
+/** The newest published minor: what an up-to-date agent stamps on every batch. */
+const PROTOCOL_VERSION = "0.5.0";
+//#endregion
 //#region src/index.ts
-/**
-* Version of the ingestion protocol this package speaks. Every published minor of v0 stays acceptable to the
-* cloud, so an agent on an older minor keeps working: fields are only ever added, and always optional (ADR 0008).
-*/
-const PROTOCOL_VERSION = "0.4.0";
 /** Path, relative to the ingest URL, that receives AggregatesBatch payloads. */
 const AGGREGATES_PATH = "/v0/aggregates";
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
@@ -538,4 +551,4 @@ function callsPerRequestBucket(calls) {
 	return n;
 }
 //#endregion
-export { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, callsPerRequestBucket, latencyBucket };
+export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, callsPerRequestBucket, latencyBucket };

package/package.json

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

package/schema/v0/aggregates.schema.json

@@ -9,7 +9,7 @@
   "properties": {
     "protocol": {
       "type": "string",
-      "enum": ["0.1.0", "0.2.0", "0.3.0", "0.4.0"],
+      "enum": ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0"],
       "description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
     },
     "agent": {
@@ -357,6 +357,11 @@
           "type": "integer",
           "minimum": 0,
           "description": "Calls that failed."
+        },
+        "waitMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Time requests spent waiting to be able to talk to this dependency, on top of the time spent talking to it: a saturated connection pool shows up here and nowhere else. Optional; agents that cannot see it omit it."
         }
       }
     }

package/schema/v0/fixtures/valid/pool-wait.json

@@ -0,0 +1,84 @@
+{
+  "protocol": "0.5.0",
+  "agent": {
+    "name": "@downtrace/agent",
+    "version": "0.0.0",
+    "runtime": "node",
+    "runtimeVersion": "v24.0.0"
+  },
+  "instance": {
+    "id": "7d1e9c6a-4f2b-4c1e-9b0a-2f6d3e8a1c55",
+    "hostname": "web-1",
+    "pid": 4242
+  },
+  "deploy": {
+    "version": "8f71ac2",
+    "environment": "production"
+  },
+  "intervals": [
+    {
+      "start": 1756900000000,
+      "durationMs": 10000,
+      "endpoints": [
+        {
+          "method": "POST",
+          "route": "/checkout",
+          "count": 3,
+          "errors": 0,
+          "status": {
+            "success": 3,
+            "redirect": 0,
+            "clientError": 0,
+            "serverError": 0
+          },
+          "latency": {
+            "counts": [
+              0, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
+            ],
+            "sum": 2.4,
+            "max": 0.9
+          },
+          "dependencies": [
+            {
+              "kind": "postgres",
+              "target": "",
+              "callsPerRequest": [0, 0, 0, 0, 0, 3, 0, 0],
+              "totalMs": 41.25,
+              "max": 9.5,
+              "errors": 0,
+              "waitMs": 30.5
+            },
+            {
+              "kind": "http",
+              "target": "api.stripe.com",
+              "callsPerRequest": [0, 0, 3, 0, 0, 0, 0, 0],
+              "totalMs": 612.4,
+              "max": 240.1,
+              "errors": 1
+            },
+            {
+              "kind": "redis",
+              "target": "",
+              "callsPerRequest": [0, 0, 0, 3, 0, 0, 0, 0],
+              "totalMs": 4.2,
+              "max": 1.1,
+              "errors": 0
+            }
+          ]
+        }
+      ],
+      "runtime": {
+        "eventLoopDelayMs": {
+          "p50": 0.9,
+          "p99": 14.2,
+          "max": 61.5
+        },
+        "gcPauseMs": 22.4,
+        "gcCount": 7,
+        "heapUsedMb": 48.6,
+        "rssMb": 131.2,
+        "inFlightMax": 9
+      }
+    }
+  ]
+}