监控概览

了解 Nebutra 如何通过 Sentry 和结构化 @nebutra/logger 包监控错误、性能和日志。

Nebutra 的监控栈让你对 Next.js 前端和 Hono API Gateway 的应用健康状况保持完整的可见性。

监控内容

层级	工具	捕获内容
客户端错误	Sentry（浏览器 SDK）	未处理的异常、React 错误边界
服务端错误	Sentry（Node SDK）	API 错误、未处理的 Promise 拒绝
性能监控	Sentry Tracing	HTTP 请求追踪、DB 查询耗时、p99 延迟
结构化日志	`@nebutra/logger`	所有 `info` / `warn` / `error` 事件（含租户上下文）
发布追踪	Sentry Releases	每次部署自动上传源码映射，关联提交记录
产品分析	PostHog	漏斗、留存、会话回放、功能使用情况

职责边界

关注点	负责人
代码失败、堆栈、发布回归	Sentry
用户旅程、漏斗流失、会话回放	PostHog
请求内结构化事件和 trace ID	`@nebutra/logger` + OpenTelemetry
活动链接和邀请归因	Dub via `createAnalyticsClient`

PostHog 和 Sentry 可以通过共享的 userId、organizationId、request ID 和 release 值做关联，但不要互相替代。

架构

应用代码
    │
    ▼
@nebutra/logger  ──────────────────────────────────►  stdout（JSON）
    │                                                      │
    │  （warn / error 级别）                               │
    ▼                                                      ▼
Sentry SDK                                    日志聚合器（可选）
    │                                         （Datadog、Loki、CloudWatch）
    ▼
Sentry 云端
    │
    ├──► 错误追踪（问题、堆栈跟踪）
    ├──► 性能监控（traces、spans）
    └──► 告警（邮件、Slack、PagerDuty）

@nebutra/logger 发出的每条 warn 和 error 日志都会自动作为 Sentry 面包屑或事件转发。无需手动调用 Sentry.captureException——日志记录器会自动处理。

告警渠道

Sentry 支持多种告警目标。推荐配置：

严重程度	告警渠道
新错误（首次出现）	Slack `#eng-alerts`
错误激增（1 小时内超过 10 个新错误）	Slack `#eng-alerts` + 邮件
P1（高频未处理错误）	PagerDuty
性能退化（p99 > 2s）	Slack `#eng-alerts`

在 Sentry 中前往告警 → 创建告警规则进行配置。

关键监控指标

错误率

目标：5xx 错误率 < 0.1%

告警阈值：每分钟超过 5 个错误且持续 5 分钟

仪表盘：Sentry → 问题标签页，按环境过滤

API 延迟（p99）

目标：所有 /api/v1/* 端点的 p99 < 500ms

告警阈值：任意端点在 15 分钟窗口内 p99 > 2s

仪表盘：Sentry → 性能 → 事务

配额使用率

来源：quota_warning 和 quota_exceeded 事件（PostHog + 日志）

目标：每月触发配额超限的租户 < 5%

仪表盘：管理面板 /admin/analytics

环境变量

# Sentry — 服务端（API Gateway + Next.js 服务端组件）
SENTRY_DSN=https://[email protected]/XXXX
SENTRY_AUTH_TOKEN=sntrys_xxxxxxxxxxxx   # 用于 CI 中的源码映射上传
SENTRY_ORG=your-sentry-org-slug
SENTRY_PROJECT=nebutra

# Sentry — 客户端（浏览器，必须以 NEXT_PUBLIC_ 开头）
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/XXXX

# PostHog — 服务端产品事件
POSTHOG_KEY=phc_xxxxxxxxxxxx
POSTHOG_HOST=https://us.i.posthog.com

# PostHog — 浏览器 SDK
NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxx
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

SENTRY_AUTH_TOKEN 授予对你的 Sentry 组织的写入权限。切勿在客户端代码中暴露，也不要提交到版本控制中。请将其作为 CI 密钥存储（GitHub Actions secret / Vercel 环境变量，仅限服务端作用域）。

在开发环境中禁用监控

默认情况下，Sentry 在 development 环境中被禁用，以避免污染生产数据。这由 @nebutra/logger 中的 NODE_ENV 检查控制：

# .env.local — 当此变量为空或环境为 development 时，Sentry 不会上报
SENTRY_DSN=   # 留空以禁用

在开发环境中，@nebutra/logger 仍会向 stdout 输出结构化 JSON。你可以通过 pnpm dev 2>&1 | jq '.' 以格式化方式查看。

Sentry 配置

配置 Sentry 错误追踪、性能监控和发布追踪。

结构化日志

学习如何使用 @nebutra/logger 进行结构化、感知租户的日志记录。

分析概览

使用 PostHog 进行产品分析，使用 Dub.co 进行营销分析。

部署

CI/CD 流水线配置，包括源码映射上传和发布追踪。

Sentry 配置

结构化日志

分析概览

部署

目录