@dash0/sdk-web 0.20.0 → 0.21.0

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 (`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
+   * 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.
    */