@dash0/sdk-web 0.20.0 → 0.22.0

package/dist/types/api/browser-env.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare function pickFirstString(...values: (string | undefined)[]): string | undefined;
+export {};

package/dist/types/api/vcs.d.ts

@@ -0,0 +1,10 @@
+import { InitOptions } from "../types/options";
+/**
+ * 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 declare function applyVcsResourceAttributes(opts: InitOptions): void;

package/dist/types/semantic-conventions.d.ts

@@ -4,6 +4,13 @@ export declare const SERVICE_VERSION = "service.version";
 export declare const DEPLOYMENT_ENVIRONMENT_NAME = "deployment.environment.name";
 export declare const DEPLOYMENT_NAME = "deployment.name";
 export declare const DEPLOYMENT_ID = "deployment.id";
+export declare const VCS_PROVIDER_NAME = "vcs.provider.name";
+export declare const VCS_OWNER_NAME = "vcs.owner.name";
+export declare const VCS_REPOSITORY_NAME = "vcs.repository.name";
+export declare const VCS_REPOSITORY_URL_FULL = "vcs.repository.url.full";
+export declare const VCS_REF_HEAD_NAME = "vcs.ref.head.name";
+export declare const VCS_REF_HEAD_REVISION = "vcs.ref.head.revision";
+export declare const VCS_CHANGE_ID = "vcs.change.id";
 export declare const EVENT_NAME = "event.name";
 export declare const WEB_EVENT_TITLE = "dash0.web.event.title";
 export declare const WEB_EVENT_ID = "dash0.web.event.id";

package/dist/types/types/options.d.ts

@@ -2,6 +2,28 @@ import { AttributeValueType } from "../utils/otel";
 import { AnyValue } from "./otlp";
 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;
@@ -23,6 +45,37 @@ export type InitOptions = {
      * Set to `false` to opt out and pass the `serviceName` through unchanged.
      */
     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.
      */
@@ -31,6 +84,15 @@ export type InitOptions = {
      * Which instrumentations to enable. Defaults to undefined, which means all instrumentations.
      */
     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/dist/types/utils/index.d.ts

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

package/dist/types/utils/session-sampling.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function isSessionSampledIn(sessionId: string, samplingRate: number): boolean;

package/dist/types/utils/session-sampling_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/vars.d.ts

@@ -145,5 +145,10 @@ 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 declare const vars: Vars;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dash0/sdk-web",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Dash0's Web SDK to collect telemetry from end-users' web browsers",
   "type": "module",
   "main": "dist/dash0.umd.cjs",

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,6 +33,10 @@ 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;
 
@@ -93,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();
   }
@@ -134,6 +150,8 @@ function initializeResourceAttributes(opts: InitOptions) {
   if (deploymentId) {
     addAttribute(vars.resource.attributes, DEPLOYMENT_ID, deploymentId);
   }
+
+  applyVcsResourceAttributes(opts);
 }
 
 function initializeSignalAttributes(opts: InitOptions) {
@@ -155,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;
   }
@@ -176,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;
   }
@@ -192,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;
   }