feat(browser): Add shim package for logs (#18831)

chargome · web-flow · commit e50b75cdff50 · 2026-01-16T16:57:03.000+01:00
Adds a shim for the `logger` namespace since we'll soon ship the logs bundle in the loader and want to avoid breaking user apps when they switch back to a bundle that does not include logs closes #18826
diff --git a/dev-packages/browser-integration-tests/suites/public-api/logger/consoleLoggingIntegrationShim/init.js b/dev-packages/browser-integration-tests/suites/public-api/logger/consoleLoggingIntegrationShim/init.js
@@ -0,0 +1,10 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+// consoleLoggingIntegration should not actually work, but still not error out
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  sampleRate: 1,
+  integrations: [Sentry.consoleLoggingIntegration()],
+});
diff --git a/dev-packages/browser-integration-tests/suites/public-api/logger/consoleLoggingIntegrationShim/test.ts b/dev-packages/browser-integration-tests/suites/public-api/logger/consoleLoggingIntegrationShim/test.ts
@@ -0,0 +1,37 @@
+import { expect } from '@playwright/test';
+import { sentryTest } from '../../../../utils/fixtures';
+
+sentryTest('exports a shim consoleLoggingIntegration for non-logs bundles', async ({ getLocalTestUrl, page }) => {
+  const bundle = process.env.PW_BUNDLE;
+
+  // Only run this for CDN bundles that do NOT include logs
+  // Skip minified bundles because DEBUG_BUILD is false and warnings won't appear
+  if (!bundle?.startsWith('bundle') || bundle.includes('logs') || bundle.includes('min')) {
+    sentryTest.skip();
+  }
+
+  const consoleMessages: string[] = [];
+  page.on('console', msg => consoleMessages.push(msg.text()));
+
+  let requestCount = 0;
+  await page.route(/^https:\/\/dsn\.ingest\.sentry\.io\//, route => {
+    requestCount++;
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ id: 'test-id' }),
+    });
+  });
+
+  const url = await getLocalTestUrl({ testDir: __dirname, skipDsnRouteHandler: true });
+
+  await page.goto(url);
+
+  // Wait a bit to ensure no requests are made
+  await page.waitForTimeout(500);
+
+  expect(requestCount).toBe(0);
+  expect(consoleMessages).toEqual([
+    'You are using consoleLoggingIntegration() even though this bundle does not include logs.',
+  ]);
+});
diff --git a/dev-packages/browser-integration-tests/suites/public-api/logger/loggerShim/init.js b/dev-packages/browser-integration-tests/suites/public-api/logger/loggerShim/init.js
@@ -0,0 +1,18 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  sampleRate: 1,
+});
+
+// These should not actually work, but still not error out
+Sentry.logger.trace('test trace');
+Sentry.logger.debug('test debug');
+Sentry.logger.info('test info');
+Sentry.logger.warn('test warn');
+Sentry.logger.error('test error');
+Sentry.logger.fatal('test fatal');
+const testVar = 'test';
+Sentry.logger.info(Sentry.logger.fmt`formatted ${testVar}`);
diff --git a/dev-packages/browser-integration-tests/suites/public-api/logger/loggerShim/test.ts b/dev-packages/browser-integration-tests/suites/public-api/logger/loggerShim/test.ts
@@ -0,0 +1,37 @@
+import { expect } from '@playwright/test';
+import { sentryTest } from '../../../../utils/fixtures';
+
+sentryTest('exports a shim logger for non-logs bundles', async ({ getLocalTestUrl, page }) => {
+  const bundle = process.env.PW_BUNDLE;
+
+  // Only run this for CDN bundles that do NOT include logs
+  // Skip minified bundles because DEBUG_BUILD is false and warnings won't appear
+  if (!bundle?.startsWith('bundle') || bundle.includes('logs') || bundle.includes('min')) {
+    sentryTest.skip();
+  }
+
+  const consoleMessages: string[] = [];
+  page.on('console', msg => consoleMessages.push(msg.text()));
+
+  let requestCount = 0;
+  await page.route(/^https:\/\/dsn\.ingest\.sentry\.io\//, route => {
+    requestCount++;
+    return route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ id: 'test-id' }),
+    });
+  });
+
+  const url = await getLocalTestUrl({ testDir: __dirname, skipDsnRouteHandler: true });
+
+  await page.goto(url);
+
+  // Wait a bit to ensure no requests are made
+  await page.waitForTimeout(500);
+
+  expect(requestCount).toBe(0);
+
+  expect(consoleMessages).toContain('You are using Sentry.logger.* even though this bundle does not include logs.');
+  expect(consoleMessages).toContain('You are using Sentry.logger.fmt even though this bundle does not include logs.');
+});
diff --git a/packages/browser/src/index.bundle.feedback.ts b/packages/browser/src/index.bundle.feedback.ts
@@ -1,8 +1,16 @@
-import { browserTracingIntegrationShim, replayIntegrationShim } from '@sentry-internal/integration-shims';
+import {
+  browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
+  loggerShim,
+  replayIntegrationShim,
+} from '@sentry-internal/integration-shims';
 import { feedbackAsyncIntegration } from './feedbackAsync';
 
 export * from './index.bundle.base';
 
+// TODO(v11): Export metricsShim here once we remove metrics from the base bundle.
+export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };
+
 export { getFeedback, sendFeedback } from '@sentry-internal/feedback';
 
 export {
diff --git a/packages/browser/src/index.bundle.replay.feedback.ts b/packages/browser/src/index.bundle.replay.feedback.ts
@@ -1,8 +1,15 @@
-import { browserTracingIntegrationShim } from '@sentry-internal/integration-shims';
+import {
+  browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
+  loggerShim,
+} from '@sentry-internal/integration-shims';
 import { feedbackAsyncIntegration } from './feedbackAsync';
 
 export * from './index.bundle.base';
 
+// TODO(v11): Export metricsShim here once we remove metrics from the base bundle.
+export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };
+
 export { getFeedback, sendFeedback } from '@sentry-internal/feedback';
 
 export {
diff --git a/packages/browser/src/index.bundle.replay.ts b/packages/browser/src/index.bundle.replay.ts
@@ -1,7 +1,15 @@
-import { browserTracingIntegrationShim, feedbackIntegrationShim } from '@sentry-internal/integration-shims';
+import {
+  browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
+  feedbackIntegrationShim,
+  loggerShim,
+} from '@sentry-internal/integration-shims';
 
 export * from './index.bundle.base';
 
+// TODO(v11): Export metricsShim here once we remove metrics from the base bundle.
+export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };
+
 export { replayIntegration, getReplay } from '@sentry-internal/replay';
 
 export {
diff --git a/packages/browser/src/index.bundle.tracing.replay.feedback.ts b/packages/browser/src/index.bundle.tracing.replay.feedback.ts
@@ -1,10 +1,14 @@
 import { registerSpanErrorInstrumentation } from '@sentry/core';
+import { consoleLoggingIntegrationShim, loggerShim } from '@sentry-internal/integration-shims';
 import { feedbackAsyncIntegration } from './feedbackAsync';
 
 registerSpanErrorInstrumentation();
 
 export * from './index.bundle.base';
 
+// TODO(v11): Export metricsShim here once we remove metrics from the base bundle.
+export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };
+
 export {
   getActiveSpan,
   getRootSpan,
diff --git a/packages/browser/src/index.bundle.tracing.replay.ts b/packages/browser/src/index.bundle.tracing.replay.ts
@@ -1,10 +1,13 @@
 import { registerSpanErrorInstrumentation } from '@sentry/core';
-import { feedbackIntegrationShim } from '@sentry-internal/integration-shims';
+import { consoleLoggingIntegrationShim, feedbackIntegrationShim, loggerShim } from '@sentry-internal/integration-shims';
 
 registerSpanErrorInstrumentation();
 
 export * from './index.bundle.base';
 
+// TODO(v11): Export metricsShim here once we remove metrics from the base bundle.
+export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };
+
 export {
   getActiveSpan,
   getRootSpan,
diff --git a/packages/browser/src/index.bundle.tracing.ts b/packages/browser/src/index.bundle.tracing.ts
@@ -1,10 +1,18 @@
 import { registerSpanErrorInstrumentation } from '@sentry/core';
-import { feedbackIntegrationShim, replayIntegrationShim } from '@sentry-internal/integration-shims';
+import {
+  consoleLoggingIntegrationShim,
+  feedbackIntegrationShim,
+  loggerShim,
+  replayIntegrationShim,
+} from '@sentry-internal/integration-shims';
 
 registerSpanErrorInstrumentation();
 
 export * from './index.bundle.base';
 
+// TODO(v11): Export metricsShim here once we remove metrics from the base bundle.
+export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };
+
 export {
   getActiveSpan,
   getRootSpan,
diff --git a/packages/browser/src/index.bundle.ts b/packages/browser/src/index.bundle.ts
@@ -1,11 +1,16 @@
 import {
   browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
   feedbackIntegrationShim,
+  loggerShim,
   replayIntegrationShim,
 } from '@sentry-internal/integration-shims';
 
 export * from './index.bundle.base';
 
+// TODO(v11): Export metricsShim here once we remove metrics from the base bundle.
+export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };
+
 export {
   browserTracingIntegrationShim as browserTracingIntegration,
   feedbackIntegrationShim as feedbackAsyncIntegration,
diff --git a/packages/browser/test/index.bundle.feedback.test.ts b/packages/browser/test/index.bundle.feedback.test.ts
@@ -1,4 +1,9 @@
-import { browserTracingIntegrationShim, replayIntegrationShim } from '@sentry-internal/integration-shims';
+import {
+  browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
+  loggerShim,
+  replayIntegrationShim,
+} from '@sentry-internal/integration-shims';
 import { describe, expect, it } from 'vitest';
 import { feedbackAsyncIntegration } from '../src';
 import * as FeedbackBundle from '../src/index.bundle.feedback';
@@ -9,5 +14,8 @@ describe('index.bundle.feedback', () => {
     expect(FeedbackBundle.feedbackAsyncIntegration).toBe(feedbackAsyncIntegration);
     expect(FeedbackBundle.feedbackIntegration).toBe(feedbackAsyncIntegration);
     expect(FeedbackBundle.replayIntegration).toBe(replayIntegrationShim);
+
+    expect(FeedbackBundle.logger).toBe(loggerShim);
+    expect(FeedbackBundle.consoleLoggingIntegration).toBe(consoleLoggingIntegrationShim);
   });
 });
diff --git a/packages/browser/test/index.bundle.replay.feedback.test.ts b/packages/browser/test/index.bundle.replay.feedback.test.ts
@@ -0,0 +1,20 @@
+import {
+  browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
+  loggerShim,
+} from '@sentry-internal/integration-shims';
+import { describe, expect, it } from 'vitest';
+import { feedbackAsyncIntegration, replayIntegration } from '../src';
+import * as ReplayFeedbackBundle from '../src/index.bundle.replay.feedback';
+
+describe('index.bundle.replay.feedback', () => {
+  it('has correct exports', () => {
+    expect(ReplayFeedbackBundle.browserTracingIntegration).toBe(browserTracingIntegrationShim);
+    expect(ReplayFeedbackBundle.feedbackAsyncIntegration).toBe(feedbackAsyncIntegration);
+    expect(ReplayFeedbackBundle.feedbackIntegration).toBe(feedbackAsyncIntegration);
+    expect(ReplayFeedbackBundle.replayIntegration).toBe(replayIntegration);
+
+    expect(ReplayFeedbackBundle.logger).toBe(loggerShim);
+    expect(ReplayFeedbackBundle.consoleLoggingIntegration).toBe(consoleLoggingIntegrationShim);
+  });
+});
diff --git a/packages/browser/test/index.bundle.replay.test.ts b/packages/browser/test/index.bundle.replay.test.ts
@@ -1,4 +1,9 @@
-import { browserTracingIntegrationShim, feedbackIntegrationShim } from '@sentry-internal/integration-shims';
+import {
+  browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
+  feedbackIntegrationShim,
+  loggerShim,
+} from '@sentry-internal/integration-shims';
 import { describe, expect, it } from 'vitest';
 import { replayIntegration } from '../src';
 import * as ReplayBundle from '../src/index.bundle.replay';
@@ -9,5 +14,8 @@ describe('index.bundle.replay', () => {
     expect(ReplayBundle.feedbackAsyncIntegration).toBe(feedbackIntegrationShim);
     expect(ReplayBundle.feedbackIntegration).toBe(feedbackIntegrationShim);
     expect(ReplayBundle.replayIntegration).toBe(replayIntegration);
+
+    expect(ReplayBundle.logger).toBe(loggerShim);
+    expect(ReplayBundle.consoleLoggingIntegration).toBe(consoleLoggingIntegrationShim);
   });
 });
diff --git a/packages/browser/test/index.bundle.test.ts b/packages/browser/test/index.bundle.test.ts
@@ -1,6 +1,8 @@
 import {
   browserTracingIntegrationShim,
+  consoleLoggingIntegrationShim,
   feedbackIntegrationShim,
+  loggerShim,
   replayIntegrationShim,
 } from '@sentry-internal/integration-shims';
 import { describe, expect, it } from 'vitest';
@@ -12,5 +14,8 @@ describe('index.bundle', () => {
     expect(Bundle.feedbackAsyncIntegration).toBe(feedbackIntegrationShim);
     expect(Bundle.feedbackIntegration).toBe(feedbackIntegrationShim);
     expect(Bundle.replayIntegration).toBe(replayIntegrationShim);
+
+    expect(Bundle.logger).toBe(loggerShim);
+    expect(Bundle.consoleLoggingIntegration).toBe(consoleLoggingIntegrationShim);
   });
 });
diff --git a/packages/browser/test/index.bundle.tracing.replay.feedback.test.ts b/packages/browser/test/index.bundle.tracing.replay.feedback.test.ts
@@ -1,3 +1,4 @@
+import { consoleLoggingIntegrationShim, loggerShim } from '@sentry-internal/integration-shims';
 import { describe, expect, it } from 'vitest';
 import { browserTracingIntegration, feedbackAsyncIntegration, replayIntegration } from '../src';
 import * as TracingReplayFeedbackBundle from '../src/index.bundle.tracing.replay.feedback';
@@ -8,5 +9,8 @@ describe('index.bundle.tracing.replay.feedback', () => {
     expect(TracingReplayFeedbackBundle.feedbackAsyncIntegration).toBe(feedbackAsyncIntegration);
     expect(TracingReplayFeedbackBundle.feedbackIntegration).toBe(feedbackAsyncIntegration);
     expect(TracingReplayFeedbackBundle.replayIntegration).toBe(replayIntegration);
+
+    expect(TracingReplayFeedbackBundle.logger).toBe(loggerShim);
+    expect(TracingReplayFeedbackBundle.consoleLoggingIntegration).toBe(consoleLoggingIntegrationShim);
   });
 });
diff --git a/packages/browser/test/index.bundle.tracing.replay.test.ts b/packages/browser/test/index.bundle.tracing.replay.test.ts
@@ -1,4 +1,4 @@
-import { feedbackIntegrationShim } from '@sentry-internal/integration-shims';
+import { consoleLoggingIntegrationShim, feedbackIntegrationShim, loggerShim } from '@sentry-internal/integration-shims';
 import { describe, expect, it } from 'vitest';
 import { browserTracingIntegration, replayIntegration } from '../src';
 import * as TracingReplayBundle from '../src/index.bundle.tracing.replay';
@@ -9,5 +9,8 @@ describe('index.bundle.tracing.replay', () => {
     expect(TracingReplayBundle.feedbackAsyncIntegration).toBe(feedbackIntegrationShim);
     expect(TracingReplayBundle.feedbackIntegration).toBe(feedbackIntegrationShim);
     expect(TracingReplayBundle.replayIntegration).toBe(replayIntegration);
+
+    expect(TracingReplayBundle.logger).toBe(loggerShim);
+    expect(TracingReplayBundle.consoleLoggingIntegration).toBe(consoleLoggingIntegrationShim);
   });
 });
diff --git a/packages/browser/test/index.bundle.tracing.test.ts b/packages/browser/test/index.bundle.tracing.test.ts
@@ -1,4 +1,9 @@
-import { feedbackIntegrationShim, replayIntegrationShim } from '@sentry-internal/integration-shims';
+import {
+  consoleLoggingIntegrationShim,
+  feedbackIntegrationShim,
+  loggerShim,
+  replayIntegrationShim,
+} from '@sentry-internal/integration-shims';
 import { describe, expect, it } from 'vitest';
 import { browserTracingIntegration } from '../src';
 import * as TracingBundle from '../src/index.bundle.tracing';
@@ -9,5 +14,8 @@ describe('index.bundle.tracing', () => {
     expect(TracingBundle.feedbackAsyncIntegration).toBe(feedbackIntegrationShim);
     expect(TracingBundle.feedbackIntegration).toBe(feedbackIntegrationShim);
     expect(TracingBundle.replayIntegration).toBe(replayIntegrationShim);
+
+    expect(TracingBundle.logger).toBe(loggerShim);
+    expect(TracingBundle.consoleLoggingIntegration).toBe(consoleLoggingIntegrationShim);
   });
 });
diff --git a/packages/integration-shims/package.json b/packages/integration-shims/package.json
@@ -44,7 +44,8 @@
     "clean": "rimraf build",
     "fix": "eslint . --format stylish --fix",
     "lint": "eslint . --format stylish",
-    "lint:es-compatibility": "es-check es2020 ./build/cjs/*.js && es-check es2020 ./build/esm/*.js --module"
+    "lint:es-compatibility": "es-check es2020 ./build/cjs/*.js && es-check es2020 ./build/esm/*.js --module",
+    "test": "vitest run"
   },
   "repository": {
     "type": "git",
diff --git a/packages/integration-shims/src/debug-build.ts b/packages/integration-shims/src/debug-build.ts
@@ -0,0 +1,8 @@
+declare const __DEBUG_BUILD__: boolean;
+
+/**
+ * This serves as a build time flag that will be true by default, but false in non-debug builds or if users replace `__SENTRY_DEBUG__` in their generated code.
+ *
+ * ATTENTION: This constant must never cross package boundaries (i.e. be exported) to guarantee that it can be used for tree shaking.
+ */
+export const DEBUG_BUILD = __DEBUG_BUILD__;
diff --git a/packages/integration-shims/src/index.ts b/packages/integration-shims/src/index.ts
@@ -2,3 +2,4 @@ export { feedbackIntegrationShim } from './Feedback';
 export { replayIntegrationShim } from './Replay';
 export { browserTracingIntegrationShim } from './BrowserTracing';
 export { launchDarklyIntegrationShim, buildLaunchDarklyFlagUsedHandlerShim } from './launchDarkly';
+export { loggerShim, consoleLoggingIntegrationShim } from './logs';
diff --git a/packages/integration-shims/src/logs.ts b/packages/integration-shims/src/logs.ts
diff --git a/packages/integration-shims/test/logs.test.ts b/packages/integration-shims/test/logs.test.ts
diff --git a/packages/integration-shims/tsconfig.test.json b/packages/integration-shims/tsconfig.test.json
diff --git a/packages/integration-shims/vite.config.ts b/packages/integration-shims/vite.config.ts
