@downtrace/protocol 0.10.0 → 0.12.0

package/README.md

@@ -62,6 +62,10 @@ And still protocol **0.9.0**, an operation may be an **outgoing HTTP call** or a
 
 And since **0.10.0** a dependency may be of kind **`mongodb`**: a MongoDB database, one dependency with an empty `target` whatever the members of its replica set, as Postgres reached through postgres.js is. Its commands are operations of kind `query`, labelled by two words, the command's name and the collection it names — `find users`, `insert orders`, `aggregate events` — and never the filter, the documents, the pipeline or the update; a collection whose name looks like a value is `?`.
 
+And since **0.11.0** a dependency may be of kind **`sqlite`**: a SQLite database the process opens itself, through `better-sqlite3`, `libsql` or `@libsql/client` on a file, one dependency with an empty `target` whatever file it is, as MongoDB is. Its statements are operations of kind `query`, normalised as SQLite reads them: a double quote, a backtick and a bracket delimit a name, a single quote a value, and a backslash escapes nothing. The same minor lets `observers` name every switch of `DOWNTRACE_INSTRUMENT`: `mysql`, `sqlite` and `mongodb` beside `pg`, `http`, `redis` and `runtime`, so an observer of those three that is watching is said; the instrumentation leaves the key out when no driver of it resolved, which is «did not say».
+
+And since **0.12.0** `observers` has a `prisma` switch: Prisma's client, observed through the client and not through a driver, for Prisma before 7 on its own engine. Its operations are operations of kind `query` of the dependency its datasource is — `postgres` for Postgres and CockroachDB, `mysql`, `sqlite`, `mongodb` — with an empty `target`, labelled by two words, the action and the model (`findMany Post`, `create User`), and never the arguments; a raw query is labelled by its SQL, normalised as that dependency's dialect reads it. A client given a driver adapter is not counted by it: its driver's observer counts the SQL.
+
 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 and the ingestion path (`x-ingest-path`), so they are part of the generated contract rather than a constant someone has to keep in sync. So is the first minor that carries each kind of operation and of process exception (`x-since`, beside each `kind` enum), which is how a consumer tells a kind of error a sender cannot send from one it did not send, and whether each kind of operation is an error (`x-error`). A validator in strict mode has to be told these annotations are keywords.
 
 ## Source

package/dist/index.d.ts

@@ -11,6 +11,22 @@ declare function captureEvidencePath(id: string): string;
  * Whether an observer is attached (`on`), was not asked for (`off`), or was asked for and could not attach (`unavailable`) — a driver that is not resolvable from the application's root, for instance. The third one is the point: without it, a service that is not being watched looks exactly like a service that has nothing to watch (COB-01, invariant 14).
  */
 type ObserverState = "on" | "off" | "unavailable";
+/**
+ * Whether an observer is attached (`on`), was not asked for (`off`), or was asked for and could not attach (`unavailable`) — a driver that is not resolvable from the application's root, for instance. The third one is the point: without it, a service that is not being watched looks exactly like a service that has nothing to watch (COB-01, invariant 14).
+ */
+type ObserverState1 = "on" | "off" | "unavailable";
+/**
+ * Whether an observer is attached (`on`), was not asked for (`off`), or was asked for and could not attach (`unavailable`) — a driver that is not resolvable from the application's root, for instance. The third one is the point: without it, a service that is not being watched looks exactly like a service that has nothing to watch (COB-01, invariant 14).
+ */
+type ObserverState2 = "on" | "off" | "unavailable";
+/**
+ * Whether an observer is attached (`on`), was not asked for (`off`), or was asked for and could not attach (`unavailable`) — a driver that is not resolvable from the application's root, for instance. The third one is the point: without it, a service that is not being watched looks exactly like a service that has nothing to watch (COB-01, invariant 14).
+ */
+type ObserverState3 = "on" | "off" | "unavailable";
+/**
+ * Whether an observer is attached (`on`), was not asked for (`off`), or was asked for and could not attach (`unavailable`) — a driver that is not resolvable from the application's root, for instance. The third one is the point: without it, a service that is not being watched looks exactly like a service that has nothing to watch (COB-01, invariant 14).
+ */
+type ObserverState4 = "on" | "off" | "unavailable";
 /**
  * A value of `Operation.kind` that its `x-error` marks as an error: the ways an error inside a request arrives, and so the sources that can produce one. A query, an outgoing call and a Redis command are things a route ran, never a source of error.
  */
@@ -26,7 +42,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" | "0.8.0" | "0.9.0" | "0.10.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" | "0.9.0" | "0.10.0" | "0.11.0" | "0.12.0";
   agent: AgentInfo;
   instance: InstanceInfo;
   deploy: DeployInfo;
@@ -76,6 +92,10 @@ interface AgentInfo {
  */
 interface Observers {
   pg?: ObserverState;
+  mysql?: ObserverState1;
+  sqlite?: ObserverState2;
+  mongodb?: ObserverState3;
+  prisma?: ObserverState4;
   http?: ObserverState;
   redis?: ObserverState;
   runtime?: ObserverState;
@@ -260,9 +280,9 @@ interface PostgresStats {
  */
 interface Dependency {
   /**
-   * What kind of dependency this is. `mongodb` since 0.10.0: a MongoDB database, whose commands are operations of kind `query` named by the command and the collection (`find users`).
+   * What kind of dependency this is. `mongodb` since 0.10.0: a MongoDB database, whose commands are operations of kind `query` named by the command and the collection (`find users`). `sqlite` since 0.11.0: a SQLite database in the process, one dependency with an empty `target`, whose statements are operations of kind `query`. Since 0.12.0 a Prisma client's operation is an operation of kind `query` of the dependency its datasource is, with an empty `target`, named by the action and the model (`findMany Post`), or by its SQL for a raw query.
    */
-  kind: "postgres" | "mysql" | "mongodb" | "redis" | "http";
+  kind: "postgres" | "mysql" | "sqlite" | "mongodb" | "redis" | "http";
   /**
    * Host for outgoing HTTP (`api.stripe.com`); empty when the dependency is a single one, like the application's own database.
    */
@@ -483,7 +503,7 @@ declare const DEPENDENCIES_MAX_ITEMS_V0 = 64;
 /** The most requests a capture's evidence may carry: the ring is sized as this minus the reserves' room (gh-901). */
 declare const EVIDENCE_REQUESTS_MAX_ITEMS_V0 = 4096;
 /** The dependency kinds the schema names, in the order it names them. */
-declare const DEPENDENCY_KINDS_V0: readonly ["postgres", "mysql", "mongodb", "redis", "http"];
+declare const DEPENDENCY_KINDS_V0: readonly ["postgres", "mysql", "sqlite", "mongodb", "redis", "http"];
 //#endregion
 //#region src/generated/capture-evidence.d.ts
 /**
@@ -493,7 +513,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" | "0.8.0" | "0.9.0" | "0.10.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" | "0.9.0" | "0.10.0" | "0.11.0" | "0.12.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.
    */
@@ -766,9 +786,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", "0.8.0", "0.9.0", "0.10.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", "0.9.0", "0.10.0", "0.11.0", "0.12.0"];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-declare const PROTOCOL_VERSION = "0.10.0";
+declare const PROTOCOL_VERSION = "0.12.0";
 //#endregion
 //#region src/index.d.ts
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
@@ -1370,6 +1390,22 @@ declare const AGGREGATES_SCHEMA_V0: {
         pg: {
           $ref: string;
         };
+        mysql: {
+          $ref: string;
+          description: string;
+        };
+        sqlite: {
+          $ref: string;
+          description: string;
+        };
+        mongodb: {
+          $ref: string;
+          description: string;
+        };
+        prisma: {
+          $ref: string;
+          description: string;
+        };
         http: {
           $ref: string;
         };

package/dist/index.js

@@ -27,7 +27,9 @@ var aggregates_schema_default = {
 				"0.7.0",
 				"0.8.0",
 				"0.9.0",
-				"0.10.0"
+				"0.10.0",
+				"0.11.0",
+				"0.12.0"
 			],
 			"description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
 		},
@@ -501,11 +503,12 @@ var aggregates_schema_default = {
 					"enum": [
 						"postgres",
 						"mysql",
+						"sqlite",
 						"mongodb",
 						"redis",
 						"http"
 					],
-					"description": "What kind of dependency this is. `mongodb` since 0.10.0: a MongoDB database, whose commands are operations of kind `query` named by the command and the collection (`find users`)."
+					"description": "What kind of dependency this is. `mongodb` since 0.10.0: a MongoDB database, whose commands are operations of kind `query` named by the command and the collection (`find users`). `sqlite` since 0.11.0: a SQLite database in the process, one dependency with an empty `target`, whose statements are operations of kind `query`. Since 0.12.0 a Prisma client's operation is an operation of kind `query` of the dependency its datasource is, with an empty `target`, named by the action and the model (`findMany Post`), or by its SQL for a raw query."
 				},
 				"target": {
 					"type": "string",
@@ -712,6 +715,22 @@ var aggregates_schema_default = {
 			"description": "What the instrumentation is watching, by switch. The keys are the switches of `DOWNTRACE_INSTRUMENT`, so this says `pg` where a dependency says `postgres`: one is the switch and the other is the thing observed.",
 			"properties": {
 				"pg": { "$ref": "#/$defs/ObserverState" },
+				"mysql": {
+					"$ref": "#/$defs/ObserverState",
+					"description": "Since 0.11.0. Absent from an older sender, which had no word for it."
+				},
+				"sqlite": {
+					"$ref": "#/$defs/ObserverState",
+					"description": "Since 0.11.0. Absent from an older sender, which had no word for it."
+				},
+				"mongodb": {
+					"$ref": "#/$defs/ObserverState",
+					"description": "Since 0.11.0. Absent from an older sender, which had no word for it."
+				},
+				"prisma": {
+					"$ref": "#/$defs/ObserverState",
+					"description": "Since 0.12.0. Absent from an older sender, which had no word for it. Prisma's client, whose operations are queries of the dependency its datasource is: a switch of its own because it observes a client and not a driver."
+				},
 				"http": { "$ref": "#/$defs/ObserverState" },
 				"redis": { "$ref": "#/$defs/ObserverState" },
 				"runtime": { "$ref": "#/$defs/ObserverState" }
@@ -946,7 +965,9 @@ var capture_evidence_schema_default = {
 				"0.7.0",
 				"0.8.0",
 				"0.9.0",
-				"0.10.0"
+				"0.10.0",
+				"0.11.0",
+				"0.12.0"
 			]
 		},
 		"instance": {
@@ -1468,6 +1489,7 @@ const EVIDENCE_REQUESTS_MAX_ITEMS_V0 = 4096;
 const DEPENDENCY_KINDS_V0 = [
 	"postgres",
 	"mysql",
+	"sqlite",
 	"mongodb",
 	"redis",
 	"http"
@@ -1485,10 +1507,12 @@ const ACCEPTED_PROTOCOL_VERSIONS_V0 = [
 	"0.7.0",
 	"0.8.0",
 	"0.9.0",
-	"0.10.0"
+	"0.10.0",
+	"0.11.0",
+	"0.12.0"
 ];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-const PROTOCOL_VERSION = "0.10.0";
+const PROTOCOL_VERSION = "0.12.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.10.0",
+  "version": "0.12.0",
   "description": "Downtrace ingestion protocol: JSON Schema, fixtures and generated TypeScript types",
   "type": "module",
   "exports": {

package/schema/v0/aggregates.schema.json

@@ -10,7 +10,20 @@
   "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", "0.8.0", "0.9.0", "0.10.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",
+        "0.9.0",
+        "0.10.0",
+        "0.11.0",
+        "0.12.0"
+      ],
       "description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
     },
     "agent": {
@@ -410,8 +423,8 @@
       "x-calls-per-request-boundaries": [0, 1, 2, 5, 10, 20, 50],
       "properties": {
         "kind": {
-          "enum": ["postgres", "mysql", "mongodb", "redis", "http"],
-          "description": "What kind of dependency this is. `mongodb` since 0.10.0: a MongoDB database, whose commands are operations of kind `query` named by the command and the collection (`find users`)."
+          "enum": ["postgres", "mysql", "sqlite", "mongodb", "redis", "http"],
+          "description": "What kind of dependency this is. `mongodb` since 0.10.0: a MongoDB database, whose commands are operations of kind `query` named by the command and the collection (`find users`). `sqlite` since 0.11.0: a SQLite database in the process, one dependency with an empty `target`, whose statements are operations of kind `query`. Since 0.12.0 a Prisma client's operation is an operation of kind `query` of the dependency its datasource is, with an empty `target`, named by the action and the model (`findMany Post`), or by its SQL for a raw query."
         },
         "target": {
           "type": "string",
@@ -594,6 +607,22 @@
         "pg": {
           "$ref": "#/$defs/ObserverState"
         },
+        "mysql": {
+          "$ref": "#/$defs/ObserverState",
+          "description": "Since 0.11.0. Absent from an older sender, which had no word for it."
+        },
+        "sqlite": {
+          "$ref": "#/$defs/ObserverState",
+          "description": "Since 0.11.0. Absent from an older sender, which had no word for it."
+        },
+        "mongodb": {
+          "$ref": "#/$defs/ObserverState",
+          "description": "Since 0.11.0. Absent from an older sender, which had no word for it."
+        },
+        "prisma": {
+          "$ref": "#/$defs/ObserverState",
+          "description": "Since 0.12.0. Absent from an older sender, which had no word for it. Prisma's client, whose operations are queries of the dependency its datasource is: a switch of its own because it observes a client and not a driver."
+        },
         "http": {
           "$ref": "#/$defs/ObserverState"
         },

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

@@ -11,7 +11,20 @@
     "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", "0.8.0", "0.9.0", "0.10.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",
+        "0.9.0",
+        "0.10.0",
+        "0.11.0",
+        "0.12.0"
+      ]
     },
     "instance": {
       "type": "object",