@downtrace/protocol 0.1.0 → 0.2.1

package/README.md

@@ -4,13 +4,19 @@ 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()`, and the types `AggregatesBatch`, `Interval`, `Endpoint`, `LatencyHistogram`, …
+- 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`, …
 
 ## v0 in one sentence
 
 Every 10 seconds, for every route, an agent sends how many requests there were, how many failed, how statuses split, and a **35-bucket fixed latency histogram** (0.5 ms → 60 s). Fixed buckets add up across instances, so the cloud can compute fleet-wide percentiles.
 
-`POST {DOWNTRACE_URL}/v0/aggregates` · `Authorization: Bearer <token>` · JSON · 202 accepted, 400 invalid, 401 bad token.
+Since **0.2.0** an endpoint may also carry `postgres`: how many queries each request made, as an **8-bucket histogram** (0, 1, 2, 3–5, 6–10, 11–20, 21–50, 51+), plus the total and the slowest query time. It is optional, so an agent that does not observe queries omits it. That is what turns "this endpoint got slower" into "it went from 12 queries per request to 65".
+
+`POST {DOWNTRACE_URL}/v0/aggregates` · `Authorization: Bearer <token>` · JSON · 202 accepted, 400 invalid, 401 bad token, 429 rate limit or daily budget.
+
+## 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.
 
 ## Source
 

package/dist/index.d.ts

@@ -4,9 +4,9 @@
  */
 interface AggregatesBatch {
   /**
-   * Protocol version this batch conforms to.
+   * Protocol version this batch conforms to. Every published minor of v0 stays acceptable.
    */
-  protocol: "0.1.0";
+  protocol: "0.1.0" | "0.2.0";
   agent: AgentInfo;
   instance: InstanceInfo;
   deploy: DeployInfo;
@@ -61,6 +61,7 @@ interface Endpoint {
   errors: number;
   status: StatusClasses;
   latency: LatencyHistogram;
+  postgres?: PostgresStats;
 }
 interface StatusClasses {
   /**
@@ -98,16 +99,43 @@ interface LatencyHistogram {
    */
   max: number;
 }
+/**
+ * Postgres work done per request on this route during the interval. Optional: agents that do not observe queries omit it.
+ */
+interface PostgresStats {
+  /**
+   * Requests per bucket of queries-per-request; bounds in x-queries-per-request-boundaries, last bucket open-ended.
+   *
+   * @minItems 8
+   * @maxItems 8
+   */
+  queriesPerRequest: [number, number, number, number, number, number, number, number];
+  /**
+   * Sum of query durations (ms) across every request on this route.
+   */
+  totalMs: number;
+  /**
+   * Slowest single query (ms).
+   */
+  max: 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;
 //#endregion
 //#region src/index.d.ts
-/** Version of the ingestion protocol spoken by agents and the cloud. */
-declare const PROTOCOL_VERSION = "0.1.0";
+/**
+ * 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";
 /** 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. */
@@ -122,7 +150,7 @@ declare const AGGREGATES_SCHEMA_V0: {
   properties: {
     protocol: {
       type: string;
-      const: string;
+      enum: string[];
       description: string;
     };
     agent: {
@@ -267,6 +295,9 @@ declare const AGGREGATES_SCHEMA_V0: {
         latency: {
           $ref: string;
         };
+        postgres: {
+          $ref: string;
+        };
       };
     };
     StatusClasses: {
@@ -326,9 +357,41 @@ declare const AGGREGATES_SCHEMA_V0: {
         };
       };
     };
+    PostgresStats: {
+      title: string;
+      description: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      "x-queries-per-request-boundaries": number[];
+      properties: {
+        queriesPerRequest: {
+          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;
+        };
+      };
+    };
   };
 };
 /** 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;
 //#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 StatusClasses, latencyBucket };
+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 };

package/dist/index.js

@@ -16,8 +16,8 @@ var aggregates_schema_default = {
 	properties: {
 		"protocol": {
 			"type": "string",
-			"const": "0.1.0",
-			"description": "Protocol version this batch conforms to."
+			"enum": ["0.1.0", "0.2.0"],
+			"description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
 		},
 		"agent": { "$ref": "#/$defs/AgentInfo" },
 		"instance": { "$ref": "#/$defs/InstanceInfo" },
@@ -171,7 +171,8 @@ var aggregates_schema_default = {
 					"description": "Responses with a 5xx status."
 				},
 				"status": { "$ref": "#/$defs/StatusClasses" },
-				"latency": { "$ref": "#/$defs/LatencyHistogram" }
+				"latency": { "$ref": "#/$defs/LatencyHistogram" },
+				"postgres": { "$ref": "#/$defs/PostgresStats" }
 			}
 		},
 		"StatusClasses": {
@@ -274,6 +275,48 @@ var aggregates_schema_default = {
 					"description": "Maximum latency in ms."
 				}
 			}
+		},
+		"PostgresStats": {
+			"title": "PostgresStats",
+			"description": "Postgres work done per request on this route during the interval. Optional: agents that do not observe queries omit it.",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"queriesPerRequest",
+				"totalMs",
+				"max"
+			],
+			"x-queries-per-request-boundaries": [
+				0,
+				1,
+				2,
+				5,
+				10,
+				20,
+				50
+			],
+			"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)."
+				}
+			}
 		}
 	}
 };
@@ -318,10 +361,25 @@ 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 = [
+	0,
+	1,
+	2,
+	5,
+	10,
+	20,
+	50
+];
+/** Number of queries-per-request buckets: boundaries + 1 open-ended bucket. */
+const QUERIES_PER_REQUEST_BUCKETS_V0 = 8;
 //#endregion
 //#region src/index.ts
-/** Version of the ingestion protocol spoken by agents and the cloud. */
-const PROTOCOL_VERSION = "0.1.0";
+/**
+* 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";
 /** 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. */
@@ -335,5 +393,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;
+	for (let i = 0; i < n; i++) {
+		const bound = QUERIES_PER_REQUEST_BOUNDARIES_V0[i];
+		if (bound !== void 0 && queries <= bound) return i;
+	}
+	return n;
+}
 //#endregion
-export { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, latencyBucket };
+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 };

package/package.json

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

package/schema/v0/aggregates.schema.json

@@ -9,8 +9,8 @@
   "properties": {
     "protocol": {
       "type": "string",
-      "const": "0.1.0",
-      "description": "Protocol version this batch conforms to."
+      "enum": ["0.1.0", "0.2.0"],
+      "description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
     },
     "agent": {
       "$ref": "#/$defs/AgentInfo"
@@ -153,6 +153,9 @@
         },
         "latency": {
           "$ref": "#/$defs/LatencyHistogram"
+        },
+        "postgres": {
+          "$ref": "#/$defs/PostgresStats"
         }
       }
     },
@@ -215,6 +218,36 @@
           "description": "Maximum latency in ms."
         }
       }
+    },
+    "PostgresStats": {
+      "title": "PostgresStats",
+      "description": "Postgres work done per request on this route during the interval. Optional: agents that do not observe queries omit it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["queriesPerRequest", "totalMs", "max"],
+      "x-queries-per-request-boundaries": [0, 1, 2, 5, 10, 20, 50],
+      "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)."
+        }
+      }
     }
   }
 }

package/schema/v0/fixtures/invalid/postgres-buckets-length.json

@@ -0,0 +1,50 @@
+{
+  "protocol": "0.2.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],
+            "totalMs": 41.25,
+            "max": 9.5
+          }
+        }
+      ]
+    }
+  ]
+}

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

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