monitoring-setup

监控设置

分为两层：应用健康状况（错误、用户行为）和运维健康状况（队列是否正在清空、数据库是否跟得上）。即使应用的 Sentry 一切正常，如果队列积压，或每个请求都触发表扫描，用户仍会受到影响——两方面都要覆盖。

适用场景

• 需要设置错误跟踪（Sentry）
• 想要配置 Google Analytics
• 需要监控生产应用
• 想要跟踪应用错误和用户行为
• 需要运维信号：队列深度、慢查询、连接饱和度，以及针对这些信号的告警

Sentry 设置

NestJS 后端

1. 安装：bun add @sentry/node @sentry/profiling-node
2. 在创建应用前于 main.ts 中初始化
3. 通过 SENTRY_DSN 环境变量配置 DSN
4. 为生产环境设置合适的采样率

Next.js 前端

1. 安装：bun add @sentry/nextjs
2. 运行：bunx @sentry/wizard@latest -i nextjs
3. 配置客户端/服务端/边缘配置
4. 为客户端设置 NEXT_PUBLIC_SENTRY_DSN

Google Analytics 设置

Next.js 设置

1. 将 Google Analytics 脚本添加到根布局
2. 使用 NEXT_PUBLIC_GA_MEASUREMENT_ID（格式：G-XXXXXXXXXX）
3. 创建用于事件跟踪的分析工具函数
4. 设置页面浏览跟踪

常见事件

• 用户注册/登录
• 购买/转化
• 功能使用情况
• 自定义业务事件

运维监控

应用错误会告诉你哪里抛出了异常；运维信号则会告诉你哪里在悄然退化。在负载下会导致产品故障的三个方面，都要做好监控。

BullMQ 队列深度

队列填充速度超过清空速度，就像一场缓慢发生的宕机——只有作业超时后才会触发错误。

• 按队列跟踪：waiting（积压）、active、failed 和完成速率。Queue.getJobCounts() 可以提供这些数据；按间隔抓取，或通过 bullmq-prometheus 抓取。
• 关键在于趋势：waiting 持续上升而 completed 持平，意味着工作进程跟不上（扩容工作进程或 Redis 连接）。
• 关注死信/失败集合——重试耗尽的作业会造成无声的数据丢失。

Postgres 慢查询与连接

• 启用 pg_stat_statements；按总耗时和平均耗时展示耗时最高的查询。单次执行很快、但每分钟运行 1 万次的查询，才是真正的成本所在。
• 记录超过阈值的查询（log_min_duration_statement），并对新出现的慢查询发出告警——慢查询通常意味着缺少索引或存在 N+1 问题。
• 跟踪连接饱和度（active / max_connections）。无服务器环境中的连接数接近上限，意味着连接池规模不足——参见 postgres-ops。

Redis

• 内存使用量与 maxmemory 的对比、驱逐速率和命令延迟。发生驱逐意味着缓存过小，命中率正在悄然下降。

告警

没人查看的监控数据不算监控。针对上述每个信号，都要设定阈值，并将告警发送到凌晨 3 点有人能看到的地方（PagerDuty、Opsgenie，或会触发呼叫的 Slack 频道）。要针对先行指标告警（队列 waiting 持续上升、连接数接近上限），而不只是针对滞后指标告警（作业已经超时、已经返回 500）。每条告警都要说明应采取的运行手册步骤，否则它就只是噪声。

最佳实践

• 开发环境和生产环境使用不同的 DSN
• 设置合适的采样率
• 尊重用户隐私（GDPR/CCPA）
• 不要跟踪敏感数据
• 针对先行运维指标发出告警，而不仅仅是在问题发生后针对错误告警
• 每条告警都关联到运行手册操作——不要留下孤立告警

集成

此技能与 /monitoring-setup 命令集成，可用于自动化设置工作流。可与 postgres-ops（连接池、灾难恢复）和 nestjs-queue-architect（队列设计）配合使用。