后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载本指南基于 RedwoodJS 8.0 版本文档系统讲解如何通过一条 CLI 命令在 Redwood 应用中接入 Sentry实现 API 与 Web 两侧的错误上报、Prisma 数据库追踪与浏览器性能监控并深入解析setup monitoring sentry命令在仓库中的真实实现以及如何手动完成 Envelop 插件接入、当前用户绑定、异常捕获与错误边界替换。读完本文你将掌握从零到一配置 Sentry 监控、读懂生成代码并用源码级证据排查集成问题的完整能力。快速上手一条命令完成 Sentry 初始化在 Redwood 应用根目录执行以下命令即可完成 Sentry 的安装与基础配置yarn redwood setup monitoring sentry该命令属于 Redwood CLI 的setup monitoring子命令族由 packages/cli/src/commands/setup/monitoring/monitoring.ts 注册执行后会自动完成以下工作安装并配置 API 侧依赖sentry/node与envelop/sentry安装并配置 Web 侧依赖sentry/react与sentry/browser提示你设置SENTRY_DSN环境变量DSN 即 Sentry 项目数据源名称用于标识事件上报的目标项目在api/src/lib/与web/src/lib/下分别生成 Sentry 初始化文件尝试自动向 GraphQL handler 注入useSentry()Envelop 插件尝试将 Web 端默认的FatalErrorBoundary替换为Sentry.ErrorBoundary。上述每一步在源码中都有对应任务实现见 packages/cli/src/commands/setup/monitoring/sentry/sentryHandler.ts。--force参数命令支持--force别名-f布尔参数用于覆盖已存在的 Sentry 配置文件yarn redwood setup monitoring sentry --force其参数声明位于 packages/cli/src/commands/setup/monitoring/sentry/sentry.ts默认值为false。在源码中生成初始化文件时使用{ existingFiles: force ? OVERWRITE : SKIP }策略即未加--force时若目标文件已存在会跳过写入避免破坏你已有的自定义配置。关于 SENTRY_DSN 环境变量setup命令会引导你配置SENTRY_DSN。在 Redwood 中Web 侧默认只会把redwood.toml的includeEnvironmentVariables中列出的环境变量暴露给浏览器端代码因此你还需要把它加入配置# redwood.toml [web] includeEnvironmentVariables [ SENTRY_DSN ]这一要求在命令执行末尾的 One more thing... 任务中会以醒目提示输出对应 sentryHandler.ts。如果遗漏该步骤Web 侧初始化文件会打印缺失SENTRY_DSN的报错信息并暂时禁用 Sentry详见下文 Web 侧模板分析。setup 命令生成的初始化文件解析setup命令依据项目类型TypeScript 或 JavaScript在两侧各生成一个初始化文件。下面以 TypeScript 为例展开分析JavaScript 项目结构完全一致仅扩展名不同。API 侧api/src/lib/sentry.ts由模板 sentryApi.ts.template 生成内容如下import * as Sentry from sentry/node import { db as client } from src/lib/db Sentry.init({ dsn: process.env.SENTRY_DSN, environment: process.env.NODE_ENV, integrations: [ new Sentry.Integrations.Prisma({ client }), new Sentry.Integrations.Http({ tracing: true }), ], tracesSampleRate: 1.0, }) export default Sentry几个关键点dsn直接取自process.env.SENTRY_DSN因此在 API 侧运行环境本地.env文件或部署平台的环境变量中配置即可environment使用process.env.NODE_ENV方便你在 Sentry 后台按 production / development 等环境区分事件Prisma 集成new Sentry.Integrations.Prisma({ client })将 Redwood 默认导出的db来自src/lib/db注入 Prisma 集成从而在性能追踪中捕获数据库查询的耗时信息这正是文档开头提到的启用 Prisma 追踪的落地实现Http 集成开启tracing: true后API 侧发起的 HTTP 出站请求也会纳入性能追踪tracesSampleRate: 1.0表示对 100% 的事件启用性能追踪Sample Rate 采样率 1.0 全量采样与文档描述一致生产环境可酌情调低以控制费用。Web 侧web/src/lib/sentry.ts由模板 sentryWeb.ts.template 生成import * as Sentry from sentry/react let dsn let environment development if (typeof process undefined || !process.env?.SENTRY_DSN) { console.error( Missing SENTRY_DSN environment variable. Did you forget to add it to your redwood.toml file in includeEnvironmentVariables? ) console.info(Copy this into your redwood.toml file:) console.info( includeEnvironmentVariables [ SENTRY_DSN ] ) console.error(Sentry is disabled for now) } else { dsn process.env.SENTRY_DSN environment process.env.NODE_ENV } Sentry.init({ dsn, environment, integrations: [new Sentry.BrowserTracing()], tracesSampleRate: 1.0, }) export default SentryWeb 侧模板体现了 Redwood 特有的工程约束浏览器端拿不到process.env中未显式暴露的变量因此模板在初始化前先做防御性检查若SENTRY_DSN缺失会打印清晰的排错提示引导你补上includeEnvironmentVariables并将 Sentry 置于禁用状态dsn为空而不是让应用崩溃BrowserTracing 集成对应文档提到的 Browser tracing负责采集页面加载、路由切换等浏览器端性能数据tracesSampleRate: 1.0同样为全量采样。两侧文件都通过export default Sentry导出后续在业务代码中统一通过import Sentry from src/lib/sentry使用src即api/src或web/src的别名。为 GraphQL 请求接入 Sentry Envelop 插件Redwood 的 GraphQL 服务基于 GraphQL Yoga 与 Envelop 插件体系构建。setup命令会尝试自动修改api/src/functions/graphql.ts为你注入useSentry()插件若自动注入因故跳过也可以手动接入。手动配置方式在 GraphQL handler 中导入插件并加入extraPlugins数组import { useSentry } from envelop/sentry import { createGraphQLHandler } from redwoodjs/graphql-server import directives from src/directives/**/*.{js,ts} import sdls from src/graphql/**/*.sdl.{js,ts} import services from src/services/**/*.{js,ts} import src/lib/sentry // ... export const handler createGraphQLHandler({ directives, sdls, services, extraPlugins: [useSentry()], // ... })这里通过import src/lib/sentry确保 Sentry 在 handler 启动前完成初始化副作用导入JS 项目写法完全一致仅文件扩展名不同。自动注入时使用的插件选项从 sentryHandler.ts 的源码可以看到命令自动注入的并非裸的useSentry()而是带有一组 Envelop 上下文选项extraPlugins: [useSentry({ includeRawResult: true, includeResolverArgs: true, includeExecuteVariables: true, })],includeRawResult在事件中附带每个字段的原始执行结果注意可能包含敏感数据请按业务评估includeResolverArgs附带 resolver即 Service 解析函数的入参includeExecuteVariables附带 GraphQL 执行的查询变量。同时命令会在该文件顶部补上import { useSentry } from envelop/sentry与import src/lib/sentry两行导入。底层实现extraPlugins 如何生效extraPlugins是createGraphQLHandler配置项之一类型定义见 packages/graphql-server/src/types.ts。从 packages/graphql-server/src/createGraphQLYoga.ts 的源码可以看到插件在创建 Yoga 实例时被合并进默认插件链// App-defined plugins if (extraPlugins extraPlugins.length 0) { plugins.push(...extraPlugins) }这意味着你传入的 Envelop 插件会与 Redwood 内置的useFilterAllowedOperations、useRedwoodTrustedDocuments、useRedwoodError、useReadinessCheck等插件一起按顺序执行。useSentry()由此可以拦截 GraphQL 的解析、校验、执行与结果阶段实现请求级错误捕获与性能 Span 记录。若自动注入失败例如你曾自定义过extraPlugins命令会打印提示要求手动实现此时按上一节手动方式补充即可。为错误与性能事件绑定当前用户使用Sentry.setUser可以把错误与性能事件关联到具体用户身份便于在 Sentry 后台按用户维度检索与复现问题。API 侧在 getCurrentUser 中设置Redwood 认证体系的核心钩子getCurrentUser位于api/src/lib/auth.ts会在每个请求鉴权时执行是设置用户上下文的理想位置import Sentry from src/lib/sentry export const getCurrentUser async (...) { const user await db.user.findUnique(...) Sentry.setUser(user) // ... }注意Sentry.setUser(user)接收的user是 Prisma 返回的完整用户对象若你的用户模型包含敏感字段建议先映射为仅含id、email、username等必要字段的对象再传入。Web 侧在布局组件中设置Web 侧可以利用 React 布局Layout配合useEffect完成设置。文档推荐的做法是创建一个专属布局例如通过yarn redwood generate layout Sentry生成的SentryLayoutimport React, { useEffect } from react import { useAuth } from src/lib/auth import Sentry from src/lib/sentry interface Props { children: React.ReactNode } const SentryLayout ({ children }: Props) { const { currentUser } useAuth() useEffect(() Sentry.setUser(currentUser), [currentUser]) return {children}/ } export default SentryLayout要点说明useAuth()返回的currentUser与 API 侧getCurrentUser的返回值对应useEffect的依赖数组写[currentUser]保证仅在用户身份变化时重新设置登录 / 登出 / 切换账号文档特别提醒useEffect依赖数组需根据你在应用中放置Sentry.setUser的位置灵活调整例如放在页面级组件时依赖项可能还需包含相关路由或上下文状态该布局需包裹在你的路由外层例如在Routes之上确保所有页面共享用户上下文。在 API 函数中手动捕获异常除了 GraphQL 层的自动采集你还可以在自定义 API 函数Functions中手动捕获并上报异常import Sentry from src/lib/sentry export const handler async (event, context) { try { // ... } catch (err) { Sentry.captureException(err) } }Sentry.captureException(err)会把异常对象连同当前上下文用户、环境、事务等一起上报到 Sentry。该模式同样适用于 Service、Job 或其他非 GraphQL 执行路径。若希望在捕获后仍向外抛出错误可在上报后throw err由 Redwood 的全局错误处理继续兜底。用 Sentry.ErrorBoundary 替换默认错误边界Web 侧的setup任务还会自动改写web/src/App.tsx将 Redwood 默认的FatalErrorBoundary替换为Sentry.ErrorBoundary实现见 sentryHandler.ts。替换后的效果等价于import { RedwoodProvider } from redwoodjs/web import Sentry from src/lib/sentry // ... Sentry.ErrorBoundary fallback{FatalErrorPage} {/* 应用内容 */} /Sentry.ErrorBoundarySentry.ErrorBoundary是sentry/react提供的 React 错误边界组件它接管渲染阶段抛出的错误既会将错误上报到 Sentry又会渲染fallback指定的FatalErrorPage作为兜底 UI与 Redwood 原有的FatalErrorBoundary行为对齐从而保证上报 优雅降级两者兼得。验证与常见问题排查完成配置后可以从以下几个方面验证集成是否生效DSN 是否到位检查 API 侧运行环境的SENTRY_DSN以及 Web 侧redwood.toml的includeEnvironmentVariables是否包含SENTRY_DSN缺失时 Web 侧控制台会打印模板内置的红色报错GraphQL 插件是否注入打开api/src/functions/graphql.ts确认存在extraPlugins: [useSentry(...)]与import src/lib/sentry初始化文件是否存在确认api/src/lib/sentry.ts与web/src/lib/sentry.ts已生成且无语法错误错误边界是否替换查看web/src/App.tsx中是否为Sentry.ErrorBoundary主动触发一次异常在某个 API 函数中调用Sentry.captureException(new Error(test))或直接抛错前往 Sentry 后台确认事件与 Span 是否出现。若需要从零开始对照练习可参考仓库中的 empty-project 与 test-project 等 fixture 工程结构结合 cli-commands.md 了解相关 CLI 命令的完整行为。至此Redwood 应用已经具备完整的 Sentry 错误上报与性能监控能力。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐Redwood 应用接入 Sentry错误监控与性能追踪完整实战指南Redwood 应用接入 Sentry错误监控与性能追踪完整实战指南 Sentry 是 Redwood 官方推荐的全栈错误监控与性能追踪方案。 本文基于 Re后端前端Web框架开发工具Next.js 错误监控终极指南Sentry 集成与配置完整教程Next.js 错误监控终极指南Sentry 集成与配置完整教程 在当今快速发展的Web开发环境中 Next.js错误监控 已成为构建稳定应用的关键环节。本前端UI组件终极指南使用SPFx构建Viva Connections Adaptive Card Extensions (ACEs)实战教程终极指南使用SPFx构建Viva Connections Adaptive Card Extensions ACEs 实战教程 SharePoint Fram上一篇Places365源码解析深入理解PyTorch实现的核心逻辑下一篇JSON:API时间戳处理终极指南高效管理时序数据的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考