@downtrace/protocol 0.1.0 → 0.2.0

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.0",
   "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
+          }
+        }
+      ]
+    }
+  ]
+}