应用监控

🚀 Cheatsheet (快速执行)

目标: 10分钟内配置错误监控和性能追踪，第一时间发现线上问题

最快上手方式:

# 1. 注册 Sentry 账号并创建项目
# https://sentry.io/signup

# 2. 安装 Sentry SDK
bun add @sentry/nextjs

# 3. 配置环境变量
echo 'SENTRY_DSN=你的项目DSN' >> .env.local
echo 'SENTRY_AUTH_TOKEN=你的授权令牌' >> .env.local

# 4. 自动配置向导
npx @sentry/wizard nextjs

立即生效: 重启应用后，所有错误和性能数据自动上报到 Sentry 控制台

❓ 为什么要做应用监控

对 MVP 的关键价值:

提前发现问题: 用户还没投诉，你就知道哪里出错了
定位问题根因: 不用猜测，直接看到错误堆栈和用户操作路径
性能优化: 发现慢查询、内存泄漏等性能瓶颈
用户体验保障: 确保核心功能（注册、支付）稳定可用

真实场景举例: 你的支付接口突然报错 10 次，Sentry 立即通知你，并显示是 Stripe API 超时导致，你马上修复，避免了收入损失。

🤔 为什么选择 Sentry

我们的实战经验:

错误追踪精准: 精确到代码行，包含完整上下文
性能监控全面: API 响应时间、数据库查询、页面加载
通知及时: 邮件、Slack、钉钉多渠道报警
免费额度充足: 月度 5000 个错误事件，初期完全够用

对比其他方案:

# Sentry     - ⭐ 推荐，功能全面，Next.js 支持好
# LogRocket  - 用户会话录制，但价格贵
# Bugsnag    - 错误追踪专业，但生态不如 Sentry
# DataDog    - 企业级监控，但配置复杂且昂贵

🧠 简要原理 & 最简案例

监控系统架构: 应用错误/性能数据 → Sentry SDK → 自动上报 → Sentry 服务器 → 报警通知

核心监控内容:

// 1. 自动错误捕获（无需代码）
try {
  await fetchUserData()
} catch (error) {
  // Sentry 自动捕获并上报
}

// 2. 性能监控（自动启用）
// API 调用时间、数据库查询、页面加载速度

// 3. 自定义事件追踪
import * as Sentry from '@sentry/nextjs'

Sentry.captureMessage('用户完成支付', 'info')

🛠️ 实际操作步骤

1. 创建 Sentry 项目 (3分钟)

注册和项目设置:

访问 sentry.io 注册账号
创建组织（Organization）
选择 Next.js 作为平台
获取项目 DSN（数据源名称）

重要信息记录:

DSN: https://xxx@xxx.ingest.sentry.io/xxx
Project ID: 你的项目ID  
Auth Token: 稍后在设置中生成

2. 安装和配置 Sentry SDK (5分钟)

安装依赖:

bun add @sentry/nextjs

自动配置（推荐）:

# 运行配置向导
npx @sentry/wizard nextjs

# 向导会自动：
# 1. 创建 sentry.client.config.ts
# 2. 创建 sentry.server.config.ts  
# 3. 创建 sentry.edge.config.ts
# 4. 修改 next.config.ts
# 5. 添加 instrumentation.ts

3. 环境变量配置 (2分钟)

# .env.local
SENTRY_DSN=https://你的dsn@sentry.io/项目id
SENTRY_AUTH_TOKEN=你的授权令牌  
SENTRY_SUPPRESS_TURBOPACK_WARNING=1

获取 Auth Token:

Sentry 控制台 > Settings > Auth Tokens
Create New Token > 选择 project:write 权限
复制 token 到环境变量

💡 关键文件配置

Next.js 配置集成

// next.config.ts
import { withSentryConfig } from '@sentry/nextjs'

const nextConfig = {
  // 你的 Next.js 配置
}

export default withSentryConfig(nextConfig, {
  org: "你的组织名",
  project: "你的项目名", 
  authToken: process.env.SENTRY_AUTH_TOKEN,
  
  // 使用隧道路由避免广告拦截
  tunnelRoute: "/monitoring-tunnel",
  
  // 上传源码映射（生产环境）
  uploadSourceMaps: process.env.NODE_ENV === 'production',
})

中间件配置

// middleware.ts
export const config = {
  matcher: [
    // 排除 Sentry 隧道路由
    "/((?!api|_next/static|_next/image|favicon.ico|monitoring-tunnel).*)",
  ],
}

全局错误处理

// app/global-error.tsx
'use client'
import * as Sentry from '@sentry/nextjs'
import NextError from 'next/error'
import { useEffect } from 'react'

export default function GlobalError({ error }: { error: Error }) {
  useEffect(() => {
    Sentry.captureException(error)
  }, [error])

  return (
    <html>
      <body>
        <h2>应用出现了错误</h2>
        <p>我们已收到错误报告，正在修复中</p>
      </body>
    </html>
  )
}

📊 监控配置详解

错误监控设置

// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  
  // 性能监控采样率
  tracesSampleRate: 1.0,
  
  // 会话重放（用户操作录制）
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  
  // 开发环境调试
  debug: process.env.NODE_ENV === 'development',
  
  // 集成配置
  integrations: [
    Sentry.replayIntegration(),
  ],
})

服务端监控设置

// sentry.server.config.ts
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  
  // 服务端特定配置
  environment: process.env.NODE_ENV,
  
  // 过滤敏感信息
  beforeSend(event) {
    // 移除敏感数据
    if (event.request?.headers) {
      delete event.request.headers.authorization
    }
    return event
  },
})

🎯 实用监控场景

场景1: API 错误监控

// app/api/users/route.ts
import * as Sentry from '@sentry/nextjs'

export async function GET() {
  try {
    const users = await db.user.findMany()
    return Response.json(users)
  } catch (error) {
    // 自动上报错误，包含请求上下文
    Sentry.captureException(error, {
      tags: { api: 'users' },
      extra: { timestamp: new Date().toISOString() }
    })
    
    return Response.json(
      { error: '获取用户列表失败' }, 
      { status: 500 }
    )
  }
}

场景2: 支付流程监控

// 支付处理监控
async function processPayment(paymentData) {
  const transaction = Sentry.startTransaction({
    name: 'payment_process',
    op: 'payment'
  })
  
  try {
    // 监控支付 API 调用
    const result = await stripe.paymentIntents.create(paymentData)
    
    Sentry.addBreadcrumb({
      message: '支付创建成功',
      data: { paymentId: result.id }
    })
    
    return result
  } catch (error) {
    // 支付错误立即报警
    Sentry.captureException(error, {
      tags: { 
        component: 'payment',
        severity: 'critical' 
      }
    })
    throw error
  } finally {
    transaction.finish()
  }
}

场景3: 用户行为监控

// 关键用户操作监控
function trackUserAction(action: string, details: any) {
  Sentry.addBreadcrumb({
    message: `用户操作: ${action}`,
    category: 'user',
    data: details,
    level: 'info'
  })
  
  // 对关键操作设置检查点
  if (['signup', 'payment', 'subscription'].includes(action)) {
    Sentry.setTag('critical_action', action)
  }
}

🔧 高级监控功能

性能监控

// 自定义性能追踪
const transaction = Sentry.startTransaction({
  name: 'database_query',
  op: 'db'
})

const span = transaction.startChild({
  op: 'db.query',
  description: 'SELECT * FROM users'
})

// 执行数据库查询
const users = await db.user.findMany()

span.finish()
transaction.finish()

用户上下文关联

// 登录用户信息关联
useEffect(() => {
  if (user) {
    Sentry.setUser({
      id: user.id,
      email: user.email,
      subscription: user.subscription?.plan
    })
    
    Sentry.setTag('user_type', user.subscription?.plan || 'free')
  }
}, [user])

自定义报警规则

// 基于业务逻辑的报警
if (errorRate > 0.05) { // 错误率超过 5%
  Sentry.captureMessage('错误率过高，需要关注', 'warning')
}

if (responseTime > 3000) { // 响应时间超过 3秒
  Sentry.captureMessage('API 响应过慢', 'warning')
}

🔔 报警通知配置

邮件和 Slack 通知

# Sentry 控制台配置
1. Project > Settings > Alerts
2. Create Alert Rule
3. 设置触发条件：
   - 新错误出现
   - 错误频率过高  
   - 性能下降
4. 配置通知渠道：
   - 邮件通知
   - Slack 频道
   - 钉钉群聊

智能通知规则

// 示例报警规则
{
  "conditions": [
    {
      "event.type": "error",
      "count": "> 10",  
      "time": "1 minute"
    }
  ],
  "actions": [
    {
      "type": "email",
      "targets": ["admin@example.com"]
    }
  ]
}

🆘 常见问题解决

问题1: 源码映射未生效

# 检查构建配置
echo $SENTRY_AUTH_TOKEN

# 确认上传设置
bun run build --verbose

# 手动上传源码映射
npx @sentry/cli releases files VERSION upload-sourcemaps ./build

问题2: 过多噪音报警

// 过滤不重要的错误
beforeSend(event) {
  // 忽略网络错误
  if (event.exception?.values?.[0]?.type === 'NetworkError') {
    return null
  }
  
  // 忽略开发环境错误
  if (process.env.NODE_ENV === 'development') {
    return null
  }
  
  return event
}

问题3: 性能影响

// 调整采样率
tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,

// 异步上报
async: true,

// 批量上报
transport: Sentry.makeBrowserOfflineTransport(Sentry.makeFetchTransport)

📎 延伸阅读

官方文档:

Sentry Next.js 集成 - 官方集成指南
Sentry 性能监控 - 性能追踪详解

最佳实践:

错误监控策略 - React 应用监控指南
生产环境监控 - 配额管理和优化

工具推荐:

Sentry CLI - 命令行工具
Sentry Dashboard - 监控面板

下一步: 配置好监控后，查看 [测试指南]./testing) 了解如何编写自动化测试。

应用监控

On this page