@downtrace/protocol 0.9.0 → 0.10.0

package/README.md

@@ -56,10 +56,12 @@ And still protocol **0.9.0**, a capture's `coverage` may carry `shed`: `{ "ms":
 
 And still protocol **0.9.0**, `agent` may carry `errorSources`: `{ "inRequest": [...], "outsideRequest": [...] }` — which of the sources of error the process has **connected**, as of the moment the batch is sealed. `inRequest` holds the values of `Operation.kind` that are errors — `error`, `framework`, `explicit` — and `outsideRequest` the values of `ProcessException.kind` — `uncaught`, `unhandled-rejection`, `framework`, `explicit`. A value is on its list when the process has, at that moment, the instrumentation that produces it installed; the application calling `captureException` does not make it one without the hook connected. Both lists are required when the field is present, and no value appears twice. **Absent is «did not declare»**, exactly as with `observers`: an older sender says nothing, and that is not the same as the two lists left empty, which are a statement — the sender says it has connected no source of error. It exists because the protocol only bounds what a batch can carry from above: an instrumentation that speaks a protocol and does not send everything it carries has no other way to say so, and a reader that attributed to it the kinds its protocol allows would be saying what it does not send.
 
-And still protocol **0.9.0**, a captured request may carry `dependenciesTruncated`: its list of dependencies did not fit and was truncated to what the register keeps per request, and the capture's `coverage` counts such rows in its own `dependenciesTruncated`, beside `truncated` and `detailLost`. It is the mark that keeps a row that entered a capture of a dependency because its list did not fit from reading as a complete one: a dependency that is not in the list is not proven not to have been used, and `truncated` means operations, so the row says it in a field of its own. Absent means false, as with the other two: a sender older than the field sends nothing, and an evidence without the mark is as valid as it was.
+And still protocol **0.9.0**, a captured request may carry `dependenciesTruncated`: its list of dependencies did not fit and was truncated to what the register keeps per request, and the capture's `coverage` counts such rows in its own `dependenciesTruncated`, beside `truncated` and `detailLost`. It is the mark that keeps a row that entered a capture of a dependency because its list did not fit from reading as a complete one: a dependency that is not in the list is not proven not to have been used, and `truncated` means operations, so the row says it in a field of its own. Absent means false, as with the other two: a sender older than the field sends nothing, and an evidence without the mark is as valid as it was. The count is said at zero too; an evidence of protocol 0.9.0 or later without it counts zero, because `@downtrace/agent` 0.9.0 omitted it at zero, and one of an earlier protocol did not say.
 
 And still protocol **0.9.0**, an operation may be an **outgoing HTTP call** or a **Redis command**: `Operation.kind` gains `call`, identified by its method and its host, and `command`, identified by its name and its server, beside `query` as the things a route ran. Their text is a word and the place it went — `POST api.stripe.com`, `HGETALL cache:6379` — and never a path, a query string, a key or an argument: the schema refuses a label with anything after the place, or a slash, a question mark or a hash in it, and the text is absent in minimal mode or when the dependency's name is withheld, with the hash still the identity. Which kinds are errors is said beside the enum as `x-error`, one boolean per value: `error`, `framework` and `explicit` are, the three things a route ran are not, and `errorSources.inRequest` takes exactly the ones that are. A captured operation may say its `kind` too, from the same enum. **Absent there means the sender did not say**, never a query: an instrumentation older than this wrote every operation it recorded into the black box without one, the error signature beside a failed query among them, so a reader that took them for queries would be naming what it was not told.
 
+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 `?`.
+
 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

@@ -26,7 +26,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";
+  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";
   agent: AgentInfo;
   instance: InstanceInfo;
   deploy: DeployInfo;
@@ -181,7 +181,7 @@ interface Interval {
 interface Endpoint {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "OTHER";
   /**
-   * Normalised route template, e.g. /products/:id, or (other).
+   * Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56).
    */
   route: string;
   count: number;
@@ -260,9 +260,9 @@ interface PostgresStats {
  */
 interface Dependency {
   /**
-   * What kind of dependency this is.
+   * 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`).
    */
-  kind: "postgres" | "mysql" | "redis" | "http";
+  kind: "postgres" | "mysql" | "mongodb" | "redis" | "http";
   /**
    * Host for outgoing HTTP (`api.stripe.com`); empty when the dependency is a single one, like the application's own database.
    */
@@ -350,7 +350,7 @@ interface Profile {
 interface ProfileEndpoint {
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "OTHER";
   /**
-   * Normalised route template, e.g. /products/:id, or (other).
+   * Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56).
    */
   route: string;
   /**
@@ -371,7 +371,7 @@ interface Operation {
    */
   hash: string;
   /**
-   * Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `POST api.stripe.com` for a call and `HGETALL cache:6379` for a command. A call's and a command's are a word and the place it went — the method and the host, the command's name and its server — and never a path, a query string, a key or an argument (invariant 5): the schema refuses one with anything after the place, or a slash, a question mark or a hash in it. Optional: a user who would rather not send it keeps the whole analysis, only without the label, and a sender in minimal mode, or one withholding the name of the dependency, sends none.
+   * Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `find users` for a MongoDB command — its name and its collection, never the filter or the documents —, `POST api.stripe.com` for a call and `HGETALL cache:6379` for a command. A call's and a command's are a word and the place it went — the method and the host, the command's name and its server — and never a path, a query string, a key or an argument (invariant 5): the schema refuses one with anything after the place, or a slash, a question mark or a hash in it. Optional: a user who would rather not send it keeps the whole analysis, only without the label, and a sender in minimal mode, or one withholding the name of the dependency, sends none.
    */
   text?: string;
   /**
@@ -483,7 +483,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", "redis", "http"];
+declare const DEPENDENCY_KINDS_V0: readonly ["postgres", "mysql", "mongodb", "redis", "http"];
 //#endregion
 //#region src/generated/capture-evidence.d.ts
 /**
@@ -493,7 +493,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";
+  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";
   /**
    * 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.
    */
@@ -542,7 +542,7 @@ interface CaptureCoverage {
   truncated: number;
   shed?: Shed;
   /**
-   * Requests whose list of dependencies was truncated. Their count is real and their list is not complete.
+   * Requests whose list of dependencies was truncated. Their count is real and their list is not complete. A sender that knows the field sends it, zero included. Absent in an evidence of protocol 0.9.0 or later is zero: @downtrace/agent 0.9.0 omitted it at zero. Absent in an earlier protocol is a sender older than the field, which did not say, and that is not none.
    */
   dependenciesTruncated?: number;
 }
@@ -766,9 +766,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"];
+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"];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-declare const PROTOCOL_VERSION = "0.9.0";
+declare const PROTOCOL_VERSION = "0.10.0";
 //#endregion
 //#region src/index.d.ts
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */

package/dist/index.js

@@ -26,7 +26,8 @@ var aggregates_schema_default = {
 				"0.6.0",
 				"0.7.0",
 				"0.8.0",
-				"0.9.0"
+				"0.9.0",
+				"0.10.0"
 			],
 			"description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
 		},
@@ -256,7 +257,7 @@ var aggregates_schema_default = {
 					"type": "string",
 					"minLength": 1,
 					"maxLength": 256,
-					"description": "Normalised route template, e.g. /products/:id, or (other)."
+					"description": "Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56)."
 				},
 				"count": {
 					"type": "integer",
@@ -500,10 +501,11 @@ var aggregates_schema_default = {
 					"enum": [
 						"postgres",
 						"mysql",
+						"mongodb",
 						"redis",
 						"http"
 					],
-					"description": "What kind of dependency this is."
+					"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`)."
 				},
 				"target": {
 					"type": "string",
@@ -591,7 +593,7 @@ var aggregates_schema_default = {
 					"type": "string",
 					"minLength": 1,
 					"maxLength": 256,
-					"description": "Normalised route template, e.g. /products/:id, or (other)."
+					"description": "Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56)."
 				},
 				"operations": {
 					"type": "array",
@@ -647,7 +649,7 @@ var aggregates_schema_default = {
 				"text": {
 					"type": "string",
 					"maxLength": 1024,
-					"description": "Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `POST api.stripe.com` for a call and `HGETALL cache:6379` for a command. A call's and a command's are a word and the place it went — the method and the host, the command's name and its server — and never a path, a query string, a key or an argument (invariant 5): the schema refuses one with anything after the place, or a slash, a question mark or a hash in it. Optional: a user who would rather not send it keeps the whole analysis, only without the label, and a sender in minimal mode, or one withholding the name of the dependency, sends none."
+					"description": "Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `find users` for a MongoDB command — its name and its collection, never the filter or the documents —, `POST api.stripe.com` for a call and `HGETALL cache:6379` for a command. A call's and a command's are a word and the place it went — the method and the host, the command's name and its server — and never a path, a query string, a key or an argument (invariant 5): the schema refuses one with anything after the place, or a slash, a question mark or a hash in it. Optional: a user who would rather not send it keeps the whole analysis, only without the label, and a sender in minimal mode, or one withholding the name of the dependency, sends none."
 				},
 				"count": {
 					"type": "integer",
@@ -943,7 +945,8 @@ var capture_evidence_schema_default = {
 				"0.6.0",
 				"0.7.0",
 				"0.8.0",
-				"0.9.0"
+				"0.9.0",
+				"0.10.0"
 			]
 		},
 		"instance": {
@@ -1024,7 +1027,7 @@ var capture_evidence_schema_default = {
 				"dependenciesTruncated": {
 					"type": "integer",
 					"minimum": 0,
-					"description": "Requests whose list of dependencies was truncated. Their count is real and their list is not complete."
+					"description": "Requests whose list of dependencies was truncated. Their count is real and their list is not complete. A sender that knows the field sends it, zero included. Absent in an evidence of protocol 0.9.0 or later is zero: @downtrace/agent 0.9.0 omitted it at zero. Absent in an earlier protocol is a sender older than the field, which did not say, and that is not none."
 				}
 			}
 		},
@@ -1465,6 +1468,7 @@ const EVIDENCE_REQUESTS_MAX_ITEMS_V0 = 4096;
 const DEPENDENCY_KINDS_V0 = [
 	"postgres",
 	"mysql",
+	"mongodb",
 	"redis",
 	"http"
 ];
@@ -1480,10 +1484,11 @@ const ACCEPTED_PROTOCOL_VERSIONS_V0 = [
 	"0.6.0",
 	"0.7.0",
 	"0.8.0",
-	"0.9.0"
+	"0.9.0",
+	"0.10.0"
 ];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-const PROTOCOL_VERSION = "0.9.0";
+const PROTOCOL_VERSION = "0.10.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.9.0",
+  "version": "0.10.0",
   "description": "Downtrace ingestion protocol: JSON Schema, fixtures and generated TypeScript types",
   "type": "module",
   "exports": {

package/schema/v0/aggregates.schema.json

@@ -10,7 +10,7 @@
   "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"],
+      "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"],
       "description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
     },
     "agent": {
@@ -225,7 +225,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 256,
-          "description": "Normalised route template, e.g. /products/:id, or (other)."
+          "description": "Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56)."
         },
         "count": {
           "type": "integer",
@@ -410,8 +410,8 @@
       "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."
+          "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`)."
         },
         "target": {
           "type": "string",
@@ -486,7 +486,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 256,
-          "description": "Normalised route template, e.g. /products/:id, or (other)."
+          "description": "Normalised route template, e.g. /products/:id, or a name that is not a route: (other), what the interval's cap on routes left out, or (unmatched), the requests that no route of the framework named (DT-56)."
         },
         "operations": {
           "type": "array",
@@ -532,7 +532,7 @@
         "text": {
           "type": "string",
           "maxLength": 1024,
-          "description": "Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `POST api.stripe.com` for a call and `HGETALL cache:6379` for a command. A call's and a command's are a word and the place it went — the method and the host, the command's name and its server — and never a path, a query string, a key or an argument (invariant 5): the schema refuses one with anything after the place, or a slash, a question mark or a hash in it. Optional: a user who would rather not send it keeps the whole analysis, only without the label, and a sender in minimal mode, or one withholding the name of the dependency, sends none."
+          "description": "Normalised text, e.g. `SELECT id FROM products WHERE id = ?` for a query, `find users` for a MongoDB command — its name and its collection, never the filter or the documents —, `POST api.stripe.com` for a call and `HGETALL cache:6379` for a command. A call's and a command's are a word and the place it went — the method and the host, the command's name and its server — and never a path, a query string, a key or an argument (invariant 5): the schema refuses one with anything after the place, or a slash, a question mark or a hash in it. Optional: a user who would rather not send it keeps the whole analysis, only without the label, and a sender in minimal mode, or one withholding the name of the dependency, sends none."
         },
         "count": {
           "type": "integer",

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

@@ -11,7 +11,7 @@
     "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"]
+      "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"]
     },
     "instance": {
       "type": "object",
@@ -96,7 +96,7 @@
         "dependenciesTruncated": {
           "type": "integer",
           "minimum": 0,
-          "description": "Requests whose list of dependencies was truncated. Their count is real and their list is not complete."
+          "description": "Requests whose list of dependencies was truncated. Their count is real and their list is not complete. A sender that knows the field sends it, zero included. Absent in an evidence of protocol 0.9.0 or later is zero: @downtrace/agent 0.9.0 omitted it at zero. Absent in an earlier protocol is a sender older than the field, which did not say, and that is not none."
         }
       }
     },