api-observability-setup-axiom-pino-sentry

可观测性设置（Pino + Axiom + Sentry）

快速指南： 一次性项目可观测性设置。安装 pino、next-axiom、@sentry/nextjs。配置 Axiom 数据集和 Vercel 集成。设置 Sentry DSN 和配置文件。用 withAxiom 包装 next.config.ts，然后再用 withSentryConfig 包装。添加 instrumentation.ts，用于针对运行时初始化 Sentry。当 CI 中设置了 SENTRY_AUTH_TOKEN 时，源映射会自动上传。

---

详细资源：

• 代码示例请参阅 examples/ 文件夹：
  • examples/core.md - 依赖项、环境变量、next.config.ts、instrumentation
  • examples/sentry-config.md - Sentry 配置文件（客户端、服务端、边缘运行时）
  • examples/pino-logger.md - 配置带脱敏功能的 Pino 日志记录器
  • examples/axiom-integration.md - Web Vitals 和仪表板查询
  • examples/ci-cd.md - GitHub Actions 源映射上传
  • examples/health-check.md - 健康检查端点
• 决策框架和反模式请参阅 reference.md

---

<critical_requirements>

关键：使用此技能前

所有代码必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入排序、import type、命名常量）

（必须为每个环境分别创建 Axiom 数据集：development、staging、production）

（必须配置全部三个 Sentry 配置文件：sentry.client.config.ts、sentry.server.config.ts、sentry.edge.config.ts）

（必须将源映射上传添加到 CI/CD 中——Sentry 需要源映射才能显示可读的堆栈跟踪）

（必须仅将 pino-pretty 安装为 devDependency——切勿在生产环境中使用）

</critical_requirements>

---

自动检测： pino、next-axiom、@sentry/nextjs、Axiom、Sentry、可观测性设置、日志记录设置、错误跟踪设置、源映射、sentry.client.config、sentry.server.config、sentry.edge.config、withAxiom、withSentryConfig

适用场景：

• 为需要日志记录和错误跟踪的新项目进行设置
• 为尚未具备可观测性的现有项目添加可观测性
• 从其他日志记录／错误跟踪解决方案迁移到 Axiom + Sentry

不适用场景：

• 在现有代码中添加新的日志语句（这是持续使用，而非初始设置）
• 初始设置完成后配置告警、监控器或仪表板
• 使用现有可观测性工具排查生产问题

涵盖的关键模式：

• 安装依赖项（Pino、next-axiom、@sentry/nextjs、pino-pretty）
• 环境变量模板（.env.example）
• 使用 withAxiom() 和 withSentryConfig() 包装 next.config.ts
• Sentry 配置文件（客户端、服务端、边缘运行时）
• 使用 instrumentation.ts 初始化 Sentry
• 使用 GitHub Actions 上传源映射
• 支持开发／生产模式的 Pino 日志记录器
• 健康检查端点
• 初始 Axiom 仪表板设置

---

核心模式

模式 1：安装依赖

使用正确的依赖类型安装所有可观测性软件包。

# Production dependencies
npm install pino next-axiom @sentry/nextjs

# Development dependencies (pretty printing for local dev)
npm install -D pino-pretty

原因： 将 pino-pretty 作为开发依赖可避免生产构建包膨胀（约 500KB），所有核心软件包都是运行时所需的生产依赖。

如需包含优劣对比的详细代码示例，请参阅 examples/core.md。

---

模式 2：环境变量模板

创建 .env.example，记录所有必需的可观测性变量。按服务分组，使用注释说明每个值的获取方式，并为不同环境维护独立的数据集。

所需的关键变量：

• NEXT_PUBLIC_AXIOM_DATASET - 数据集名称（例如，myapp-dev、myapp-prod）
• NEXT_PUBLIC_AXIOM_TOKEN - 具有数据写入权限的 API 令牌
• NEXT_PUBLIC_SENTRY_DSN - 从项目设置中获取的 Sentry DSN
• SENTRY_AUTH_TOKEN - 用于在 CI 中上传 Source Map
• SENTRY_ORG / SENTRY_PROJECT - 组织和项目的 slug

如需包含所有变量的完整模板，请参阅 examples/core.md。

---

模式 3：使用 withAxiom 和 withSentryConfig 配置 next.config.ts

使用 withAxiom 包装 Next.js 配置以集成日志记录，然后使用 withSentryConfig 处理 Source Map。

关键配置点：

• 先用 withAxiom 包装（内部），再用 Sentry 包装外层
• silent: !process.env.CI 可在本地抑制 Source Map 上传日志
• v9+ 默认隐藏 Source Map（无需设置 hideSourceMaps）
• 使用 sourcemaps.deleteSourcemapsAfterUpload 在上传后清理文件

import { withSentryConfig } from "@sentry/nextjs";
import { withAxiom } from "next-axiom";

const nextConfig = {
  /* your config */
};

export default withSentryConfig(withAxiom(nextConfig), {
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
  authToken: process.env.SENTRY_AUTH_TOKEN,
  silent: !process.env.CI,
});

如需完整配置示例，请参阅 examples/core.md。

---

模式 4：Sentry 配置文件

为客户端、服务端和 Edge 运行时创建全部三个 Sentry 配置文件。

必需文件：

• sentry.client.config.ts - 客户端配置，包含重放集成
• sentry.server.config.ts - 服务端配置，捕获本地变量
• sentry.edge.config.ts - Edge 运行时配置，功能有限

关键注意事项：

• 为采样率使用具名常量
• 根据环境设置配置（调试模式、采样率）
• 使用 beforeSend 过滤预期错误
• v9+：已移除 hideSourceMaps 和 enableTracing，默认隐藏 Source Map

如需完整文件模板，请参阅 examples/sentry-config.md。

---

模式 5：Instrumentation 文件

创建 instrumentation.ts，以便在 Next.js 中正确初始化 Sentry。使用动态导入，为每种运行时加载相应的配置。

import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }

  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

// Next.js 15+ error handling hook
export const onRequestError = Sentry.captureRequestError;

原因： 动态导入可避免为运行时加载错误的配置；onRequestError 钩子会自动捕获 Server Component 错误（Next.js 15+）。

---

模式 6：Web Vitals 组件

在根布局中添加 <AxiomWebVitals /> 组件，自动将核心 Web Vitals（LCP、INP、CLS）报告到 Axiom。

注意： Web Vitals 仅在生产部署中发送，本地开发时不会发送。

如需实现示例，请参阅 examples/axiom-integration.md。

---

模式 7：GitHub Actions Source Map 上传

配置 CI/CD，在部署时向 Sentry 上传 Source Map。关键要求：

• 在构建环境中设置 SENTRY_AUTH_TOKEN，即可启用自动上传
• 使用 getsentry/action-release@v3 创建发布版本
• 将版本与 git SHA 关联，以便追踪发布

如需完整工作流模板，请参阅 examples/ci-cd.md。

---

模式 8：健康检查端点

添加与可观测性技术栈集成的健康检查端点：

• 浅层检查 - 为负载均衡器探测提供快速响应，并包含版本信息以便关联 Sentry 发布
• 深度检查 - 验证依赖项，并通过 Pino 记录失败，以便在 Axiom 仪表板中查看

实现示例请参见 examples/health-check.md。

---

模式 9：Pino 日志记录器设置

配置 Pino 的开发/生产模式：

• 开发环境：使用 pino-pretty 输出易读的日志
• 生产环境：使用 JSON 格式，以便汇总日志时采集
• 为每条日志设置基础上下文字段
• 对敏感字段进行脱敏

完整配置请参见 examples/pino-logger.md。

---

模式 10：Axiom 仪表板设置

设置完成后，在 Axiom 中创建初始仪表板：

• 每分钟请求量
• 错误率百分比
• 响应时间 P95
• 高频错误
• Web Vitals 指标

APL 查询示例请参见 examples/axiom-integration.md。

---

<decision_framework>

决策框架

完整决策树请参见 reference.md：

• 日志目标：各环境中的日志应发送到哪里
• 错误处理：Sentry 还是 Axiom：哪种系统负责处理哪类错误

</decision_framework>

---

<red_flags>

危险信号

完整列表请参见 reference.md。

高优先级：

• 将 Axiom 令牌或 Sentry DSN 提交到版本控制中
• 在生产环境中使用 pino-pretty
• 在 CI 中缺少源映射上传步骤
• 所有环境使用相同的 Axiom 数据集

常见错误：

• 忘记使用 withAxiom 包装 next.config.ts
• 缺少 instrumentation.ts
• 使用已移除的 Sentry 选项（hideSourceMaps、enableTracing、disableServerWebpackPlugin）
• 硬编码采样率，而不是使用具名常量

</red_flags>

---

<critical_reminders>

重要提醒

所有代码都必须遵循 CLAUDE.md 中的项目约定

（必须为每个环境分别创建 Axiom 数据集——开发、预发布、生产）

（必须配置全部三个 Sentry 配置文件——sentry.client.config.ts、sentry.server.config.ts、sentry.edge.config.ts）

（必须将源映射上传添加到 CI/CD 中——Sentry 需要源映射才能显示可读的堆栈跟踪）

（必须仅将 pino-pretty 安装为开发依赖——切勿在生产环境中使用）

未遵循这些规则将导致日志缺失、错误难以阅读以及安全漏洞。

</critical_reminders>