@downtrace/protocol 0.2.1 → 0.4.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()`, `QUERIES_PER_REQUEST_BOUNDARIES_V0`, `QUERIES_PER_REQUEST_BUCKETS_V0`, `queriesPerRequestBucket()`, and the types `AggregatesBatch`, `Interval`, `Endpoint`, `LatencyHistogram`, `PostgresStats`, …
+- 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`, …
 
 ## v0 in one sentence
 

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";
+  protocol: "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0" | "0.5.0";
   agent: AgentInfo;
   instance: InstanceInfo;
   deploy: DeployInfo;
@@ -47,6 +47,7 @@ interface Interval {
    * @maxItems 4096
    */
   endpoints: Endpoint[];
+  runtime?: RuntimeHealth;
 }
 interface Endpoint {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "OTHER";
@@ -62,6 +63,12 @@ interface Endpoint {
   status: StatusClasses;
   latency: LatencyHistogram;
   postgres?: PostgresStats;
+  /**
+   * One entry per dependency this route touched. Replaces `postgres` (ADR 0011).
+   *
+   * @maxItems 64
+   */
+  dependencies?: Dependency[];
 }
 interface StatusClasses {
   /**
@@ -100,7 +107,7 @@ interface LatencyHistogram {
   max: number;
 }
 /**
- * Postgres work done per request on this route during the interval. Optional: agents that do not observe queries omit it.
+ * DEPRECATED since 0.4.0, use `dependencies` with kind `postgres` (ADR 0011). Still accepted, and translated at ingest, so agents on 0.2.x and 0.3.x keep working. Will be removed in v1. Its buckets are the same as Dependency's, declared there.
  */
 interface PostgresStats {
   /**
@@ -119,23 +126,101 @@ interface PostgresStats {
    */
   max: number;
 }
+/**
+ * What one request did against one dependency, aggregated over the interval for this route. The same shape for every kind, so the cloud stores and compares them uniformly (ADR 0011).
+ */
+interface Dependency {
+  /**
+   * What kind of dependency this is.
+   */
+  kind: "postgres" | "mysql" | "redis" | "http";
+  /**
+   * Host for outgoing HTTP (`api.stripe.com`); empty when the dependency is a single one, like the application's own database.
+   */
+  target: string;
+  /**
+   * Requests per bucket of calls-per-request; bounds in x-calls-per-request-boundaries, last bucket open-ended.
+   *
+   * @minItems 8
+   * @maxItems 8
+   */
+  callsPerRequest: [number, number, number, number, number, number, number, number];
+  /**
+   * Sum of call durations (ms) across every request on this route.
+   */
+  totalMs: number;
+  /**
+   * Slowest single call (ms).
+   */
+  max: number;
+  /**
+   * 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.
+ */
+interface RuntimeHealth {
+  /**
+   * How long the event loop was late, in ms. The signal that says the process itself is the bottleneck.
+   */
+  eventLoopDelayMs: {
+    /**
+     * Median delay.
+     */
+    p50: number;
+    /**
+     * 99th percentile delay.
+     */
+    p99: number;
+    /**
+     * Worst delay.
+     */
+    max: number;
+  };
+  /**
+   * Total time spent in garbage collection during the interval.
+   */
+  gcPauseMs: number;
+  /**
+   * Garbage collections during the interval.
+   */
+  gcCount: number;
+  /**
+   * Heap in use at the end of the interval.
+   */
+  heapUsedMb: number;
+  /**
+   * Resident set size at the end of the interval.
+   */
+  rssMb: number;
+  /**
+   * Peak concurrent in-flight requests during the interval.
+   */
+  inFlightMax: number;
+}
 //#endregion
 //#region src/generated/boundaries.d.ts
 /** Upper bounds (ms) of the fixed latency buckets; the last bucket is open-ended. */
 declare const LATENCY_BOUNDARIES_V0: readonly number[];
 /** Number of buckets: boundaries + 1 open-ended bucket. */
 declare const LATENCY_BUCKETS_V0 = 35;
-/** Upper bounds of the fixed queries-per-request buckets; the last bucket is open-ended. */
-declare const QUERIES_PER_REQUEST_BOUNDARIES_V0: readonly number[];
-/** Number of queries-per-request buckets: boundaries + 1 open-ended bucket. */
-declare const QUERIES_PER_REQUEST_BUCKETS_V0 = 8;
+/** Upper bounds of the fixed calls-per-request buckets; the last bucket is open-ended. */
+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/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.2.0";
+declare const PROTOCOL_VERSION = "0.5.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. */
@@ -263,6 +348,9 @@ declare const AGGREGATES_SCHEMA_V0: {
             $ref: string;
           };
         };
+        runtime: {
+          $ref: string;
+        };
       };
     };
     Endpoint: {
@@ -298,6 +386,14 @@ declare const AGGREGATES_SCHEMA_V0: {
         postgres: {
           $ref: string;
         };
+        dependencies: {
+          type: string;
+          description: string;
+          maxItems: number;
+          items: {
+            $ref: string;
+          };
+        };
       };
     };
     StatusClasses: {
@@ -363,7 +459,6 @@ declare const AGGREGATES_SCHEMA_V0: {
       type: string;
       additionalProperties: boolean;
       required: string[];
-      "x-queries-per-request-boundaries": number[];
       properties: {
         queriesPerRequest: {
           type: string;
@@ -387,11 +482,117 @@ declare const AGGREGATES_SCHEMA_V0: {
         };
       };
     };
+    RuntimeHealth: {
+      title: string;
+      description: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        eventLoopDelayMs: {
+          type: string;
+          additionalProperties: boolean;
+          required: string[];
+          description: string;
+          properties: {
+            p50: {
+              type: string;
+              minimum: number;
+              description: string;
+            };
+            p99: {
+              type: string;
+              minimum: number;
+              description: string;
+            };
+            max: {
+              type: string;
+              minimum: number;
+              description: string;
+            };
+          };
+        };
+        gcPauseMs: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        gcCount: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        heapUsedMb: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        rssMb: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        inFlightMax: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+      };
+    };
+    Dependency: {
+      title: string;
+      description: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      "x-calls-per-request-boundaries": number[];
+      properties: {
+        kind: {
+          enum: string[];
+          description: string;
+        };
+        target: {
+          type: string;
+          maxLength: number;
+          description: string;
+        };
+        callsPerRequest: {
+          type: string;
+          description: string;
+          minItems: number;
+          maxItems: number;
+          items: {
+            type: string;
+            minimum: number;
+          };
+        };
+        totalMs: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        max: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        errors: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        waitMs: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+      };
+    };
   };
 };
 /** Index of the bucket a latency (ms) falls into: first boundary >= latency, else the open-ended last bucket. */
 declare function latencyBucket(ms: number): number;
-/** Index of the bucket a query count falls into: first boundary >= count, else the open-ended last bucket. */
-declare function queriesPerRequestBucket(queries: 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, type DeployInfo, type Endpoint, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, PROTOCOL_VERSION, type PostgresStats, QUERIES_PER_REQUEST_BOUNDARIES_V0, QUERIES_PER_REQUEST_BUCKETS_V0, type StatusClasses, latencyBucket, queriesPerRequestBucket };
+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 };

package/dist/index.js

@@ -16,7 +16,13 @@ var aggregates_schema_default = {
 	properties: {
 		"protocol": {
 			"type": "string",
-			"enum": ["0.1.0", "0.2.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": { "$ref": "#/$defs/AgentInfo" },
@@ -129,7 +135,8 @@ var aggregates_schema_default = {
 					"type": "array",
 					"maxItems": 4096,
 					"items": { "$ref": "#/$defs/Endpoint" }
-				}
+				},
+				"runtime": { "$ref": "#/$defs/RuntimeHealth" }
 			}
 		},
 		"Endpoint": {
@@ -172,7 +179,13 @@ var aggregates_schema_default = {
 				},
 				"status": { "$ref": "#/$defs/StatusClasses" },
 				"latency": { "$ref": "#/$defs/LatencyHistogram" },
-				"postgres": { "$ref": "#/$defs/PostgresStats" }
+				"postgres": { "$ref": "#/$defs/PostgresStats" },
+				"dependencies": {
+					"type": "array",
+					"description": "One entry per dependency this route touched. Replaces `postgres` (ADR 0011).",
+					"maxItems": 64,
+					"items": { "$ref": "#/$defs/Dependency" }
+				}
 			}
 		},
 		"StatusClasses": {
@@ -278,7 +291,7 @@ var aggregates_schema_default = {
 		},
 		"PostgresStats": {
 			"title": "PostgresStats",
-			"description": "Postgres work done per request on this route during the interval. Optional: agents that do not observe queries omit it.",
+			"description": "DEPRECATED since 0.4.0, use `dependencies` with kind `postgres` (ADR 0011). Still accepted, and translated at ingest, so agents on 0.2.x and 0.3.x keep working. Will be removed in v1. Its buckets are the same as Dependency's, declared there.",
 			"type": "object",
 			"additionalProperties": false,
 			"required": [
@@ -286,7 +299,111 @@ var aggregates_schema_default = {
 				"totalMs",
 				"max"
 			],
-			"x-queries-per-request-boundaries": [
+			"properties": {
+				"queriesPerRequest": {
+					"type": "array",
+					"description": "Requests per bucket of queries-per-request; bounds in x-queries-per-request-boundaries, last bucket open-ended.",
+					"minItems": 8,
+					"maxItems": 8,
+					"items": {
+						"type": "integer",
+						"minimum": 0
+					}
+				},
+				"totalMs": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Sum of query durations (ms) across every request on this route."
+				},
+				"max": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Slowest single query (ms)."
+				}
+			}
+		},
+		"RuntimeHealth": {
+			"title": "RuntimeHealth",
+			"description": "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.",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"eventLoopDelayMs",
+				"gcPauseMs",
+				"gcCount",
+				"heapUsedMb",
+				"rssMb",
+				"inFlightMax"
+			],
+			"properties": {
+				"eventLoopDelayMs": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": [
+						"p50",
+						"p99",
+						"max"
+					],
+					"description": "How long the event loop was late, in ms. The signal that says the process itself is the bottleneck.",
+					"properties": {
+						"p50": {
+							"type": "number",
+							"minimum": 0,
+							"description": "Median delay."
+						},
+						"p99": {
+							"type": "number",
+							"minimum": 0,
+							"description": "99th percentile delay."
+						},
+						"max": {
+							"type": "number",
+							"minimum": 0,
+							"description": "Worst delay."
+						}
+					}
+				},
+				"gcPauseMs": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Total time spent in garbage collection during the interval."
+				},
+				"gcCount": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Garbage collections during the interval."
+				},
+				"heapUsedMb": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Heap in use at the end of the interval."
+				},
+				"rssMb": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Resident set size at the end of the interval."
+				},
+				"inFlightMax": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Peak concurrent in-flight requests during the interval."
+				}
+			}
+		},
+		"Dependency": {
+			"title": "Dependency",
+			"description": "What one request did against one dependency, aggregated over the interval for this route. The same shape for every kind, so the cloud stores and compares them uniformly (ADR 0011).",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"kind",
+				"target",
+				"callsPerRequest",
+				"totalMs",
+				"max",
+				"errors"
+			],
+			"x-calls-per-request-boundaries": [
 				0,
 				1,
 				2,
@@ -296,9 +413,23 @@ var aggregates_schema_default = {
 				50
 			],
 			"properties": {
-				"queriesPerRequest": {
+				"kind": {
+					"enum": [
+						"postgres",
+						"mysql",
+						"redis",
+						"http"
+					],
+					"description": "What kind of dependency this is."
+				},
+				"target": {
+					"type": "string",
+					"maxLength": 256,
+					"description": "Host for outgoing HTTP (`api.stripe.com`); empty when the dependency is a single one, like the application's own database."
+				},
+				"callsPerRequest": {
 					"type": "array",
-					"description": "Requests per bucket of queries-per-request; bounds in x-queries-per-request-boundaries, last bucket open-ended.",
+					"description": "Requests per bucket of calls-per-request; bounds in x-calls-per-request-boundaries, last bucket open-ended.",
 					"minItems": 8,
 					"maxItems": 8,
 					"items": {
@@ -309,12 +440,22 @@ var aggregates_schema_default = {
 				"totalMs": {
 					"type": "number",
 					"minimum": 0,
-					"description": "Sum of query durations (ms) across every request on this route."
+					"description": "Sum of call durations (ms) across every request on this route."
 				},
 				"max": {
 					"type": "number",
 					"minimum": 0,
-					"description": "Slowest single query (ms)."
+					"description": "Slowest single call (ms)."
+				},
+				"errors": {
+					"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."
 				}
 			}
 		}
@@ -361,8 +502,8 @@ const LATENCY_BOUNDARIES_V0 = [
 ];
 /** Number of buckets: boundaries + 1 open-ended bucket. */
 const LATENCY_BUCKETS_V0 = 35;
-/** Upper bounds of the fixed queries-per-request buckets; the last bucket is open-ended. */
-const QUERIES_PER_REQUEST_BOUNDARIES_V0 = [
+/** Upper bounds of the fixed calls-per-request buckets; the last bucket is open-ended. */
+const CALLS_PER_REQUEST_BOUNDARIES_V0 = [
 	0,
 	1,
 	2,
@@ -371,15 +512,15 @@ const QUERIES_PER_REQUEST_BOUNDARIES_V0 = [
 	20,
 	50
 ];
-/** Number of queries-per-request buckets: boundaries + 1 open-ended bucket. */
-const QUERIES_PER_REQUEST_BUCKETS_V0 = 8;
+/** Number of calls-per-request buckets: boundaries + 1 open-ended bucket. */
+const CALLS_PER_REQUEST_BUCKETS_V0 = 8;
 //#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.2.0";
+const PROTOCOL_VERSION = "0.5.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. */
@@ -393,14 +534,14 @@ function latencyBucket(ms) {
 	}
 	return n;
 }
-/** Index of the bucket a query count falls into: first boundary >= count, else the open-ended last bucket. */
-function queriesPerRequestBucket(queries) {
-	const n = QUERIES_PER_REQUEST_BOUNDARIES_V0.length;
+/** Index of the bucket a call count falls into: first boundary >= count, else the open-ended last bucket. */
+function callsPerRequestBucket(calls) {
+	const n = CALLS_PER_REQUEST_BOUNDARIES_V0.length;
 	for (let i = 0; i < n; i++) {
-		const bound = QUERIES_PER_REQUEST_BOUNDARIES_V0[i];
-		if (bound !== void 0 && queries <= bound) return i;
+		const bound = CALLS_PER_REQUEST_BOUNDARIES_V0[i];
+		if (bound !== void 0 && calls <= bound) return i;
 	}
 	return n;
 }
 //#endregion
-export { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, QUERIES_PER_REQUEST_BOUNDARIES_V0, QUERIES_PER_REQUEST_BUCKETS_V0, latencyBucket, queriesPerRequestBucket };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downtrace/protocol",
-  "version": "0.2.1",
+  "version": "0.4.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"],
+      "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": {
@@ -121,6 +121,9 @@
           "items": {
             "$ref": "#/$defs/Endpoint"
           }
+        },
+        "runtime": {
+          "$ref": "#/$defs/RuntimeHealth"
         }
       }
     },
@@ -156,6 +159,14 @@
         },
         "postgres": {
           "$ref": "#/$defs/PostgresStats"
+        },
+        "dependencies": {
+          "type": "array",
+          "description": "One entry per dependency this route touched. Replaces `postgres` (ADR 0011).",
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/$defs/Dependency"
+          }
         }
       }
     },
@@ -221,11 +232,10 @@
     },
     "PostgresStats": {
       "title": "PostgresStats",
-      "description": "Postgres work done per request on this route during the interval. Optional: agents that do not observe queries omit it.",
+      "description": "DEPRECATED since 0.4.0, use `dependencies` with kind `postgres` (ADR 0011). Still accepted, and translated at ingest, so agents on 0.2.x and 0.3.x keep working. Will be removed in v1. Its buckets are the same as Dependency's, declared there.",
       "type": "object",
       "additionalProperties": false,
       "required": ["queriesPerRequest", "totalMs", "max"],
-      "x-queries-per-request-boundaries": [0, 1, 2, 5, 10, 20, 50],
       "properties": {
         "queriesPerRequest": {
           "type": "array",
@@ -248,6 +258,112 @@
           "description": "Slowest single query (ms)."
         }
       }
+    },
+    "RuntimeHealth": {
+      "title": "RuntimeHealth",
+      "description": "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.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["eventLoopDelayMs", "gcPauseMs", "gcCount", "heapUsedMb", "rssMb", "inFlightMax"],
+      "properties": {
+        "eventLoopDelayMs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["p50", "p99", "max"],
+          "description": "How long the event loop was late, in ms. The signal that says the process itself is the bottleneck.",
+          "properties": {
+            "p50": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Median delay."
+            },
+            "p99": {
+              "type": "number",
+              "minimum": 0,
+              "description": "99th percentile delay."
+            },
+            "max": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Worst delay."
+            }
+          }
+        },
+        "gcPauseMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Total time spent in garbage collection during the interval."
+        },
+        "gcCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Garbage collections during the interval."
+        },
+        "heapUsedMb": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Heap in use at the end of the interval."
+        },
+        "rssMb": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Resident set size at the end of the interval."
+        },
+        "inFlightMax": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Peak concurrent in-flight requests during the interval."
+        }
+      }
+    },
+    "Dependency": {
+      "title": "Dependency",
+      "description": "What one request did against one dependency, aggregated over the interval for this route. The same shape for every kind, so the cloud stores and compares them uniformly (ADR 0011).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "target", "callsPerRequest", "totalMs", "max", "errors"],
+      "x-calls-per-request-boundaries": [0, 1, 2, 5, 10, 20, 50],
+      "properties": {
+        "kind": {
+          "enum": ["postgres", "mysql", "redis", "http"],
+          "description": "What kind of dependency this is."
+        },
+        "target": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "Host for outgoing HTTP (`api.stripe.com`); empty when the dependency is a single one, like the application's own database."
+        },
+        "callsPerRequest": {
+          "type": "array",
+          "description": "Requests per bucket of calls-per-request; bounds in x-calls-per-request-boundaries, last bucket open-ended.",
+          "minItems": 8,
+          "maxItems": 8,
+          "items": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "totalMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Sum of call durations (ms) across every request on this route."
+        },
+        "max": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Slowest single call (ms)."
+        },
+        "errors": {
+          "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/invalid/dependency-unknown-kind.json

@@ -0,0 +1,83 @@
+{
+  "protocol": "0.4.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": "cassandra",
+              "target": "",
+              "callsPerRequest": [0, 0, 0, 0, 0, 3, 0, 0],
+              "totalMs": 41.25,
+              "max": 9.5,
+              "errors": 0
+            },
+            {
+              "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
+      }
+    }
+  ]
+}

package/schema/v0/fixtures/invalid/runtime-missing-rss.json

@@ -0,0 +1,61 @@
+{
+  "protocol": "0.3.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
+          },
+          "postgres": {
+            "queriesPerRequest": [0, 0, 0, 0, 0, 3, 0, 0],
+            "totalMs": 41.25,
+            "max": 9.5
+          }
+        }
+      ],
+      "runtime": {
+        "eventLoopDelayMs": {
+          "p50": 0.9,
+          "p99": 14.2,
+          "max": 61.5
+        },
+        "gcPauseMs": 22.4,
+        "gcCount": 7,
+        "heapUsedMb": 48.6,
+        "inFlightMax": 9
+      }
+    }
+  ]
+}

package/schema/v0/fixtures/valid/dependencies.json

@@ -0,0 +1,83 @@
+{
+  "protocol": "0.4.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
+            },
+            {
+              "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
+      }
+    }
+  ]
+}

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
+      }
+    }
+  ]
+}

package/schema/v0/fixtures/valid/runtime.json

@@ -0,0 +1,62 @@
+{
+  "protocol": "0.3.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
+          },
+          "postgres": {
+            "queriesPerRequest": [0, 0, 0, 0, 0, 3, 0, 0],
+            "totalMs": 41.25,
+            "max": 9.5
+          }
+        }
+      ],
+      "runtime": {
+        "eventLoopDelayMs": {
+          "p50": 0.9,
+          "p99": 14.2,
+          "max": 61.5
+        },
+        "gcPauseMs": 22.4,
+        "gcCount": 7,
+        "heapUsedMb": 48.6,
+        "rssMb": 131.2,
+        "inFlightMax": 9
+      }
+    }
+  ]
+}