@dash0/sdk-web 0.20.0 → 0.22.0

package/src/api/vcs.ts

@@ -0,0 +1,328 @@
+import { vars } from "../vars";
+import {
+  VCS_CHANGE_ID,
+  VCS_OWNER_NAME,
+  VCS_PROVIDER_NAME,
+  VCS_REF_HEAD_NAME,
+  VCS_REF_HEAD_REVISION,
+  VCS_REPOSITORY_NAME,
+  VCS_REPOSITORY_URL_FULL,
+} from "../semantic-conventions";
+import { InitOptions, VcsAttributes } from "../types/options";
+import { addAttribute } from "../utils/otel";
+import { BrowserBuildEnv, pickFirstString } from "./browser-env";
+
+declare const process: { env?: BrowserBuildEnv } | undefined;
+
+// Single source of truth mapping each VcsAttributes field to its OTel
+// resource attribute name. Typed as `Record<keyof VcsAttributes, string>` so
+// adding a field to VcsAttributes without adding an entry here is a compile
+// error — no silent "I forgot to apply that field" bugs.
+const VCS_FIELD_TO_ATTRIBUTE: Record<keyof VcsAttributes, string> = {
+  providerName: VCS_PROVIDER_NAME,
+  ownerName: VCS_OWNER_NAME,
+  repositoryName: VCS_REPOSITORY_NAME,
+  repositoryUrlFull: VCS_REPOSITORY_URL_FULL,
+  refHeadName: VCS_REF_HEAD_NAME,
+  refHeadRevision: VCS_REF_HEAD_REVISION,
+  changeId: VCS_CHANGE_ID,
+};
+
+/**
+ * Derive VCS (version control) context from the build environment and apply
+ * the resulting `vcs.*` resource attributes to `vars.resource.attributes`.
+ *
+ * Detection precedence per attribute: `opts.vcs` → Vercel env vars → Netlify
+ * env vars. Manual overrides via `opts.vcs` always win, even when
+ * `opts.disableVcsDetection` is set.
+ */
+export function applyVcsResourceAttributes(opts: InitOptions) {
+  const vcs = detectVcs(opts);
+  for (const field of Object.keys(VCS_FIELD_TO_ATTRIBUTE) as (keyof VcsAttributes)[]) {
+    const value = vcs[field];
+    if (value) {
+      addAttribute(vars.resource.attributes, VCS_FIELD_TO_ATTRIBUTE[field], value);
+    }
+  }
+}
+
+function detectVcs(opts: InitOptions): VcsAttributes {
+  // opts.vcs manual overrides always win, even when auto-detection is disabled.
+  // This lets callers on non-Vercel/Netlify platforms supply context explicitly
+  // while still opting out of any env-var reading.
+  const override = opts.vcs ?? {};
+
+  if (opts.disableVcsDetection) {
+    return override;
+  }
+
+  const vercel = detectVcsFromVercel();
+  const netlify = detectVcsFromNetlify();
+
+  return {
+    providerName: override.providerName ?? vercel.providerName ?? netlify.providerName,
+    ownerName: override.ownerName ?? vercel.ownerName ?? netlify.ownerName,
+    repositoryName: override.repositoryName ?? vercel.repositoryName ?? netlify.repositoryName,
+    repositoryUrlFull: override.repositoryUrlFull ?? vercel.repositoryUrlFull ?? netlify.repositoryUrlFull,
+    refHeadName: override.refHeadName ?? vercel.refHeadName ?? netlify.refHeadName,
+    refHeadRevision: override.refHeadRevision ?? vercel.refHeadRevision ?? netlify.refHeadRevision,
+    changeId: override.changeId ?? vercel.changeId ?? netlify.changeId,
+  };
+}
+
+// Frameworks expose env vars to the browser bundle using a per-framework
+// prefix (Next.js `NEXT_PUBLIC_*`, Vite `VITE_*`, etc.). For each known
+// vendor suffix (e.g. Vercel's `VERCEL_GIT_PROVIDER`, Netlify's
+// `REPOSITORY_URL`) we enumerate the prefixed variants below.
+//
+// IMPORTANT: each `process.env.NAME` MUST be a LITERAL accessor. Webpack
+// DefinePlugin, Next.js, Gatsby, and equivalents substitute env vars at
+// build time only when they see the literal form. Dynamic lookups like
+// `process.env[name]` or iterating a string array are NOT substituted —
+// they would resolve to `undefined` in the browser bundle.
+//
+// The 9 prefixes below are the framework presets Vercel auto-prefixes
+// `VERCEL_*` system vars under (https://vercel.com/docs/environment-variables/framework-environment-variables).
+// Users on platforms without auto-prefixing (Netlify, Cloudflare Pages, custom
+// CI) can manually expose any env var under any of these prefixes and get
+// the same auto-detection.
+//
+// Adding a new framework prefix = one new literal accessor per attribute in
+// each `detectVcsFrom*` function below.
+
+function detectVcsFromVercel(): VcsAttributes {
+  let provider: string | undefined;
+  let owner: string | undefined;
+  let repo: string | undefined;
+  let ref: string | undefined;
+  let revision: string | undefined;
+  let changeId: string | undefined;
+  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,
+      process?.env?.VITE_VERCEL_GIT_PROVIDER,
+      process?.env?.PUBLIC_VERCEL_GIT_PROVIDER,
+      process?.env?.VUE_APP_VERCEL_GIT_PROVIDER,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_PROVIDER,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_PROVIDER
+    );
+    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,
+      process?.env?.VITE_VERCEL_GIT_REPO_OWNER,
+      process?.env?.PUBLIC_VERCEL_GIT_REPO_OWNER,
+      process?.env?.VUE_APP_VERCEL_GIT_REPO_OWNER,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_REPO_OWNER,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_REPO_OWNER
+    );
+    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,
+      process?.env?.VITE_VERCEL_GIT_REPO_SLUG,
+      process?.env?.PUBLIC_VERCEL_GIT_REPO_SLUG,
+      process?.env?.VUE_APP_VERCEL_GIT_REPO_SLUG,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_REPO_SLUG,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_REPO_SLUG
+    );
+    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,
+      process?.env?.VITE_VERCEL_GIT_COMMIT_REF,
+      process?.env?.PUBLIC_VERCEL_GIT_COMMIT_REF,
+      process?.env?.VUE_APP_VERCEL_GIT_COMMIT_REF,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_COMMIT_REF,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_COMMIT_REF
+    );
+    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,
+      process?.env?.VITE_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.PUBLIC_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.VUE_APP_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_COMMIT_SHA
+    );
+    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,
+      process?.env?.VITE_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.VUE_APP_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_PULL_REQUEST_ID
+    );
+  } catch (_ignored) {
+    // process is not defined (or a bundler shimmed it strangely) — skip.
+  }
+
+  return {
+    providerName: provider,
+    ownerName: owner,
+    repositoryName: repo,
+    repositoryUrlFull: buildRepositoryUrlFromVercel(provider, owner, repo),
+    refHeadName: ref,
+    refHeadRevision: revision,
+    changeId,
+  };
+}
+
+function detectVcsFromNetlify(): VcsAttributes {
+  // Netlify exposes read-only build env vars (REPOSITORY_URL, BRANCH,
+  // COMMIT_REF, REVIEW_ID) but does not auto-prefix them for browser
+  // exposure. Users must surface them via their framework's prefix
+  // convention themselves (e.g. `NEXT_PUBLIC_REPOSITORY_URL = $REPOSITORY_URL`
+  // for Next.js, `VITE_REPOSITORY_URL = $REPOSITORY_URL` for Vite, etc.).
+  // We enumerate the same 9 framework prefixes as the Vercel path above.
+  let repositoryUrl: string | undefined;
+  let branch: string | undefined;
+  let commit: string | undefined;
+  let reviewId: string | undefined;
+  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,
+      process?.env?.VITE_REPOSITORY_URL,
+      process?.env?.PUBLIC_REPOSITORY_URL,
+      process?.env?.VUE_APP_REPOSITORY_URL,
+      process?.env?.REDWOOD_ENV_REPOSITORY_URL,
+      process?.env?.SANITY_STUDIO_REPOSITORY_URL
+    );
+    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,
+      process?.env?.VITE_BRANCH,
+      process?.env?.PUBLIC_BRANCH,
+      process?.env?.VUE_APP_BRANCH,
+      process?.env?.REDWOOD_ENV_BRANCH,
+      process?.env?.SANITY_STUDIO_BRANCH
+    );
+    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,
+      process?.env?.VITE_COMMIT_REF,
+      process?.env?.PUBLIC_COMMIT_REF,
+      process?.env?.VUE_APP_COMMIT_REF,
+      process?.env?.REDWOOD_ENV_COMMIT_REF,
+      process?.env?.SANITY_STUDIO_COMMIT_REF
+    );
+    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,
+      process?.env?.VITE_REVIEW_ID,
+      process?.env?.PUBLIC_REVIEW_ID,
+      process?.env?.VUE_APP_REVIEW_ID,
+      process?.env?.REDWOOD_ENV_REVIEW_ID,
+      process?.env?.SANITY_STUDIO_REVIEW_ID
+    );
+  } catch (_ignored) {
+    // process is not defined — skip.
+  }
+
+  const parsed = parseRepositoryUrl(repositoryUrl);
+  return {
+    providerName: parsed?.providerName,
+    ownerName: parsed?.ownerName,
+    repositoryName: parsed?.repositoryName,
+    repositoryUrlFull: repositoryUrl,
+    refHeadName: branch,
+    refHeadRevision: commit,
+    changeId: reviewId,
+  };
+}
+
+function buildRepositoryUrlFromVercel(
+  provider: string | undefined,
+  owner: string | undefined,
+  repo: string | undefined
+): string | undefined {
+  if (!provider || !owner || !repo) return undefined;
+  const host = vcsHostForProvider(provider);
+  if (!host) return undefined;
+  return `https://${host}/${owner}/${repo}`;
+}
+
+// Single source of truth for provider↔host mapping. Both `vcsHostForProvider`
+// (Vercel path: provider name is known, derive the canonical host) and
+// `vcsProviderForHost` (Netlify path: only the URL is known, derive the
+// provider) consult this map so adding a provider is one edit. Each entry is
+// a list of accepted hostnames; the FIRST entry is the canonical host used
+// when building URLs from a provider name. Subsequent entries are exact
+// aliases — we do not match arbitrary subdomains.
+const VCS_PROVIDER_HOSTS: Record<string, readonly string[]> = {
+  github: ["github.com", "gist.github.com"],
+  gitlab: ["gitlab.com"],
+  bitbucket: ["bitbucket.org"],
+};
+
+function vcsHostForProvider(provider: string): string | undefined {
+  return VCS_PROVIDER_HOSTS[provider]?.[0];
+}
+
+function parseRepositoryUrl(
+  url: string | undefined
+): { providerName: string; ownerName: string; repositoryName: string } | undefined {
+  if (!url) return undefined;
+
+  let host: string;
+  let pathname: string;
+  try {
+    const parsed = new URL(url);
+    host = parsed.host;
+    pathname = parsed.pathname;
+  } catch (_ignored) {
+    return undefined;
+  }
+
+  const provider = vcsProviderForHost(host);
+  if (!provider) return undefined;
+
+  const trimmed = pathname.replace(/^\/+/, "").replace(/\.git$/, "");
+  const segments = trimmed.split("/");
+  if (segments.length < 2) return undefined;
+
+  const ownerName = segments[0];
+  // Bitbucket and GitLab can have nested groups; the repository slug is the
+  // last path segment. GitHub paths are always two segments.
+  const repositoryName = segments[segments.length - 1];
+  if (!ownerName || !repositoryName) return undefined;
+
+  return { providerName: provider, ownerName, repositoryName };
+}
+
+function vcsProviderForHost(host: string): string | undefined {
+  for (const [provider, hosts] of Object.entries(VCS_PROVIDER_HOSTS)) {
+    if (hosts.includes(host)) return provider;
+  }
+  return undefined;
+}

package/src/semantic-conventions.ts

@@ -6,6 +6,15 @@ export const DEPLOYMENT_ENVIRONMENT_NAME = "deployment.environment.name";
 export const DEPLOYMENT_NAME = "deployment.name";
 export const DEPLOYMENT_ID = "deployment.id";
 
+// VCS Resource Attribute Keys
+export const VCS_PROVIDER_NAME = "vcs.provider.name";
+export const VCS_OWNER_NAME = "vcs.owner.name";
+export const VCS_REPOSITORY_NAME = "vcs.repository.name";
+export const VCS_REPOSITORY_URL_FULL = "vcs.repository.url.full";
+export const VCS_REF_HEAD_NAME = "vcs.ref.head.name";
+export const VCS_REF_HEAD_REVISION = "vcs.ref.head.revision";
+export const VCS_CHANGE_ID = "vcs.change.id";
+
 // Misc Signal Attribute Keys
 export const EVENT_NAME = "event.name";
 export const WEB_EVENT_TITLE = "dash0.web.event.title";

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

@@ -4,6 +4,29 @@ import { Endpoint, Vars, PropagatorConfig } from "../vars";
 
 export type InstrumentationName = "@dash0/navigation" | "@dash0/web-vitals" | "@dash0/error" | "@dash0/fetch";
 
+/**
+ * VCS (version control) context describing the build the SDK is running
+ * inside. Used both as the public manual-override shape on `InitOptions.vcs`
+ * and internally as the merged result of auto-detection. Each field maps to
+ * a standard OpenTelemetry `vcs.*` resource attribute.
+ */
+export type VcsAttributes = {
+  /** vcs.provider.name — e.g. "github", "gitlab", "bitbucket". */
+  providerName?: string;
+  /** vcs.owner.name — repository owner / organization. */
+  ownerName?: string;
+  /** vcs.repository.name — short repository name (no owner prefix). */
+  repositoryName?: string;
+  /** vcs.repository.url.full — canonical repository URL. */
+  repositoryUrlFull?: string;
+  /** vcs.ref.head.name — branch or tag name the build was made from. */
+  refHeadName?: string;
+  /** vcs.ref.head.revision — commit SHA the build was made from. */
+  refHeadRevision?: string;
+  /** vcs.change.id — pull/merge request identifier (preview deploys). */
+  changeId?: string;
+};
+
 export type InitOptions = {
   serviceName: string;
   serviceNamespace?: string;
@@ -28,6 +51,39 @@ export type InitOptions = {
    */
   rejectSuspiciousServiceName?: boolean;
 
+  /**
+   * When `true`, disable auto-detection of VCS (version control) context
+   * from the build environment. By default the SDK reads VCS context from
+   * 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
+   *   - vcs.owner.name
+   *   - vcs.repository.name
+   *   - vcs.repository.url.full
+   *   - vcs.ref.head.name
+   *   - vcs.ref.head.revision
+   *   - vcs.change.id
+   *
+   * Pairing telemetry with the git commit + branch the build came from lets
+   * Dash0 Agent answer questions like "which PR introduced this error?".
+   *
+   * Note: any fields supplied via `vcs` are still applied even when this flag
+   * is `true` — manual overrides always win. Set this flag when you want to
+   * prevent env-var reads entirely but still supply context explicitly.
+   */
+  disableVcsDetection?: boolean;
+
+  /**
+   * Manually specify VCS (version control) context. Each provided field
+   * overrides the value the SDK would otherwise auto-detect from the build
+   * environment for that attribute. Use this for non-Vercel/Netlify
+   * deployments, or when the auto-detected values are wrong.
+   */
+  vcs?: VcsAttributes;
+
   /**
    * OTLP endpoints to which the generated telemetry should be sent to.
    */
@@ -38,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,
 };