cmwrun

Appearance

Sentry 集成完整指南 ​

概述 ​

本项目性能仪表板集成了 Sentry APM（应用程序性能监控） 功能，用于收集和可视化：

  • Web Vitals 指标（FCP、LCP、CLS、INP、TTFB）
  • 错误监控数据（错误率、错误类型、堆栈跟踪）
  • 性能趋势（日/周/月数据对比）

快速开始（5 分钟） ​

1. Sentry 账户和项目设置 ​

步骤 1.1：创建 Sentry 账户 ​

  • 访问 https://sentry.io/
  • 使用邮箱或 GitHub 账号注册（推荐 GitHub）
  • 验证邮箱地址

步骤 1.2：创建组织 ​

  • 登录后点击"Create Organization"
  • 输入组织名称（如 cmwrun）
  • 选择自托管或云托管（推荐云托管）

步骤 1.3：创建项目 ​

  • 在组织内点击"Create Project"
  • 选择平台：JavaScript → Browser
  • 项目名称：vitepress 或你的项目名
  • 创建完毕后得到 Project Slug 和 Organization Slug

2. 获取认证凭证 ​

Auth Token（必需） ​

  1. 访问 Account Settings
  2. 左侧菜单选择 API → Auth Tokens
  3. 点击 Create New Token
  4. 配置权限：
    • ✅ org:read - 读取组织信息
    • ✅ event:read - 读取错误事件
    • ✅ project:read - 读取项目信息
  5. 复制生成的 token（仅显示一次，妥善保管）

DSN（Client Key） ​

  1. 访问项目设置：Settings → Client Keys (DSN)
  2. 复制 DSN 字符串（格式：https://key@host/project-id）

3. 配置环境变量 ​

创建 .env 文件 ​

bash
# 在项目根目录创建 .env 文件
cp .env.example .env

填写环境变量 ​

bash
# 从步骤 2 获取的 Auth Token
VITE_SENTRY_AUTH_TOKEN=your_really_long_token_here

# 你的 Sentry 组织 slug（来自项目设置的 URL）
# 例如：https://sentry.io/organizations/cmwrun/
VITE_SENTRY_ORG=cmwrun

# 你的 Sentry 项目 slug
# 例如：https://sentry.io/organizations/cmwrun/projects/vitepress/
VITE_SENTRY_PROJECT=vitepress

# 客户端 DSN（用于在前端上报错误）
VITE_SENTRY_DSN=https://xxxxx@o123456.ingest.sentry.io/xxxxxx

# Sentry API 服务器地址
VITE_SENTRY_API_URL=https://sentry.io

# 环境标识
VITE_SENTRY_ENVIRONMENT=development

# 启用/禁用 Sentry
VITE_ENABLE_SENTRY=true

⚠️ 安全提示：

  • 不在 Git 中提交 .env 文件（已在 .gitignore 中）
  • 在生产环境中，使用 CI/CD 管道的 Secrets 功能设置环境变量
  • Auth Token 只允许读取权限，但仍应视为敏感信息

4. 验证配置 ​

开发服务器启动 ​

bash
pnpm docs:dev

测试连接 ​

打开浏览器控制台监控日志：

javascript
// 在浏览器控制台执行
const client = await import('.vitepress/theme/sentry-api.js').then((m) => new m.default());
client.getProjectStats().then(console.log);

预期结果 ​

✅ 如果看到包含 errorCount 和 metrics 的 JSON 对象，配置成功

❌ 如果看到 402 或 401 错误，检查：

  • Auth Token 是否正确
  • Organization Slug 是否正确
  • Project Slug 是否正确

性能仪表板使用 ​

功能概览 ​

💯 性能评分 ​

  • 90-100：优秀 - 网站性能表现出色
  • 70-89：良好 - 网站正常运行，部分性能可优化
  • 0-69：需要改进 - 存在性能问题，需要立即优化

📊 实时指标卡 ​

指标单位目标说明
FCP秒< 1.0s首次内容绘制，页面开始显示内容的时间
LCP秒< 2.5s最大内容绘制，主要元素加载完成的时间
CLS无< 0.1累积布局移动，页面加载过程中的抖动程度
INPms< 200ms交互响应时间，用户交互到响应的延迟
TTFBms< 600ms首字节时间，网络延迟指标
错误个= 0最近捕获的 JavaScript 错误数

⏱️ 时间范围选择 ​

最近 1 小时  |  最近 24 小时  |  最近 7 天  |  最近 30 天

自动从 Sentry 拉取相应时间段的数据

🔄 手动刷新 & 自动刷新 ​

  • 手动刷新：点击"刷新数据"按钮立即更新
  • 自动刷新：每 5 分钟自动从 Sentry 拉取最新数据

数据备用方案 ​

如果 Sentry 未配置或无法连接：

⚠️ Sentry 未配置，显示模拟数据。请配置 .env 文件。
  • 仪表板仍显示数据，但使用随机生成的演示数据
  • 这对于本地开发和测试非常有用
  • 生产环境务必配置真实的 Sentry 凭证

Sentry API 集成细节 ​

API 客户端位置 ​

.vitepress/theme/sentry-api.ts

可用的 API 方法 ​

获取项目统计 ​

typescript
const stats = await sentryClient.getProjectStats();

返回：

typescript
{
  errorCount: number;        // 总错误数
  errorRate: number;         // 错误率（百分比）
  events: SentryEvent[];     // 错误事件列表
  metrics: SentryMetric[];   // 性能指标
  lastUpdated: string;       // 最后更新时间
}

获取最近错误 ​

typescript
const errors = await sentryClient.getRecentErrors((limit = 10));

返回最近 N 个错误事件的详细信息。

获取性能指标 ​

typescript
const metrics = await sentryClient.getPerformanceMetrics('24h');
// 支持的时间范围：'1h', '24h', '7d', '30d'

获取错误趋势 ​

typescript
const trend = await sentryClient.getErrorTrend('7d');

返回按日期聚合的错误数据，适合绘制图表。

创建告警规则 ​

typescript
await sentryClient.createAlertRule('高错误率告警', 'error_rate > 5%', [
  {
    service: 'slack',
    params: { channel: '#alerts', webhook_url: '...' },
  },
]);

错误处理 ​

API 客户端内置错误处理：

typescript
try {
  const data = await sentryClient.getProjectStats();
} catch (error) {
  console.error('Sentry API 调用失败:', error);
  // 自动回退到模拟数据
}

告警与通知配置 ​

按 Sentry 事项告警 ​

访问项目的 Alerts 页面：

Settings → Alerts → Create Alert Rule

配置步骤 ​

  1. 选择条件

    • When: Error event is assigned to me
    • When: An event is seen + 频率条件

  2. 设置阈值

    • Event rate: > 10 events/minute
    • Error rate: > 5%

  3. 配置动作

    • 发送到 Slack：选择 channel
    • 发送邮件：输入邮箱地址
    • Webhook：粘贴自定义 webhook URL

  4. 保存规则

Slack 集成（推荐） ​

步骤 1：创建 Slack Webhook ​

  1. 访问 Slack API
  2. 选择或创建你的应用
  3. 启用"Incoming Webhooks"
  4. 点击"Add New Webhook to Workspace"
  5. 选择通知频道（如 #alerts 或 #performance）
  6. 授权并复制 Webhook URL

步骤 2：在 Sentry 中配置 ​

进入项目的 Integrations：

Settings → Integrations → Slack
  • 安装之后，创建告警规则时选择 Slack 作为 Action
  • 选择频道和通知内容

演示消息 ​

当 Sentry 捕捉到错误时，Slack 会收到：

🚨 [Production] Error: Cannot read property 'x' of undefined
Project: cmwrun / vitepress
Error Rate: 8.5%  |  Users Affected: 233
[View in Sentry] [Assign]

生产环境配置 ​

Vercel / Netlify 部署 ​

Vercel 环境变量配置 ​

在项目设置中：

Settings → Environment Variables

添加：

VITE_SENTRY_AUTH_TOKEN  = your_token
VITE_SENTRY_ORG         = your_org
VITE_SENTRY_PROJECT     = your_project
VITE_SENTRY_DSN         = your_dsn
VITE_SENTRY_ENVIRONMENT = production

GitHub Actions 配置 ​

在 .github/workflows 中的部署脚本：

yaml
env:
  VITE_SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  VITE_SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
  VITE_SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
  VITE_SENTRY_DSN: ${{ secrets.SENTRY_DSN }}

Docker 部署 ​

在 Dockerfile 中：

dockerfile
ARG VITE_SENTRY_AUTH_TOKEN
ARG VITE_SENTRY_ORG
ARG VITE_SENTRY_PROJECT
ARG VITE_SENTRY_DSN

ENV VITE_SENTRY_AUTH_TOKEN=$VITE_SENTRY_AUTH_TOKEN
ENV VITE_SENTRY_ORG=$VITE_SENTRY_ORG
# ... 其他变量

启动时：

bash
docker run \
  -e VITE_SENTRY_AUTH_TOKEN=xxx \
  -e VITE_SENTRY_ORG=yyy \
  # ... 其他变量
  your-image

成本优化 ​

Sentry 定价规则 ​

  • 免费计划：每月 5,000 事件
  • 付费计划：按超出事件数计费（约 $0.50 per 1K events）

降低成本的策略 ​

1. Performance Monitoring 采样 ​

采样 50% 的事务：

typescript
// .vitepress/theme/performance.ts
import * as Sentry from '@sentry/vue';

Sentry.init({
  tracesSampleRate: 0.5, // 仅跟踪 50% 的页面加载
});

2. 错误采样 ​

对于高频错误，采样报告：

typescript
beforeSend(event, hint) {
  // 只报告 10% 的 NetworkError 事件
  if (event.exception?.values?.[0].type === 'NetworkError') {
    return Math.random() > 0.1 ? null : event;
  }
  return event;
}

3. 按环境过滤 ​

生产环境才上报敏感数据：

typescript
VITE_SENTRY_ENVIRONMENT = development; // 本地仅上报错误
VITE_SENTRY_ENVIRONMENT = production; // 生产全量上报

故障排除 ​

问题：Auth Token 显示 "Unauthorized" ​

原因：Token 权限不足或已过期

解决：

  1. 访问 Auth Tokens
  2. 验证 Token 权限包括：org:read, event:read, project:read
  3. 如果已过期，删除并创建新 Token

问题：仪表板显示 "Sentry 未配置，显示模拟数据" ​

原因：环境变量未正确设置

检查清单：

bash
# 检查 .env 文件是否存在
ls -la .env

# 检查变量是否正确
echo $VITE_SENTRY_AUTH_TOKEN
echo $VITE_SENTRY_ORG
echo $VITE_SENTRY_PROJECT

问题：API 返回 403 Forbidden ​

原因：

  • Token 没有项目读取权限
  • Org Slug 或 Project Slug 错误

解决：

  1. 访问 https://sentry.io/api/0/organizations/ 验证 Org Slug
  2. 在项目设置中确认 Project Slug
  3. 重新创建具有完整权限的 Token

问题：TTFB 或 CLS 数据为空 ​

原因：Sentry 尚未收集足够数据

解决：

  • 为页面生成流量（在浏览器中访问页面）
  • 等待 5-10 分钟让数据上报到 Sentry
  • 检查项目是否正确安装了 web-vitals 注入

最佳实践 ​

✅ 应该做的事 ​

  1. 定期检查仪表板

    • 每周查看一次性能趋势
    • 注意 LCP 和 TTFB 的上升趋势

  2. 设置合理的告警阈值

    • Error Rate > 1% → 通知
    • LCP > 4s → 警告
    • TTFB > 1000ms → 警告

  3. 在发布前检查

    • 部署前后对比性能指标
    • 确保新版本不会降低 Vitals

  4. 使用源地图（SourceMaps）

    bash
    # .env
VITE_SENTRY_ENABLE_SOURCE_MAPS=true

  5. 跨浏览器监控

    • 区分 Chrome、Firefox、Safari 的性能
    • Sentry 自动分类

❌ 不应该做的事 ​

  1. ❌ 在源代码中硬编码 Auth Token
  2. ❌ 将 .env 提交到 Git
  3. ❌ 在生产环境采样 100% 的错误（成本太高）
  4. ❌ 忽视 CLS 指标（严重影响用户体验）
  5. ❌ 设置过敏感的告警规则（造成告警疲劳）

常用命令 ​

bash
# 开发模式启动（使用模拟数据或 Sentry）
pnpm docs:dev

# 构建生产版本
pnpm docs:build

# 本地预览生产构建
pnpm docs:preview

# 检查类型（确保 Sentry API 类型正确）
pnpm typecheck

# 运行单元测试
pnpm test

相关资源 ​

获取帮助 ​

最后更新：2024 年 维护者：cmwrun team

内容仅供学习参考，如有错误欢迎指正与 PR

Copyright © 2024-present cmwrun