@dash0/sdk-web 0.20.0 → 0.22.0

package/dist/modules/api/browser-env.js

@@ -0,0 +1,33 @@
+// 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.
+/**
+ * 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) {
+    for (const value of values) {
+        if (value)
+            return value;
+    }
+    return undefined;
+}

package/dist/modules/api/init.js

@@ -1,7 +1,7 @@
 import { vars } from "../vars";
 import { DEPLOYMENT_ENVIRONMENT_NAME, DEPLOYMENT_ID, DEPLOYMENT_NAME, PAGE_LOAD_ID, SERVICE_NAME, SERVICE_NAMESPACE, SERVICE_VERSION, USER_AGENT, } from "../semantic-conventions";
-import { fetch, generateUniqueId, isSafeServiceName, PAGE_LOAD_ID_BYTES, warn, debug, perf, nav, win, NO_VALUE_FALLBACK, pick, loc, } from "../utils";
-import { trackSessions } from "./session";
+import { fetch, generateUniqueId, isSessionSampledIn, isSafeServiceName, PAGE_LOAD_ID_BYTES, warn, debug, perf, nav, win, NO_VALUE_FALLBACK, pick, loc, } from "../utils";
+import { sessionId, trackSessions } from "./session";
 import { startWebVitalsInstrumentation } from "../instrumentations/web-vitals";
 import { startErrorInstrumentation } from "../instrumentations/errors";
 import { addAttribute } from "../utils/otel";
@@ -9,6 +9,8 @@ import { instrumentFetch } from "../instrumentations/http/fetch";
 import { startNavigationInstrumentation } from "../instrumentations/navigation";
 import { merge } from "ts-deepmerge";
 import { initializeTabId } from "../utils/tab-id";
+import { pickFirstString } from "./browser-env";
+import { applyVcsResourceAttributes } from "./vcs";
 let hasBeenInitialised = false;
 export function init(opts) {
     if (hasBeenInitialised) {
@@ -55,6 +57,15 @@ export function init(opts) {
     initializeSignalAttributes(opts);
     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();
     }
@@ -89,6 +100,7 @@ function initializeResourceAttributes(opts) {
     if (deploymentId) {
         addAttribute(vars.resource.attributes, DEPLOYMENT_ID, deploymentId);
     }
+    applyVcsResourceAttributes(opts);
 }
 function initializeSignalAttributes(opts) {
     addAttribute(vars.signalAttributes, PAGE_LOAD_ID, generateUniqueId(PAGE_LOAD_ID_BYTES));
@@ -105,17 +117,18 @@ function isSupported() {
 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) {
-    // 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;
@@ -125,12 +138,8 @@ function detectDeploymentName(opts) {
     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;
@@ -140,12 +149,8 @@ function detectDeploymentId(opts) {
     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/dist/modules/api/init_test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { SERVICE_NAME, SERVICE_NAMESPACE } from "../semantic-conventions";
+import { DEPLOYMENT_ENVIRONMENT_NAME, DEPLOYMENT_ID, DEPLOYMENT_NAME, SERVICE_NAME, SERVICE_NAMESPACE, 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";
 // Mock all the instrumentation modules
 vi.mock("../instrumentations/web-vitals", () => ({
     startWebVitalsInstrumentation: vi.fn(),
@@ -315,4 +315,275 @@ describe("init", () => {
             expect(serviceNameAttr?.value.stringValue).toBe("unknown");
         });
     });
+    describe("vcs auto-detection", () => {
+        afterEach(() => {
+            vi.unstubAllEnvs();
+        });
+        const stringAttr = (key) => vars.resource.attributes.find((attr) => attr.key === key)?.value.stringValue;
+        it("derives full vcs resource attributes from Vercel env vars", () => {
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "dash0");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "main");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA", "abc123");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID", "42");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/dash0hq/dash0");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("abc123");
+            expect(stringAttr(VCS_CHANGE_ID)).toBe("42");
+        });
+        // The 9 framework prefixes Vercel auto-prefixes its VERCEL_GIT_* system
+        // vars under (per https://vercel.com/docs/environment-variables/framework-environment-variables).
+        // A passing test for each confirms the literal-accessor enumeration in
+        // detectVcsFromVercel is actually wired up.
+        const FRAMEWORK_PREFIX_SAMPLES = [
+            ["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 Vercel vcs attributes from %s framework prefix (%s)", (_label, prefix) => {
+            vi.stubEnv(`${prefix}VERCEL_GIT_PROVIDER`, "github");
+            vi.stubEnv(`${prefix}VERCEL_GIT_REPO_OWNER`, "dash0hq");
+            vi.stubEnv(`${prefix}VERCEL_GIT_REPO_SLUG`, "dash0");
+            vi.stubEnv(`${prefix}VERCEL_GIT_COMMIT_REF`, "main");
+            vi.stubEnv(`${prefix}VERCEL_GIT_COMMIT_SHA`, "abc123");
+            vi.stubEnv(`${prefix}VERCEL_GIT_PULL_REQUEST_ID`, "42");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/dash0hq/dash0");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("abc123");
+            expect(stringAttr(VCS_CHANGE_ID)).toBe("42");
+        });
+        it.each(FRAMEWORK_PREFIX_SAMPLES)("derives Netlify vcs attributes from %s framework prefix (%s)", (_label, prefix) => {
+            vi.stubEnv(`${prefix}REPOSITORY_URL`, "https://github.com/dash0hq/dash0");
+            vi.stubEnv(`${prefix}BRANCH`, "feature/x");
+            vi.stubEnv(`${prefix}COMMIT_REF`, "def456");
+            vi.stubEnv(`${prefix}REVIEW_ID`, "99");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("feature/x");
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("def456");
+            expect(stringAttr(VCS_CHANGE_ID)).toBe("99");
+        });
+        it("derives vcs resource attributes from Netlify env vars (parsed REPOSITORY_URL)", () => {
+            vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://github.com/dash0hq/dash0.git");
+            vi.stubEnv("NEXT_PUBLIC_BRANCH", "feature/x");
+            vi.stubEnv("NEXT_PUBLIC_COMMIT_REF", "def456");
+            vi.stubEnv("NEXT_PUBLIC_REVIEW_ID", "99");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/dash0hq/dash0.git");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("feature/x");
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("def456");
+            expect(stringAttr(VCS_CHANGE_ID)).toBe("99");
+        });
+        it("prefers Vercel values over Netlify values when both are present", () => {
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "vercel-owner");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "vercel-repo");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "vercel-branch");
+            vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://github.com/netlify-owner/netlify-repo");
+            vi.stubEnv("NEXT_PUBLIC_BRANCH", "netlify-branch");
+            init(baseOptions);
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("vercel-owner");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("vercel-repo");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("vercel-branch");
+        });
+        it("opts.vcs overrides individual auto-detected fields", () => {
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "dash0");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "main");
+            init({
+                ...baseOptions,
+                vcs: {
+                    refHeadName: "release/2026.06",
+                    changeId: "1234",
+                },
+            });
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("release/2026.06");
+            expect(stringAttr(VCS_CHANGE_ID)).toBe("1234");
+        });
+        it("disableVcsDetection: true emits no vcs.* resource attributes even when env vars are set", () => {
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA", "abc123");
+            init({ ...baseOptions, disableVcsDetection: true });
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBeUndefined();
+        });
+        it("disableVcsDetection: true still applies opts.vcs manual overrides", () => {
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+            init({
+                ...baseOptions,
+                disableVcsDetection: true,
+                vcs: { providerName: "gitlab", refHeadName: "release/1.0" },
+            });
+            // env-var values are suppressed
+            expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+            // manual overrides still win
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("gitlab");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("release/1.0");
+        });
+        it("applies opts.vcs fields as the sole source when no env vars are set", () => {
+            init({
+                ...baseOptions,
+                vcs: {
+                    providerName: "github",
+                    ownerName: "my-org",
+                    repositoryName: "my-repo",
+                    repositoryUrlFull: "https://github.com/my-org/my-repo",
+                    refHeadName: "main",
+                    refHeadRevision: "deadbeef",
+                    changeId: "7",
+                },
+            });
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("my-org");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("my-repo");
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/my-org/my-repo");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("deadbeef");
+            expect(stringAttr(VCS_CHANGE_ID)).toBe("7");
+        });
+        it("emits nothing when no env vars and no opts.vcs are provided", () => {
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBeUndefined();
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBeUndefined();
+            expect(stringAttr(VCS_CHANGE_ID)).toBeUndefined();
+        });
+        it("emits only the partial attributes that are available", () => {
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA", "abc123");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "main");
+            init(baseOptions);
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+            expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("abc123");
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBeUndefined();
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+        });
+        it("does not derive repository URL when provider is unknown", () => {
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "someproprietary");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "owner");
+            vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "repo");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("someproprietary");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("owner");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("repo");
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBeUndefined();
+        });
+        it("accepts gist.github.com as a github host alias", () => {
+            vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://gist.github.com/owner/abc123");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("owner");
+        });
+        it("rejects arbitrary github.com subdomains", () => {
+            vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://evil.github.com/attacker/repo");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+        });
+        it("ignores a Netlify REPOSITORY_URL on an unknown host", () => {
+            vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://internal-git.example.com/team/app");
+            vi.stubEnv("NEXT_PUBLIC_BRANCH", "main");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://internal-git.example.com/team/app");
+            expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+        });
+        it("parses GitLab nested-group repository URLs to the last path segment", () => {
+            vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://gitlab.com/group/subgroup/app.git");
+            init(baseOptions);
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBe("gitlab");
+            expect(stringAttr(VCS_OWNER_NAME)).toBe("group");
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("app");
+        });
+        it("ignores a malformed REPOSITORY_URL", () => {
+            vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "not-a-url");
+            init(baseOptions);
+            expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("not-a-url");
+            expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+            expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+        });
+    });
+    describe("environment + deployment auto-detection", () => {
+        afterEach(() => {
+            vi.unstubAllEnvs();
+        });
+        const stringAttr = (key) => 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 = [
+            ["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/dist/modules/api/vcs.js

@@ -0,0 +1,190 @@
+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 { addAttribute } from "../utils/otel";
+import { pickFirstString } from "./browser-env";
+// 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 = {
+    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) {
+    const vcs = detectVcs(opts);
+    for (const field of Object.keys(VCS_FIELD_TO_ATTRIBUTE)) {
+        const value = vcs[field];
+        if (value) {
+            addAttribute(vars.resource.attributes, VCS_FIELD_TO_ATTRIBUTE[field], value);
+        }
+    }
+}
+function detectVcs(opts) {
+    // 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() {
+    let provider;
+    let owner;
+    let repo;
+    let ref;
+    let revision;
+    let changeId;
+    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() {
+    // 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;
+    let branch;
+    let commit;
+    let reviewId;
+    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, owner, repo) {
+    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 = {
+    github: ["github.com", "gist.github.com"],
+    gitlab: ["gitlab.com"],
+    bitbucket: ["bitbucket.org"],
+};
+function vcsHostForProvider(provider) {
+    return VCS_PROVIDER_HOSTS[provider]?.[0];
+}
+function parseRepositoryUrl(url) {
+    if (!url)
+        return undefined;
+    let host;
+    let pathname;
+    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) {
+    for (const [provider, hosts] of Object.entries(VCS_PROVIDER_HOSTS)) {
+        if (hosts.includes(host))
+            return provider;
+    }
+    return undefined;
+}

package/dist/modules/semantic-conventions.js

@@ -5,6 +5,14 @@ export const SERVICE_VERSION = "service.version";
 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/dist/modules/transport/index.js

@@ -15,6 +15,8 @@ function isRateLimited() {
     return rateLimiter();
 }
 export function sendLog(log) {
+    if (!vars.isSessionSampled)
+        return;
     if (isRateLimited()) {
         debug("Transport rate limit. Will not send item.", log);
         return;
@@ -41,6 +43,8 @@ function sendLogs(logs) {
 export function sendSpan(span) {
     if (!span)
         return;
+    if (!vars.isSessionSampled)
+        return;
     if (isRateLimited()) {
         debug("Transport rate limit. Will not send item.", span);
         return;

package/dist/modules/utils/index.js

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