@velum-labs/routekit-telemetry-core 0.18.0 → 0.18.2

package/README.md

@@ -0,0 +1,28 @@
+# `@velum-labs/routekit-telemetry-core`
+
+Parameterized telemetry consent, redaction, and anonymous event plumbing.
+
+This package owns opt-in consent files, environment overrides, `DO_NOT_TRACK`
+handling, category toggles, install identity reset, schema inventory, event
+payload validation, redaction policy, and bounded shutdown helpers. It does not
+send events itself; product hosts provide the destination and transport.
+
+```ts
+import {
+  buildTelemetryEvent,
+  telemetryStatusMetadata,
+  anonymousEventProperties,
+  createConsentManager,
+  durationBucket
+} from "@velum-labs/routekit-telemetry-core";
+```
+
+Telemetry is off by default unless a host enables it through a persisted
+consent file or explicit environment variable. Disabled telemetry must avoid
+stable identity creation and discard queued events.
+
+## Boundaries
+
+- RouteKit daemon telemetry transport lives in `@velum-labs/routekit-daemon`.
+- OpenTelemetry tracing and span export policy live in `@velum-labs/routekit-tracing`.
+- Product telemetry inventory is documented in `../../docs/telemetry-inventory.md`.

package/dist/index.d.ts

@@ -65,7 +65,7 @@ declare const BILLING_MODES: readonly ["metered-api", "subscription", "upstream-
 declare const DIALECTS: readonly ["openai-chat", "openai-responses", "anthropic-messages", "openai-embeddings"];
 declare const REQUEST_KINDS: readonly ["chat", "responses", "messages", "embeddings"];
 declare const PREFERENCE_ACTIONS: readonly ["master", "category", "identity-reset"];
-declare const DAEMON_ACTIONS: readonly ["started", "stopped", "restarted", "reloaded"];
+declare const DAEMON_ACTIONS: readonly ["started", "stopped", "restarted", "reloaded", "roll_started", "roll_committed", "roll_failed"];
 export declare const TELEMETRY_EVENT_DEFINITIONS: {
     readonly "routekit.command_completed": {
         readonly category: "adoption";
@@ -149,7 +149,7 @@ export declare const TELEMETRY_EVENT_DEFINITIONS: {
             readonly action: {
                 readonly type: "string";
                 readonly maxLength: 16;
-                readonly values: readonly ["started", "stopped", "restarted", "reloaded"];
+                readonly values: readonly ["started", "stopped", "restarted", "reloaded", "roll_started", "roll_committed", "roll_failed"];
             };
             readonly outcome: {
                 readonly type: "string";
@@ -165,6 +165,37 @@ export declare const TELEMETRY_EVENT_DEFINITIONS: {
                 readonly type: "string";
                 readonly maxLength: 32;
             };
+            readonly reason: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["restart", "upgrade"];
+                readonly required: false;
+            };
+            readonly from_version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+                readonly required: false;
+            };
+            readonly to_version: {
+                readonly type: "string";
+                readonly maxLength: 32;
+                readonly required: false;
+            };
+            readonly rollback_stage: {
+                readonly type: "string";
+                readonly maxLength: 32;
+                readonly required: false;
+            };
+            readonly duration_bucket: {
+                readonly type: "string";
+                readonly maxLength: 16;
+                readonly values: readonly ["<1s", "1-10s", "10-60s", "1-5m", "5-30m", ">30m"];
+                readonly required: false;
+            };
+            readonly forced: {
+                readonly type: "boolean";
+                readonly required: false;
+            };
         };
     };
     readonly "routekit.gateway_usage_summary": {
@@ -329,6 +360,12 @@ export type TelemetryEventProperties = {
         outcome: (typeof OUTCOMES)[number];
         supervisor: "systemd" | "launchd" | "detached" | "unknown";
         version: string;
+        reason?: "restart" | "upgrade";
+        from_version?: string;
+        to_version?: string;
+        rollback_stage?: string;
+        duration_bucket?: (typeof DURATION_BUCKETS)[number];
+        forced?: boolean;
     };
     /** Gateway summaries are the only families permitted to carry canonical provider/model identifiers. */
     "routekit.gateway_usage_summary": {

package/dist/index.js

@@ -289,7 +289,15 @@ const DIALECTS = [
 ];
 const REQUEST_KINDS = ["chat", "responses", "messages", "embeddings"];
 const PREFERENCE_ACTIONS = ["master", "category", "identity-reset"];
-const DAEMON_ACTIONS = ["started", "stopped", "restarted", "reloaded"];
+const DAEMON_ACTIONS = [
+    "started",
+    "stopped",
+    "restarted",
+    "reloaded",
+    "roll_started",
+    "roll_committed",
+    "roll_failed"
+];
 export const TELEMETRY_EVENT_DEFINITIONS = {
     "routekit.command_completed": {
         category: "adoption",
@@ -325,7 +333,23 @@ export const TELEMETRY_EVENT_DEFINITIONS = {
                 maxLength: 16,
                 values: ["systemd", "launchd", "detached", "unknown"]
             },
-            version: { type: "string", maxLength: 32 }
+            version: { type: "string", maxLength: 32 },
+            reason: {
+                type: "string",
+                maxLength: 16,
+                values: ["restart", "upgrade"],
+                required: false
+            },
+            from_version: { type: "string", maxLength: 32, required: false },
+            to_version: { type: "string", maxLength: 32, required: false },
+            rollback_stage: { type: "string", maxLength: 32, required: false },
+            duration_bucket: {
+                type: "string",
+                maxLength: 16,
+                values: DURATION_BUCKETS,
+                required: false
+            },
+            forced: { type: "boolean", required: false }
         }
     },
     "routekit.gateway_usage_summary": {

package/dist/test/telemetry-core.test.js

@@ -138,7 +138,18 @@ test("schema inventory exposes exact category-truthful event families and fields
         },
         "routekit.daemon_lifecycle": {
             category: "reliability",
-            fields: ["action", "outcome", "supervisor", "version"]
+            fields: [
+                "action",
+                "outcome",
+                "supervisor",
+                "version",
+                "reason",
+                "from_version",
+                "to_version",
+                "rollback_stage",
+                "duration_bucket",
+                "forced"
+            ]
         },
         "routekit.gateway_usage_summary": {
             category: "usage",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-telemetry-core",
   "private": false,
-  "version": "0.18.0",
+  "version": "0.18.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -26,7 +26,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@velum-labs/routekit-runtime": "0.18.0"
+    "@velum-labs/routekit-runtime": "0.18.2"
   },
   "keywords": [
     "routekit",