telegram-management-system/frontend/SENTRY_INTEGRATION.md

Sentry 错误监控集成指南

概述

本项目已集成 Sentry 错误监控系统，用于实时监控和追踪 Telegram 管理系统的错误、性能和用户行为。

功能特性

1. 自动错误捕获

• Vue 应用全局错误处理
• API 请求错误监控
• WebSocket 连接错误追踪
• UI 组件错误记录

2. 性能监控

• API 请求响应时间
• 页面加载性能
• 用户交互延迟
• 会话重播（Session Replay）

3. 用户行为追踪

• 页面访问记录
• 用户操作行为
• 任务操作监控
• 搜索和筛选行为

4. Telegram 专用监控

• 任务创建和执行状态
• 消息发送成功率
• 目标用户添加监控
• 引擎状态变化追踪

配置说明

环境变量配置

开发环境 (.env.development)

VUE_APP_SENTRY_DSN=your_development_dsn
VUE_APP_SENTRY_ENVIRONMENT=development
VUE_APP_SENTRY_DEBUG=true

生产环境 (.env.production)

VUE_APP_SENTRY_DSN=your_production_dsn
VUE_APP_SENTRY_ENVIRONMENT=production
VUE_APP_SENTRY_DEBUG=false

采样率配置

• 开发环境: 100% 错误采样，100% 性能监控
• 生产环境: 80% 错误采样，10% 性能监控，10% 会话重播

使用方法

1. 在组件中手动发送错误

// 导入工具函数
import { sentryUtils, ERROR_TYPES } from '@/config/sentry'

// 发送自定义错误
this.$sentryUtils.captureError(
  new Error('自定义错误消息'),
  ERROR_TYPES.VALIDATION_ERROR,
  { 
    component: 'MyComponent',
    userInput: formData 
  }
)

// 记录用户行为
this.$sentryUtils.captureUserAction('button_clicked', {
  buttonName: 'submit',
  formType: 'task_creation'
})

2. Telegram 专用监控

import telegramSentry, { TASK_STATUSES } from '@/libs/sentryTelegram'

// 监控任务创建
telegramSentry.trackTaskCreation(taskData, result)

// 监控任务执行状态
telegramSentry.trackTaskExecution(taskId, TASK_STATUSES.RUNNING, metrics)

// 监控消息发送
telegramSentry.trackMessageSend(taskId, targetId, success, error)

// 监控 Telegram API 错误
telegramSentry.trackTelegramApiError('sendMessage', error, context)

3. 设置用户上下文

// 在组件 mounted 中设置用户信息
mounted() {
  this.$sentryUtils.setUser({
    id: this.$store.state.user.id,
    username: this.$store.state.user.name,
    email: this.$store.state.user.email
  })
}

错误类型

通用错误类型

• api_error: API 请求错误
• validation_error: 数据验证错误
• network_error: 网络连接错误
• ui_error: 用户界面错误
• websocket_error: WebSocket 连接错误

Telegram 专用错误类型

• task_creation_failed: 任务创建失败
• target_addition_failed: 目标用户添加失败
• message_send_failed: 消息发送失败
• telegram_auth_failed: Telegram 认证失败
• rate_limit_exceeded: 频率限制超出
• invalid_username: 无效用户名
• chat_not_found: 聊天不存在

数据隐私

自动过滤的敏感信息

• 密码和认证令牌
• 个人身份信息 (PII)
• API 密钥和密钥

发送的上下文信息

• 用户 ID 和用户名（非敏感）
• 错误发生的页面和组件
• API 请求的 URL 和方法
• 任务和操作的元数据

监控仪表板

Sentry 仪表板功能

1. 错误追踪: 实时错误监控和告警
2. 性能分析: API 和页面性能指标
3. 用户会话: 用户行为和操作回放
4. 发布追踪: 代码发布和错误关联

关键指标

• 错误率和错误趋势
• API 响应时间分布
• 用户活跃度和操作频率
• 任务成功率和失败原因

最佳实践

1. 错误处理

try {
  await riskyOperation()
} catch (error) {
  // 记录错误并提供上下文
  this.$sentryUtils.captureError(error, ERROR_TYPES.API_ERROR, {
    operation: 'riskyOperation',
    userId: this.currentUserId,
    timestamp: new Date().toISOString()
  })
  
  // 用户友好的错误提示
  this.$Message.error('操作失败，请稍后重试')
}

2. 性能监控

// 监控长时间运行的操作
const startTime = Date.now()
await heavyOperation()
const duration = Date.now() - startTime

if (duration > 3000) {
  this.$sentryUtils.captureMessage('slow_operation', {
    operation: 'heavyOperation',
    duration: duration
  })
}

3. 用户体验追踪

// 记录用户关键操作
onTaskCreate() {
  this.$sentryUtils.captureUserAction('task_create_started')
  // ... 任务创建逻辑
}

故障排除

常见问题

1. Sentry 事件未发送

   • 检查 DSN 配置是否正确
   • 确认网络连接正常
   • 查看浏览器控制台错误

2. 采样率过低

   • 调整环境变量中的采样率设置
   • 开发环境建议设置为 100%

3. 敏感信息泄露

   • 检查 beforeSend 过滤规则
   • 避免在错误上下文中包含敏感数据

调试模式

开发环境启用调试模式：

// 在 .env.development 中设置
VUE_APP_SENTRY_DEBUG=true

更新和维护

定期检查

• 每月检查错误趋势和新增错误类型
• 定期清理过期的任务指标数据
• 更新错误过滤规则

配置优化

• 根据实际使用情况调整采样率
• 优化错误分组和标签系统
• 完善用户上下文信息

技术支持

如有技术问题或需要配置支持，请联系开发团队或查看 Sentry 官方文档。