可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载本篇技术指南以 sentry-javascript 仓库中《Adding a New CDN Bundle》文档docs/adding-cdn-bundle.md为主体结合 .agents/skills/add-cdn-bundle/SKILL.md 的技能化流程完整讲解如何为浏览器 SDK 创建一个包含指定功能组合tracing / replay / feedback / logs / metrics的 CDN Bundle。读完本文你将掌握从入口文件、单元测试、Rollup 构建配置、体积预算size-limit到集成测试与 CI 矩阵的全链路接入方法并理解其中真实导出 占位 Shim的兼容设计原理。一、功能组合Feature Combinations与命名约定CDN Bundle 是sentry/browser提供给通过script标签直接引入的用户的独立构建产物。为了控制体积仓库将功能拆分为可自由组合的独立 Bundle每个 Bundle 通过点号记法dot notation声明包含哪些能力。文档中给出的合法组合包括logs.metrics— 仅包含日志与指标replay.logs.metrics— 包含回放、日志与指标tracing.replay.logs— 包含性能追踪、回放与日志tracing.replay.feedback.logs.metrics— 全功能 Bundle功能在 Bundle 名称中的固定顺序为tracing→replay→feedback→logs→metrics。新增 Bundle 时文件名、构建产物名与测试脚本名都必须遵守该顺序例如仓库中已存在的 index.bundle.tracing.replay.feedback.logs.metrics.ts 与 index.bundle.tracing.replay.logs.metrics.ts 均严格遵循此序。给定一个功能组合需要派生以下命名变体以replay.logs.metrics为例占位符示例replay.logs.metrics用途{FEATURE_COMBO}replay.logs.metrics入口/测试文件名{feature_combo}replay_logs_metricsnpm 脚本名、CI 矩阵、集成测试路径键{featureCombo}replayLogsMetricsRollup 配置中的常量名{Human Readable Features}Replay, Logs, Metrics体积预算条目名{Human Readable Feature List}Replay, Logs, and Metricslicense 头、体积预算条目名二、核心步骤 1创建入口文件index.bundle.{FEATURE_COMBO}.ts每个 CDN Bundle 的入口文件位于packages/browser/src/职责是先执行必要的全局初始化再按包含什么就导出什么、不包含什么就导出对应 Shim的原则组装公开 API。1. 基础骨架与 TRACING 初始化// 若 Bundle 包含 TRACING必须在文件顶部注册 span 错误监听 import { registerSpanErrorInstrumentation } from sentry/core; registerSpanErrorInstrumentation(); // 始终导出基础 Bundle 的全部内容 export * from ./index.bundle.base;registerSpanErrorInstrumentation()是 Sentry 错误捕获的关键前置步骤它让后续所有创建的 span 在出错时自动上报错误事件该调用是 sentry-javascript 官方 CDN 初始化流程Sentry.init之前的标准做法。index.bundle.base.ts本身只有一行export * from ./exports见 index.bundle.base.ts即把所有sentry/browser的核心导出作为每个 Bundle 的公共底座。2. 各功能模块的真实导出片段LOGS未含 tracing 时单独补充export { logger, consoleLoggingIntegration } from sentry/core;TRACINGexport { getActiveSpan, getRootSpan, getSpanDescendants, setMeasurement, startInactiveSpan, startNewTrace, startSpan, startSpanManual, withActiveSpan, } from sentry/core; export { browserTracingIntegration, startBrowserTracingNavigationSpan, startBrowserTracingPageLoadSpan, } from ./tracing/browserTracingIntegration; export { reportPageLoaded } from ./tracing/reportPageLoaded; export { setActiveSpanInBrowser } from ./tracing/setActiveSpan;注意实际仓库实现中startSpan、startInactiveSpan、startSpanManual是从sentry/core/browser导入的见 index.bundle.tracing.replay.feedback.logs.metrics.ts以保证浏览器环境下这些 API 的默认事务/页面上下文行为正确同时全功能 Bundle 还会额外导出spanStreamingIntegration、fetchStreamPerformanceIntegration、webVitalsIntegration、elementTimingIntegration、isBotUserAgent等浏览器特有能力。新增 Bundle 时应以仓库现有全功能 Bundle 的实际导出清单为准。REPLAYexport { replayIntegration, getReplay } from sentry/replay;FEEDBACKimport { feedbackAsyncIntegration } from ./feedbackAsync; export { getFeedback, sendFeedback } from sentry/feedback; export { feedbackAsyncIntegration as feedbackAsyncIntegration, feedbackAsyncIntegration as feedbackIntegration };feedbackAsyncIntegration定义于 packages/browser/src/feedbackAsync.ts它把sentry/feedback的集成包装为异步加载版本避免在未使用时拉入完整 Feedback 依赖——这也是为什么全功能 Bundle 中feedbackIntegration与feedbackAsyncIntegration指向同一个实现见 index.bundle.tracing.replay.feedback.logs.metrics.ts。3. 未包含功能的 Shim 导出为了支持 Loader 机制同一份用户配置可对接不同组合的 Bundle 而不报错未包含的功能必须导出同名占位实现而不是不导出import { browserTracingIntegrationShim, // 若未含 tracing feedbackIntegrationShim, // 若未含 feedback replayIntegrationShim, // 若未含 replay consoleLoggingIntegrationShim, // 若未含 logs loggerShim, // 若未含 logs } from sentry-internal/integration-shims; // 再以正确的公开名字导出 export { browserTracingIntegrationShim as browserTracingIntegration }; export { feedbackIntegrationShim as feedbackAsyncIntegration, feedbackIntegrationShim as feedbackIntegration }; export { replayIntegrationShim as replayIntegration }; export { consoleLoggingIntegrationShim as consoleLoggingIntegration, loggerShim as logger };从源码看这些 Shim 并非空壳而是带诊断提示的假实现packages/integration-shims/src/logs.ts 中的loggerShim在DEBUG_BUILD下通过consoleSandbox输出警告 You are using Sentry.logger.* even though this bundle does not include logs.并提供trace/debug/info/warn/error/fatal/fmt全套方法签名consoleLoggingIntegrationShim返回名为ConsoleLogs的集成对象但setup指向FAKE_FUNCTION空操作packages/integration-shims/src/Replay.ts 中的replayIntegrationShim同样打印警告并实现start/stop/flush三个方法为FAKE_FUNCTION保证调用replay.start()之类的代码不会抛错。同理metricsShim与spanStreamingIntegrationShim等也由 packages/integration-shims/src/index.ts 统一导出。这种同名替换设计正是各 Bundle 之间 API 表面一致、可无缝切换的底层原因。4. 真实仓库示例对比以只含 Logs Metrics 的 index.bundle.logs.metrics.ts 为例它导出真实的logger、consoleLoggingIntegration、metrics与elementTimingIntegration而对 tracing、feedback、replay、span streaming、fetch stream performance 全部使用 ShimbrowserTracingIntegrationShim as browserTracingIntegration等。再对比 index.bundle.tracing.replay.ts可见它包含 tracing 与 replay 的真实导出却将logger、metrics、elementTimingIntegration、feedbackIntegration替换为 Shim。新增 Bundle 时直接对照这些已有入口文件即可避免遗漏。三、核心步骤 2创建单元测试index.bundle.{FEATURE_COMBO}.test.ts测试文件位于packages/browser/test/核心断言是Bundle 的导出与真实实现引用同一对象从而验证没有误用 Shimimport { logger as coreLogger, metrics as coreMetrics } from sentry/core; import { describe, expect, it } from vitest; // 为 Bundle 中包含的功能导入真实集成 import { browserTracingIntegration, feedbackAsyncIntegration, replayIntegration } from ../src; import * as Bundle from ../src/index.bundle.{FEATURE_COMBO}; describe(index.bundle.{FEATURE_COMBO}, () { it(has correct exports, () { // 测试真实导出与 core 实现一致 expect(Bundle.browserTracingIntegration).toBe(browserTracingIntegration); // 若包含 tracing expect(Bundle.feedbackAsyncIntegration).toBe(feedbackAsyncIntegration); // 若包含 feedback expect(Bundle.replayIntegration).toBe(replayIntegration); // 若包含 replay expect(Bundle.logger).toBe(coreLogger); // 若包含 logs expect(Bundle.metrics).toBe(coreMetrics); // 始终成立base bundle 内含 }); });对于未包含的功能应反向断言Bundle.browserTracingIntegration与真实实现不相等即它是 Shim确保不会意外把未包含功能带进 Bundle。测试失败时应更新期望以匹配 Bundle 的实际导出而不是强行修改导出逻辑。四、核心步骤 3接入 Rollup 构建配置rollup.bundle.config.mjspackages/browser/rollup.bundle.config.mjs是 CDN Bundle 的构建入口它通过sentry-internal/rollup-utils提供的makeBaseBundleConfig与makeBundleConfigVariants批量生成普通/压缩/调试压缩等变体产物。新增 Bundle 时在builds.push(...)之前追加一个独立配置块const {featureCombo}BaseBundleConfig makeBaseBundleConfig({ bundleType: standalone, entrypoints: [src/index.bundle.{FEATURE_COMBO}.ts], licenseTitle: sentry/browser ({Human Readable Feature List}), outputFileBase: () bundles/bundle.{FEATURE_COMBO}, });然后在builds.push(...)中加入...makeBundleConfigVariants({featureCombo}BaseBundleConfig),从当前仓库配置可看到完整对照例如 rollup.bundle.config.mjs 中tracingReplayLogsMetricsBaseBundleConfig的licenseTitle为sentry/browser (Performance Monitoring, Replay, Logs, and Metrics)outputFileBase为bundles/bundle.tracing.replay.logs.metrics而 rollup.bundle.config.mjs 中replayLogsMetricsBaseBundleConfig的licenseTitle为sentry/browser (Replay, Logs, and Metrics)。所有独立 Bundle 最后统一通过builds.push(...makeBundleConfigVariants(xxxBaseBundleConfig))汇总见 rollup.bundle.config.mjs。其中bundleType: standalone表示产物可直接在浏览器中以全局变量方式独立加载与addon类型如 contextlines、httpclient 等可插拔集成相区别。五、核心步骤 4登记体积预算.size-limit.js仓库根目录的.size-limit.js用 size-limit 约束每个 CDN Bundle 的体积防止功能叠加导致包体失控。需在 Browser CDN bundles 一节分别登记压缩gzip与未压缩两条记录// Gzipped追加在同类 Bundle 之后 { name: CDN Bundle (incl. {Human Readable Features}), path: createCDNPath(bundle.{FEATURE_COMBO}.min.js), gzip: true, limit: {SIZE} KB, // 根据功能估算 }, // Uncompressed追加在非 gzip 小节 { name: CDN Bundle (incl. {Human Readable Features}) - uncompressed, path: createCDNPath(bundle.{FEATURE_COMBO}.min.js), gzip: false, brotli: false, limit: {SIZE} KB, // 约为 gzip 体积的 3 倍 },仓库中现有条目可作对照例如CDN Bundle (incl. Replay, Logs, Metrics)指向bundle.replay.logs.metrics.min.js见 .size-limit.js。createCDNPath将相对路径解析到实际的构建产物目录。体积估算参考功能Gzip 体积增量Base Bundle~28 KB Tracing15 KB Replay37 KB Feedback12 KB Logs1 KB未压缩体积约为 gzip 体积的 3 倍。据此即可估算新增组合的limit初值例如replay.logs.metrics≈ 28 37 1 ≈ 66 KB gzip。这些是文档给出的经验估算值实际应以yarn build后的真实产物为准调整避免 CI 因体积超限失败。六、核心步骤 57接入集成测试与 CICDN Bundle 除了单元测试还要纳入browser-integration-tests的 Playwright 端到端验证才能保证script加载场景真实可用。1. 在dev-packages/browser-integration-tests/package.json添加测试脚本test:bundle:{feature_combo}: PW_BUNDLEbundle_{feature_combo} yarn test, test:bundle:{feature_combo}:min: PW_BUNDLEbundle_{feature_combo}_min yarn test, test:bundle:{feature_combo}:debug_min: PW_BUNDLEbundle_{feature_combo}_debug_min yarn test,仓库现有脚本即遵循此模式如test:bundle:replay_logs_metrics: PW_BUNDLEbundle_replay_logs_metrics yarn test与对应的:min、:debug_min变体见 dev-packages/browser-integration-tests/package.json。全功能 Bundle 还额外提供test:bundle:full别名dev-packages/browser-integration-tests/package.json。2. 在dev-packages/browser-integration-tests/utils/generatePlugin.ts注册产物路径向BUNDLE_PATHS.browser添加三个键把PW_BUNDLE变量名映射到实际构建产物bundle_{feature_combo}: build/bundles/bundle.{FEATURE_COMBO}.js, bundle_{feature_combo}_min: build/bundles/bundle.{FEATURE_COMBO}.min.js, bundle_{feature_combo}_debug_min: build/bundles/bundle.{FEATURE_COMBO}.debug.min.js,该文件目前已登记了bundle_logs_metrics、bundle_replay_logs_metrics、bundle_tracing_replay_feedback_logs_metrics及其_min、_debug_min变体等全部现有 Bundle 的路径见 dev-packages/browser-integration-tests/utils/generatePlugin.ts新增 Bundle 时照此追加即可。该插件会读取PW_BUNDLE环境变量将选中的 Bundle 注入到测试页面的 loader 配置中其中对_min后缀的归一化逻辑见 generatePlugin.ts。3. 在.github/workflows/build.yml扩展 CI 矩阵在job_browser_playwright_tests作业的 bundle 矩阵中加入- bundle_{feature_combo}这样新 Bundle 的集成测试会自动进入 CI 并行矩阵随每次 PR 运行。七、验证步骤完成上述 7 个文件的新增/修改后按文档给出的顺序执行验证yarn lint # 1. 检查 lint 问题 cd packages/browser yarn build:dev # 2. 验证 TypeScript 编译 cd packages/browser yarn test # 3. 运行单元测试若 lint 报错可先执行yarn fix自动修复常见问题TypeScript 编译失败则必须先修复类型错误再继续测试失败需核对测试期望与 Bundle 实际导出一致性尤其是 Shim 与真实实现的区分。集成测试可通过cd dev-packages/browser-integration-tests yarn test:bundle:{feature_combo}等脚本单独运行。八、参考现有 Bundle 与错误处理动手前建议通读仓库已有的四个代表性 Bundle 入口文件作为命名、导出与 Shim 搭配的模板index.bundle.tracing.ts — 仅 tracingindex.bundle.replay.ts — 仅 replayindex.bundle.tracing.replay.ts — tracing replayindex.bundle.logs.metrics.ts — logs metrics常见错误与对策汇总非法功能组合先校验功能名必须属于tracing、replay、feedback、logs、metrics且按固定顺序排列构建失败优先修复入口文件中的 TypeScript 导入/导出错误如sentry/core/browser与sentry/core的路径选择Lint 错误运行yarn fix自动修复常见问题测试失败更新测试期望以匹配 Bundle 的实际导出含真实导出与 Shim 的区分体积超限以实际构建产物重新估算.size-limit.js中的limit。结语从加一个文件到一整套发布链路新增一个 CDN Bundle 表面上是创建一个入口文件实则牵动构建Rollup、体积治理size-limit、端到端测试Playwright CI 矩阵与 Loader 兼容integration-shims四条链路。理解了真实导出 Shim 兜底的设计哲学后你不仅可以按文档步骤机械地添加新组合还能在出现导出不一致、构建体积异常等问题时快速定位根因。对于更宏观的版本发布流程可进一步参考 docs/adding-cdn-bundle.md 与 docs/publishing-a-release.md。赞分享可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载相关推荐sentry-javascript 中新增 Browser CDN Bundle 的完整实操指南sentry javascript 中新增 Browser CDN Bundle 的完整实操指南 Sentry JavaScript SDK 为浏览器场景提供了可观测性Vue Router 命名路由Named Routes完全指南定义、链接与底层实现Vue Router 命名路由Named Routes完全指南定义、链接与底层实现 命名路由Named Routes是 Vue Router 为每条路前端路由用 Sentry 为 Flue Agent 接入错误、日志与 AI 链路追踪完整集成指南用 Sentry 为 Flue Agent 接入错误、日志与 AI 链路追踪完整集成指南 导读 本文基于 Flue 仓库中的 Sentry 接入文档 http人工智能大模型AI AgentAgent 框架工具调用Agent 沙箱MCP Clients上一篇Diablo Edit2暗黑破坏神2存档修改器终极指南下一篇如何快速掌握LangGraph构建智能代理的完整入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考