feat: add telemetry (#58)

Author: ytkimirti

.github/workflows/release.yaml

@@ -22,7 +22,9 @@ jobs:
           node-version: 18
 
       - name: Set package version
-        run: echo $(jq --arg v "${{ env.VERSION }}" '(.version) = $v' package.json) > package.json
+        run: |
+          echo $(jq --arg v "${{ env.VERSION }}" '(.version) = $v' package.json) > package.json
+          echo "export const VERSION='${{ env.VERSION }}'" > ./version.ts
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v1

README.md

@@ -258,6 +258,22 @@ await namespace.fetch(["id-1", "id-2"]);
 
 If you wanna learn more about filtering check: [Metadata Filtering](https://upstash.com/docs/vector/features/filtering)
 
+## Telemetry
+
+This sdk sends anonymous telemetry data to help us improve your experience.
+We collect the following:
+
+- SDK version
+- Platform (Cloudflare, AWS or Vercel)
+- Runtime version ([email protected])
+
+You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
+to any truthy value.
+
+```sh
+UPSTASH_DISABLE_TELEMETRY=1
+```
+
 ## Troubleshooting
 
 We have a [Discord](upstash.com/discord) for common problems. If you can't find a solution, please [open an issue](https://github.com/upstash/vector-js/issues/new).

examples/nextjs/bun.lockb

@@ -173,4 +173,3 @@ describe("NAMESPACE", () => {
     });
   });
 });
-

src/commands/client/namespace/index.test.ts

@@ -142,7 +142,6 @@ export class Namespace<TIndexMetadata extends Dict = Dict> {
   query = <TMetadata extends Dict = TIndexMetadata>(args: CommandArgs<typeof QueryCommand>) =>
     new QueryCommand<TMetadata>(args, { namespace: this.namespace }).exec(this.client);
 
-
   /**
    * Initializes a resumable query operation on the vector database.
    * This method allows for querying large result sets in multiple chunks or implementing pagination.
@@ -169,9 +168,7 @@ export class Namespace<TIndexMetadata extends Dict = Dict> {
    * const secondBatch = await fetchNext(10);
    * await stop(); // End the query session
    */
-  resumableQuery = async <TMetadata extends Dict = TIndexMetadata>(
-    args: ResumableQueryPayload,
-  ) => {
+  resumableQuery = async <TMetadata extends Dict = TIndexMetadata>(args: ResumableQueryPayload) => {
     const resumableQuery = new ResumableQuery<TMetadata>(args, this.client, this.namespace);
     const initialQuery = await resumableQuery.start();
     const { fetchNext, stop } = resumableQuery;

src/commands/client/namespace/index.ts

@@ -3,6 +3,7 @@ import * as core from "./../vector";
 
 export type * from "@commands/types";
 import type { Dict } from "@commands/client/types";
+import { VERSION } from "../../version";
 
 /**
  * Connection credentials for upstash vector.
@@ -23,6 +24,14 @@ export type IndexConfig = {
    * For more check: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
    */
   signal?: AbortSignal;
+
+  /**
+   * Enable telemetry to help us improve the SDK.
+   * The sdk will send the sdk version, platform and node version as telemetry headers.
+   *
+   * @default true
+   */
+  enableTelemetry?: boolean;
 } & RequesterConfig;
 
 /**
@@ -73,10 +82,21 @@ export class Index<TIndexMetadata extends Dict = Dict> extends core.Index<TIndex
       console.warn("The vector token contains whitespace or newline, which can cause errors!");
     }
 
+    const enableTelemetry = safeProcess.UPSTASH_DISABLE_TELEMETRY
+      ? false
+      : (config?.enableTelemetry ?? true);
+
+    const telemetryHeaders: Record<string, string> = enableTelemetry
+      ? {
+          "Upstash-Telemetry-Sdk": `upstash-vector-js@${VERSION}`,
+          "Upstash-Telemetry-Platform": "cloudflare",
+        }
+      : {};
+
     const client = new HttpClient({
       baseUrl: url,
       retry: config?.retry,
-      headers: { authorization: `Bearer ${token}` },
+      headers: { authorization: `Bearer ${token}`, ...telemetryHeaders },
       signal: config?.signal,
       cache: config?.cache === false ? undefined : config?.cache,
     });
@@ -118,7 +138,13 @@ export class Index<TIndexMetadata extends Dict = Dict> extends core.Index<TIndex
       }
     }
 
-    return new Index({ ...config, url, token });
+    return new Index({
+      // @ts-expect-error We don't need to type this in the cf env type
+      enableTelemetry: env?.UPSTASH_DISABLE_TELEMETRY ? false : undefined,
+      ...config,
+      url,
+      token,
+    });
   }
 }
 

src/platforms/cloudflare.ts

@@ -1,8 +1,10 @@
 import { HttpClient, type Requester, type RequesterConfig } from "@http";
 import * as core from "./../vector";
+import type { Dict } from "@commands/client/types";
+import { VERSION } from "../../version";
+import { getRuntime } from "@utils/get-runtime";
 
 export type * from "@commands/types";
-import type { Dict } from "@commands/client/types";
 
 /**
  * Connection credentials for upstash vector.
@@ -23,6 +25,14 @@ export type IndexConfig = {
    * For more check: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
    */
   signal?: AbortSignal;
+
+  /**
+   * Enable telemetry to help us improve the SDK.
+   * The sdk will send the sdk version, platform and node version as telemetry headers.
+   *
+   * @default true
+   */
+  enableTelemetry?: boolean;
 } & RequesterConfig;
 
 /**
@@ -93,10 +103,26 @@ export class Index<TIndexMetadata extends Dict = Dict> extends core.Index<TIndex
       console.warn("The vector token contains whitespace or newline, which can cause errors!");
     }
 
+    const enableTelemetry = process.env.UPSTASH_DISABLE_TELEMETRY
+      ? false
+      : (configOrRequester?.enableTelemetry ?? true);
+
+    const telemetryHeaders: Record<string, string> = enableTelemetry
+      ? {
+          "Upstash-Telemetry-Sdk": `upstash-vector-js@${VERSION}`,
+          "Upstash-Telemetry-Platform": process.env.VERCEL
+            ? "vercel"
+            : process.env.AWS_REGION
+              ? "aws"
+              : "unknown",
+          "Upstash-Telemetry-Runtime": getRuntime(),
+        }
+      : {};
+
     const client = new HttpClient({
       baseUrl: url,
       retry: configOrRequester?.retry,
-      headers: { authorization: `Bearer ${token}` },
+      headers: { authorization: `Bearer ${token}`, ...telemetryHeaders },
       cache:
         configOrRequester?.cache === false ? undefined : configOrRequester?.cache || "no-store",
       signal: configOrRequester?.signal,

src/platforms/nodejs.ts

@@ -0,0 +1,7 @@
+export function getRuntime() {
+  if (typeof process === "object" && typeof process.versions == "object" && process.versions.bun)
+    return `bun@${process.versions.bun}`;
+
+  // @ts-expect-error Silence compiler
+  return typeof EdgeRuntime === "string" ? "edge-light" : `node@${process.version}`;
+}

src/utils/get-runtime.ts

@@ -0,0 +1 @@
+export const VERSION = "0.0.0";