From 3c0c2ee18cd657ebee14c4ece1a3eb90190ab72e Mon Sep 17 00:00:00 2001
From: Charly Gomez <charly.gomez1310@gmail.com>
Date: Mon, 10 Aug 2026 10:16:16 +0200
Subject: [PATCH] feat(browser): Add shim for metrics

Add a `metricsShim` to `@sentry-internal/integration-shims`, mirroring the existing logs shim.

It will be exported as `metrics` from the CDN bundles that do not ship metrics, so the loader can
swap bundles without `Sentry.metrics.*` calls throwing. Not wired into any bundle yet.

Refs #18583
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/integration-shims/src/index.ts       |  1 +
 packages/integration-shims/src/metrics.ts     | 21 ++++++++
 .../integration-shims/test/metrics.test.ts    | 50 +++++++++++++++++++
 3 files changed, 72 insertions(+)
 create mode 100644 packages/integration-shims/src/metrics.ts
 create mode 100644 packages/integration-shims/test/metrics.test.ts

diff --git a/packages/integration-shims/src/index.ts b/packages/integration-shims/src/index.ts
index e29f2acb3dc4..051bda210c4f 100644
--- a/packages/integration-shims/src/index.ts
+++ b/packages/integration-shims/src/index.ts
@@ -4,5 +4,6 @@ export { browserTracingIntegrationShim } from './BrowserTracing';
 export { launchDarklyIntegrationShim, buildLaunchDarklyFlagUsedHandlerShim } from './launchDarkly';
 export { elementTimingIntegrationShim } from './ElementTiming';
 export { loggerShim, consoleLoggingIntegrationShim } from './logs';
+export { metricsShim } from './metrics';
 export { spanStreamingIntegrationShim } from './SpanStreaming';
 export { fetchStreamPerformanceIntegrationShim } from './FetchStreamPerformance';
diff --git a/packages/integration-shims/src/metrics.ts b/packages/integration-shims/src/metrics.ts
new file mode 100644
index 000000000000..6f021fdcdc26
--- /dev/null
+++ b/packages/integration-shims/src/metrics.ts
@@ -0,0 +1,21 @@
+import { consoleSandbox } from '@sentry/core/browser';
+import { DEBUG_BUILD } from './debug-build';
+
+/**
+ * This is a shim for the metrics namespace.
+ * It is needed in order for the CDN bundles to continue working when users add/remove metrics
+ * from it, without changing their config. This is necessary for the loader mechanism.
+ */
+function metricShim(_name: unknown, _value?: unknown, _options?: unknown): void {
+  DEBUG_BUILD &&
+    consoleSandbox(() => {
+      // eslint-disable-next-line no-console
+      console.warn('You are using Sentry.metrics.* even though this bundle does not include metrics.');
+    });
+}
+
+export const metricsShim = {
+  count: metricShim,
+  gauge: metricShim,
+  distribution: metricShim,
+};
diff --git a/packages/integration-shims/test/metrics.test.ts b/packages/integration-shims/test/metrics.test.ts
new file mode 100644
index 000000000000..3a361fa8d89e
--- /dev/null
+++ b/packages/integration-shims/test/metrics.test.ts
@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+let mockDebugBuild = true;
+
+vi.mock('../src/debug-build', () => ({
+  get DEBUG_BUILD() {
+    return mockDebugBuild;
+  },
+}));
+
+// Must import after mocking
+const { metricsShim } = await import('../src/metrics');
+
+describe('metrics shims', () => {
+  const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+  beforeEach(() => {
+    consoleWarnSpy.mockClear();
+  });
+
+  afterEach(() => {
+    mockDebugBuild = true;
+  });
+
+  describe('when DEBUG_BUILD is true', () => {
+    beforeEach(() => {
+      mockDebugBuild = true;
+    });
+
+    it.each(['count', 'gauge', 'distribution'] as const)('metricsShim.%s should warn', method => {
+      metricsShim[method]('test', 1);
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'You are using Sentry.metrics.* even though this bundle does not include metrics.',
+      );
+    });
+  });
+
+  describe('when DEBUG_BUILD is false', () => {
+    beforeEach(() => {
+      mockDebugBuild = false;
+    });
+
+    it('metricsShim methods should NOT warn', () => {
+      metricsShim.count('test', 1);
+      metricsShim.gauge('test', 1);
+      metricsShim.distribution('test', 1);
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+  });
+});