@dash0/sdk-web 0.21.0 → 0.22.0

package/src/api/browser-env.ts

@@ -0,0 +1,94 @@
+// Shared types and helpers for reading build-environment variables exposed
+// to the browser bundle. Owned by this module because it is used from both
+// init.ts (environment / deployment detection) and vcs.ts (VCS detection).
+//
+// IMPORTANT: each `process.env.NAME` MUST be a LITERAL accessor in the
+// caller's source. Webpack DefinePlugin, Next.js, Gatsby, and equivalents
+// substitute env vars at build time only when they see the literal form.
+// Dynamic lookups (`process.env[name]`, iterating a string array) are NOT
+// substituted — they resolve to `undefined` in the browser bundle.
+//
+// The type unions below are the single source of truth for which env var
+// names the SDK reads. They are composed via template-literal types so
+// every (prefix × suffix) combination is enumerated at the type level.
+// Adding a framework prefix is a one-line edit to `FrameworkPrefix`; adding
+// a suffix is a one-line edit to the appropriate suffix union.
+
+/**
+ * Framework prefixes the SDK reads as literal `process.env.{PREFIX}{SUFFIX}`
+ * accessors. Vercel auto-prefixes its `VERCEL_*` system vars under each
+ * (per https://vercel.com/docs/environment-variables/framework-environment-variables).
+ * Users on platforms without auto-prefixing (Netlify, Cloudflare Pages,
+ * custom CI) can expose env vars under any of these prefixes to get the
+ * same detection.
+ *
+ * Caveat: a prefix being listed here means the SDK *will read* a literal
+ * `process.env.{PREFIX}_X` accessor — it does not guarantee the consumer's
+ * bundler will substitute that accessor. Webpack-based bundlers (Next.js,
+ * Gatsby, CRA) substitute `process.env.X` literals by default. Vite reads
+ * env vars via `import.meta.env.VITE_*` by default; for `process.env.VITE_*`
+ * to be substituted in a Vite build the consumer must add
+ * `define: { 'process.env.VITE_X': JSON.stringify(...) }` to their Vite
+ * config, or use a `process.env` polyfill plugin. When deploying to Vercel
+ * the `VITE_VERCEL_*` substitution happens inside the build environment, so
+ * Vite + Vercel works out of the box; Vite users on other platforms need to
+ * surface env vars via their own bundler config.
+ *
+ * Keep `FRAMEWORK_PREFIX_SAMPLES` in `init_test.ts` in sync when adding a
+ * prefix here.
+ */
+export type FrameworkPrefix =
+  | "NEXT_PUBLIC_"
+  | "NUXT_PUBLIC_"
+  | "NUXT_ENV_"
+  | "REACT_APP_"
+  | "GATSBY_"
+  | "VITE_"
+  | "PUBLIC_"
+  | "VUE_APP_"
+  | "REDWOOD_ENV_"
+  | "SANITY_STUDIO_";
+
+/** Vercel system env vars consumed by detectEnvironment / detectDeploymentName / detectDeploymentId. */
+type VercelDeploymentSuffix = "VERCEL_ENV" | "VERCEL_TARGET_ENV" | "VERCEL_BRANCH_URL";
+
+/** Vercel git env vars consumed by VCS detection. */
+type VercelGitSuffix =
+  | "VERCEL_GIT_PROVIDER"
+  | "VERCEL_GIT_REPO_OWNER"
+  | "VERCEL_GIT_REPO_SLUG"
+  | "VERCEL_GIT_COMMIT_REF"
+  | "VERCEL_GIT_COMMIT_SHA"
+  | "VERCEL_GIT_PULL_REQUEST_ID";
+
+/** Netlify build env vars (Netlify does not auto-prefix; users surface these via their framework convention). */
+type NetlifyGitSuffix = "REPOSITORY_URL" | "BRANCH" | "COMMIT_REF" | "REVIEW_ID";
+
+/** Every env var name the SDK reads as a literal `process.env.X` accessor. */
+type BrowserBuildEnvKey = `${FrameworkPrefix}${VercelDeploymentSuffix | VercelGitSuffix | NetlifyGitSuffix}`;
+
+/**
+ * Module-locally typed shape of `process.env`. Consumers re-declare `process`
+ * with this type so dot-notation accessors are typed (no `@ts-expect-error`)
+ * and `noPropertyAccessFromIndexSignature` does not fire (each key is a
+ * known union member, not an index signature).
+ */
+export type BrowserBuildEnv = { readonly [K in BrowserBuildEnvKey]?: string };
+
+/**
+ * Return the first truthy value, or undefined. Used to walk the list of
+ * framework-prefixed variants of an env var and pick whichever the user's
+ * bundler substituted at build time.
+ *
+ * The falsy check skips empty strings as well as undefined — bundlers that
+ * do not substitute a literal leave it as `undefined`, not `""`, so empty
+ * is treated as "not set". This is intentional and matches every known
+ * `VERCEL_GIT_*` / `REPOSITORY_URL` / etc. value shape (non-empty strings
+ * or absent; Vercel PR IDs are positive integer strings, never `"0"`).
+ */
+export function pickFirstString(...values: (string | undefined)[]): string | undefined {
+  for (const value of values) {
+    if (value) return value;
+  }
+  return undefined;
+}

package/src/api/init.ts

@@ -12,6 +12,7 @@ import {
 import {
   fetch,
   generateUniqueId,
+  isSessionSampledIn,
   isSafeServiceName,
   PAGE_LOAD_ID_BYTES,
   warn,
@@ -23,7 +24,7 @@ import {
   pick,
   loc,
 } from "../utils";
-import { trackSessions } from "./session";
+import { sessionId, trackSessions } from "./session";
 import { startWebVitalsInstrumentation } from "../instrumentations/web-vitals";
 import { startErrorInstrumentation } from "../instrumentations/errors";
 import { addAttribute } from "../utils/otel";
@@ -32,8 +33,11 @@ import { startNavigationInstrumentation } from "../instrumentations/navigation";
 import { merge } from "ts-deepmerge";
 import { initializeTabId } from "../utils/tab-id";
 import { InitOptions, InstrumentationName } from "../types/options";
+import { BrowserBuildEnv, pickFirstString } from "./browser-env";
 import { applyVcsResourceAttributes } from "./vcs";
 
+declare const process: { env?: BrowserBuildEnv } | undefined;
+
 let hasBeenInitialised: boolean = false;
 
 export function init(opts: InitOptions) {
@@ -94,6 +98,17 @@ export function init(opts: InitOptions) {
   initializeTabId();
   trackSessions(opts.sessionInactivityTimeoutMillis, opts.sessionTerminationTimeoutMillis);
 
+  if (opts.sessionSamplingRate != null) {
+    const rate = Math.max(0, Math.min(100, opts.sessionSamplingRate));
+    vars.isSessionSampled = sessionId != null ? isSessionSampledIn(sessionId, rate) : rate > 0;
+  }
+
+  if (!vars.isSessionSampled) {
+    debug("Session is not sampled. No telemetry will be transmitted for this session.");
+    hasBeenInitialised = true;
+    return;
+  }
+
   if (isInstrumentationEnabled("@dash0/navigation", opts)) {
     startNavigationInstrumentation();
   }
@@ -158,18 +173,30 @@ function isClient() {
   return win != null;
 }
 
+// Vercel auto-prefixes its system env vars under every framework preset
+// (see https://vercel.com/docs/environment-variables/framework-environment-variables).
+// The shared `FrameworkPrefix` union in `./browser-env` is the single source
+// of truth for which prefixes the SDK recognises. To add a new prefix, edit
+// it there; the literal accessors below pick it up automatically via the
+// typed `process.env` declaration.
+
 function detectEnvironment(opts: InitOptions): string | undefined {
-  // if there is a manually specified value we use that
   if (opts.environment) {
     return opts.environment;
   }
-
-  // if process isn't defined access to it causes an exception, but we can't check for its present due to how
-  // plugins like webpack define work.
   try {
-    // vercel
-    // @ts-expect-error -- we need to access like this to allow webpack in the nextjs build to replace this
-    return process?.env?.NEXT_PUBLIC_VERCEL_ENV;
+    return pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_ENV,
+      process?.env?.NUXT_PUBLIC_VERCEL_ENV,
+      process?.env?.NUXT_ENV_VERCEL_ENV,
+      process?.env?.REACT_APP_VERCEL_ENV,
+      process?.env?.GATSBY_VERCEL_ENV,
+      process?.env?.VITE_VERCEL_ENV,
+      process?.env?.PUBLIC_VERCEL_ENV,
+      process?.env?.VUE_APP_VERCEL_ENV,
+      process?.env?.REDWOOD_ENV_VERCEL_ENV,
+      process?.env?.SANITY_STUDIO_VERCEL_ENV
+    );
   } catch (_ignored) {
     return undefined;
   }
@@ -179,13 +206,19 @@ function detectDeploymentName(opts: InitOptions): string | undefined {
   if (opts.deploymentName) {
     return opts.deploymentName;
   }
-
-  // if process isn't defined access to it causes an exception, but we can't check for its present due to how
-  // plugins like webpack define work.
   try {
-    // vercel
-    // @ts-expect-error -- we need to access like this to allow webpack in the nextjs build to replace this
-    return process?.env?.NEXT_PUBLIC_VERCEL_TARGET_ENV;
+    return pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_TARGET_ENV,
+      process?.env?.NUXT_PUBLIC_VERCEL_TARGET_ENV,
+      process?.env?.NUXT_ENV_VERCEL_TARGET_ENV,
+      process?.env?.REACT_APP_VERCEL_TARGET_ENV,
+      process?.env?.GATSBY_VERCEL_TARGET_ENV,
+      process?.env?.VITE_VERCEL_TARGET_ENV,
+      process?.env?.PUBLIC_VERCEL_TARGET_ENV,
+      process?.env?.VUE_APP_VERCEL_TARGET_ENV,
+      process?.env?.REDWOOD_ENV_VERCEL_TARGET_ENV,
+      process?.env?.SANITY_STUDIO_VERCEL_TARGET_ENV
+    );
   } catch (_ignored) {
     return undefined;
   }
@@ -195,13 +228,19 @@ function detectDeploymentId(opts: InitOptions): string | undefined {
   if (opts.deploymentId) {
     return opts.deploymentId;
   }
-
-  // if process isn't defined access to it causes an exception, but we can't check for its present due to how
-  // plugins like webpack define work.
   try {
-    // vercel
-    // @ts-expect-error -- we need to access like this to allow webpack in the nextjs build to replace this
-    return process?.env?.NEXT_PUBLIC_VERCEL_BRANCH_URL;
+    return pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_BRANCH_URL,
+      process?.env?.NUXT_PUBLIC_VERCEL_BRANCH_URL,
+      process?.env?.NUXT_ENV_VERCEL_BRANCH_URL,
+      process?.env?.REACT_APP_VERCEL_BRANCH_URL,
+      process?.env?.GATSBY_VERCEL_BRANCH_URL,
+      process?.env?.VITE_VERCEL_BRANCH_URL,
+      process?.env?.PUBLIC_VERCEL_BRANCH_URL,
+      process?.env?.VUE_APP_VERCEL_BRANCH_URL,
+      process?.env?.REDWOOD_ENV_VERCEL_BRANCH_URL,
+      process?.env?.SANITY_STUDIO_VERCEL_BRANCH_URL
+    );
   } catch (_ignored) {
     return undefined;
   }

package/src/api/init_test.ts

@@ -2,6 +2,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { InitOptions, InstrumentationName } from "../types/options";
 import { PropagatorConfig, Vars } from "../vars";
 import {
+  DEPLOYMENT_ENVIRONMENT_NAME,
+  DEPLOYMENT_ID,
+  DEPLOYMENT_NAME,
   SERVICE_NAME,
   SERVICE_NAMESPACE,
   VCS_CHANGE_ID,
@@ -440,7 +443,8 @@ describe("init", () => {
     // detectVcsFromVercel is actually wired up.
     const FRAMEWORK_PREFIX_SAMPLES: Array<[label: string, prefix: string]> = [
       ["Next.js", "NEXT_PUBLIC_"],
-      ["Nuxt", "NUXT_ENV_"],
+      ["Nuxt 3", "NUXT_PUBLIC_"],
+      ["Nuxt 2", "NUXT_ENV_"],
       ["Create React App", "REACT_APP_"],
       ["Gatsby", "GATSBY_"],
       ["Vite", "VITE_"],
@@ -684,4 +688,69 @@ describe("init", () => {
       expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
     });
   });
+
+  describe("environment + deployment auto-detection", () => {
+    afterEach(() => {
+      vi.unstubAllEnvs();
+    });
+
+    const stringAttr = (key: string) => vars.resource.attributes.find((attr) => attr.key === key)?.value.stringValue;
+
+    // The 9 framework prefixes Vercel auto-prefixes its `VERCEL_*` system
+    // vars under (per https://vercel.com/docs/environment-variables/framework-environment-variables).
+    // Same matrix the VCS detection uses, sourced from the shared
+    // `FrameworkPrefix` union in `./browser-env`.
+    const FRAMEWORK_PREFIX_SAMPLES: Array<[label: string, prefix: string]> = [
+      ["Next.js", "NEXT_PUBLIC_"],
+      ["Nuxt 3", "NUXT_PUBLIC_"],
+      ["Nuxt 2", "NUXT_ENV_"],
+      ["Create React App", "REACT_APP_"],
+      ["Gatsby", "GATSBY_"],
+      ["Vite", "VITE_"],
+      ["Astro / SvelteKit / Hydrogen", "PUBLIC_"],
+      ["Vue CLI", "VUE_APP_"],
+      ["RedwoodJS", "REDWOOD_ENV_"],
+      ["Sanity Studio", "SANITY_STUDIO_"],
+    ];
+
+    it.each(FRAMEWORK_PREFIX_SAMPLES)(
+      "derives environment + deployment resource attributes from %s framework prefix (%s)",
+      (_label, prefix) => {
+        vi.stubEnv(`${prefix}VERCEL_ENV`, "production");
+        vi.stubEnv(`${prefix}VERCEL_TARGET_ENV`, "production");
+        vi.stubEnv(`${prefix}VERCEL_BRANCH_URL`, "my-site-git-main.vercel.app");
+
+        init(baseOptions);
+
+        expect(stringAttr(DEPLOYMENT_ENVIRONMENT_NAME)).toBe("production");
+        expect(stringAttr(DEPLOYMENT_NAME)).toBe("production");
+        expect(stringAttr(DEPLOYMENT_ID)).toBe("my-site-git-main.vercel.app");
+      }
+    );
+
+    it("opts.environment / opts.deploymentName / opts.deploymentId override env-var detection", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_ENV", "from-env");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_TARGET_ENV", "from-env");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_BRANCH_URL", "from-env");
+
+      init({
+        ...baseOptions,
+        environment: "manual-environment",
+        deploymentName: "manual-deployment-name",
+        deploymentId: "manual-deployment-id",
+      });
+
+      expect(stringAttr(DEPLOYMENT_ENVIRONMENT_NAME)).toBe("manual-environment");
+      expect(stringAttr(DEPLOYMENT_NAME)).toBe("manual-deployment-name");
+      expect(stringAttr(DEPLOYMENT_ID)).toBe("manual-deployment-id");
+    });
+
+    it("emits no environment/deployment attributes when neither env vars nor opts are set", () => {
+      init(baseOptions);
+
+      expect(stringAttr(DEPLOYMENT_ENVIRONMENT_NAME)).toBeUndefined();
+      expect(stringAttr(DEPLOYMENT_NAME)).toBeUndefined();
+      expect(stringAttr(DEPLOYMENT_ID)).toBeUndefined();
+    });
+  });
 });

package/src/api/vcs.ts

@@ -10,41 +10,7 @@ import {
 } from "../semantic-conventions";
 import { InitOptions, VcsAttributes } from "../types/options";
 import { addAttribute } from "../utils/otel";
-
-// Module-local typing for the `process` global. The SDK does not depend on
-// @types/node, and bundler substitution requires literal `process.env.NAME`
-// accessors (dot notation, not bracket lookup). We enumerate the exact set of
-// env var names the readers below access via template-literal types — typos
-// are caught at compile time, and `noPropertyAccessFromIndexSignature` does
-// not fire because each key is a known union member, not an index signature.
-//
-// Adding a new framework prefix here automatically permits every combination
-// with every known suffix. Adding a vendor suffix permits every combination
-// with every known prefix.
-type FrameworkPrefix =
-  | "NEXT_PUBLIC_"
-  | "NUXT_ENV_"
-  | "REACT_APP_"
-  | "GATSBY_"
-  | "VITE_"
-  | "PUBLIC_"
-  | "VUE_APP_"
-  | "REDWOOD_ENV_"
-  | "SANITY_STUDIO_";
-
-type VercelGitSuffix =
-  | "VERCEL_GIT_PROVIDER"
-  | "VERCEL_GIT_REPO_OWNER"
-  | "VERCEL_GIT_REPO_SLUG"
-  | "VERCEL_GIT_COMMIT_REF"
-  | "VERCEL_GIT_COMMIT_SHA"
-  | "VERCEL_GIT_PULL_REQUEST_ID";
-
-type NetlifyGitSuffix = "REPOSITORY_URL" | "BRANCH" | "COMMIT_REF" | "REVIEW_ID";
-
-type BrowserBuildEnvKey = `${FrameworkPrefix}${VercelGitSuffix | NetlifyGitSuffix}`;
-
-type BrowserBuildEnv = { readonly [K in BrowserBuildEnvKey]?: string };
+import { BrowserBuildEnv, pickFirstString } from "./browser-env";
 
 declare const process: { env?: BrowserBuildEnv } | undefined;
 
@@ -134,6 +100,7 @@ function detectVcsFromVercel(): VcsAttributes {
   try {
     provider = pickFirstString(
       process?.env?.NEXT_PUBLIC_VERCEL_GIT_PROVIDER,
+      process?.env?.NUXT_PUBLIC_VERCEL_GIT_PROVIDER,
       process?.env?.NUXT_ENV_VERCEL_GIT_PROVIDER,
       process?.env?.REACT_APP_VERCEL_GIT_PROVIDER,
       process?.env?.GATSBY_VERCEL_GIT_PROVIDER,
@@ -145,6 +112,7 @@ function detectVcsFromVercel(): VcsAttributes {
     );
     owner = pickFirstString(
       process?.env?.NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER,
+      process?.env?.NUXT_PUBLIC_VERCEL_GIT_REPO_OWNER,
       process?.env?.NUXT_ENV_VERCEL_GIT_REPO_OWNER,
       process?.env?.REACT_APP_VERCEL_GIT_REPO_OWNER,
       process?.env?.GATSBY_VERCEL_GIT_REPO_OWNER,
@@ -156,6 +124,7 @@ function detectVcsFromVercel(): VcsAttributes {
     );
     repo = pickFirstString(
       process?.env?.NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG,
+      process?.env?.NUXT_PUBLIC_VERCEL_GIT_REPO_SLUG,
       process?.env?.NUXT_ENV_VERCEL_GIT_REPO_SLUG,
       process?.env?.REACT_APP_VERCEL_GIT_REPO_SLUG,
       process?.env?.GATSBY_VERCEL_GIT_REPO_SLUG,
@@ -167,6 +136,7 @@ function detectVcsFromVercel(): VcsAttributes {
     );
     ref = pickFirstString(
       process?.env?.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF,
+      process?.env?.NUXT_PUBLIC_VERCEL_GIT_COMMIT_REF,
       process?.env?.NUXT_ENV_VERCEL_GIT_COMMIT_REF,
       process?.env?.REACT_APP_VERCEL_GIT_COMMIT_REF,
       process?.env?.GATSBY_VERCEL_GIT_COMMIT_REF,
@@ -178,6 +148,7 @@ function detectVcsFromVercel(): VcsAttributes {
     );
     revision = pickFirstString(
       process?.env?.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.NUXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
       process?.env?.NUXT_ENV_VERCEL_GIT_COMMIT_SHA,
       process?.env?.REACT_APP_VERCEL_GIT_COMMIT_SHA,
       process?.env?.GATSBY_VERCEL_GIT_COMMIT_SHA,
@@ -189,6 +160,7 @@ function detectVcsFromVercel(): VcsAttributes {
     );
     changeId = pickFirstString(
       process?.env?.NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.NUXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
       process?.env?.NUXT_ENV_VERCEL_GIT_PULL_REQUEST_ID,
       process?.env?.REACT_APP_VERCEL_GIT_PULL_REQUEST_ID,
       process?.env?.GATSBY_VERCEL_GIT_PULL_REQUEST_ID,
@@ -227,6 +199,7 @@ function detectVcsFromNetlify(): VcsAttributes {
   try {
     repositoryUrl = pickFirstString(
       process?.env?.NEXT_PUBLIC_REPOSITORY_URL,
+      process?.env?.NUXT_PUBLIC_REPOSITORY_URL,
       process?.env?.NUXT_ENV_REPOSITORY_URL,
       process?.env?.REACT_APP_REPOSITORY_URL,
       process?.env?.GATSBY_REPOSITORY_URL,
@@ -238,6 +211,7 @@ function detectVcsFromNetlify(): VcsAttributes {
     );
     branch = pickFirstString(
       process?.env?.NEXT_PUBLIC_BRANCH,
+      process?.env?.NUXT_PUBLIC_BRANCH,
       process?.env?.NUXT_ENV_BRANCH,
       process?.env?.REACT_APP_BRANCH,
       process?.env?.GATSBY_BRANCH,
@@ -249,6 +223,7 @@ function detectVcsFromNetlify(): VcsAttributes {
     );
     commit = pickFirstString(
       process?.env?.NEXT_PUBLIC_COMMIT_REF,
+      process?.env?.NUXT_PUBLIC_COMMIT_REF,
       process?.env?.NUXT_ENV_COMMIT_REF,
       process?.env?.REACT_APP_COMMIT_REF,
       process?.env?.GATSBY_COMMIT_REF,
@@ -260,6 +235,7 @@ function detectVcsFromNetlify(): VcsAttributes {
     );
     reviewId = pickFirstString(
       process?.env?.NEXT_PUBLIC_REVIEW_ID,
+      process?.env?.NUXT_PUBLIC_REVIEW_ID,
       process?.env?.NUXT_ENV_REVIEW_ID,
       process?.env?.REACT_APP_REVIEW_ID,
       process?.env?.GATSBY_REVIEW_ID,
@@ -285,13 +261,6 @@ function detectVcsFromNetlify(): VcsAttributes {
   };
 }
 
-function pickFirstString(...values: (string | undefined)[]): string | undefined {
-  for (const value of values) {
-    if (value) return value;
-  }
-  return undefined;
-}
-
 function buildRepositoryUrlFromVercel(
   provider: string | undefined,
   owner: string | undefined,

package/src/transport/index.ts

@@ -21,6 +21,8 @@ function isRateLimited() {
 }
 
 export function sendLog(log: LogRecord): void {
+  if (!vars.isSessionSampled) return;
+
   if (isRateLimited()) {
     debug("Transport rate limit. Will not send item.", log);
     return;
@@ -49,6 +51,7 @@ function sendLogs(logs: LogRecord[]): void {
 
 export function sendSpan(span: Span | undefined): void {
   if (!span) return;
+  if (!vars.isSessionSampled) return;
 
   if (isRateLimited()) {
     debug("Transport rate limit. Will not send item.", span);

package/src/types/options.ts

@@ -54,9 +54,9 @@ export type InitOptions = {
   /**
    * When `true`, disable auto-detection of VCS (version control) context
    * from the build environment. By default the SDK reads VCS context from
-   * Vercel (`NEXT_PUBLIC_VERCEL_GIT_*`) and Netlify
-   * (`NEXT_PUBLIC_REPOSITORY_URL`, `NEXT_PUBLIC_BRANCH`,
-   * `NEXT_PUBLIC_COMMIT_REF`, `NEXT_PUBLIC_REVIEW_ID`) and applies the values
+   * Vercel (`<FRAMEWORK_PREFIX>VERCEL_GIT_*`) and Netlify
+   * (`<FRAMEWORK_PREFIX>REPOSITORY_URL`, `<FRAMEWORK_PREFIX>BRANCH`,
+   * `<FRAMEWORK_PREFIX>COMMIT_REF`, `<FRAMEWORK_PREFIX>REVIEW_ID`) and applies the values
    * as resource attributes following the OTel `vcs.*` semantic conventions:
    *
    *   - vcs.provider.name
@@ -94,6 +94,16 @@ export type InitOptions = {
    */
   enabledInstrumentations?: InstrumentationName[];
 
+  /**
+   * The percentage of sessions for which telemetry data is recorded and transmitted.
+   * Must be a number between 0 and 100.
+   * - 0: No sessions are recorded/transferred.
+   * - 100: All sessions are recorded/transferred (default).
+   * - Any other value: That percentage of sessions are recorded/transferred.
+   * The sampling decision is deterministic per session ID.
+   */
+  sessionSamplingRate?: number;
+
   /**
    * The  session inactivity timeout. Session inactivity is the maximum
    * allowed time to pass between two page loads before the session is considered

package/src/utils/index.ts

@@ -16,3 +16,4 @@ export * from "./url";
 export * from "./pick";
 export * from "./sanitize";
 export * from "./wrap";
+export * from "./session-sampling";

package/src/utils/session-sampling.ts

@@ -0,0 +1,15 @@
+import { crc32 } from "./crc32";
+
+/**
+ * Determines whether a session should be sampled based on the session ID
+ * and a configured sampling rate.
+ *
+ * @param sessionId The hex session ID string
+ * @param samplingRate A number between 0 and 100 (inclusive)
+ * @returns true if the session should be sampled (data collected), false otherwise
+ */
+export function isSessionSampledIn(sessionId: string, samplingRate: number): boolean {
+  if (samplingRate <= 0) return false;
+  if (samplingRate >= 100) return true;
+  return crc32(sessionId) % 100 < samplingRate;
+}

package/src/utils/session-sampling_test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { isSessionSampledIn } from "./session-sampling";
+import { generateSessionId } from "./session-id";
+
+describe("isSessionSampledIn", () => {
+  it("returns false when sampling rate is 0", () => {
+    expect(isSessionSampledIn("00abcdef01234567", 0)).toBe(false);
+  });
+
+  it("returns true when sampling rate is 100", () => {
+    expect(isSessionSampledIn("00abcdef01234567", 100)).toBe(true);
+  });
+
+  it("returns deterministic results for the same session ID and rate", () => {
+    const sessionId = "00abcdef01234567";
+    const rate = 50;
+    const result1 = isSessionSampledIn(sessionId, rate);
+    const result2 = isSessionSampledIn(sessionId, rate);
+    expect(result1).toBe(result2);
+  });
+
+  it("produces different results for different session IDs", () => {
+    const results = new Set<boolean>();
+    // Generate enough IDs to get both true and false with high probability
+    for (let i = 0; i < 100; i++) {
+      results.add(isSessionSampledIn(generateSessionId(), 50));
+    }
+    expect(results.size).toBe(2);
+  });
+
+  it("produces roughly correct distribution over many session IDs", () => {
+    const rate = 30;
+    const total = 10000;
+    let sampledIn = 0;
+
+    for (let i = 0; i < total; i++) {
+      if (isSessionSampledIn(generateSessionId(), rate)) {
+        sampledIn++;
+      }
+    }
+
+    const actualRate = sampledIn / total;
+    // Allow 5% tolerance
+    expect(actualRate).toBeGreaterThan(0.25);
+    expect(actualRate).toBeLessThan(0.35);
+  });
+
+  it("handles edge case: rate just above 0", () => {
+    // With rate=1, about 1% of sessions should be sampled in
+    let sampledIn = 0;
+    const total = 10000;
+    for (let i = 0; i < total; i++) {
+      if (isSessionSampledIn(generateSessionId(), 1)) {
+        sampledIn++;
+      }
+    }
+    const actualRate = sampledIn / total;
+    expect(actualRate).toBeGreaterThan(0.0);
+    expect(actualRate).toBeLessThan(0.05);
+  });
+
+  it("handles edge case: rate just below 100", () => {
+    // With rate=99, about 99% of sessions should be sampled in
+    let sampledIn = 0;
+    const total = 10000;
+    for (let i = 0; i < total; i++) {
+      if (isSessionSampledIn(generateSessionId(), 99)) {
+        sampledIn++;
+      }
+    }
+    const actualRate = sampledIn / total;
+    expect(actualRate).toBeGreaterThan(0.95);
+    expect(actualRate).toBeLessThan(1.0);
+  });
+
+  it("returns false for negative sampling rates", () => {
+    expect(isSessionSampledIn("00abcdef01234567", -10)).toBe(false);
+  });
+
+  it("returns true for sampling rates above 100", () => {
+    expect(isSessionSampledIn("00abcdef01234567", 150)).toBe(true);
+  });
+});

package/src/vars.ts

@@ -171,6 +171,12 @@ export type Vars = {
    * experimental - in rare cases causes Chrome to crash to use at your own risk.
    */
   enableTransportCompression: boolean;
+
+  /**
+   * Whether the current session is sampled in (true) or out (false).
+   * Determined at init time based on sessionSamplingRate and the session ID.
+   */
+  isSessionSampled: boolean;
 };
 
 export const vars: Vars = {
@@ -198,4 +204,5 @@ export const vars: Vars = {
     includeParts: [],
   },
   enableTransportCompression: false,
+  isSessionSampled: true,
 };