#概述

NestJS Observe 是面向 NestJS 应用程序的官方自动插桩可观测性平台。安装 SDK，添加一个 API 密钥，您的应用程序就会开始把请求、后台任务、错误、日志和追踪数据流式传输到您的仪表盘——无需手动接线跨度，无需运行收集器，无需设计模式，也无需手工搭建仪表盘。

info 提示 本章介绍如何使用 @nestjs/observe SDK 对 NestJS 应用程序进行插桩，以及这种插桩能给您带来什么。如果您想了解的是仪表盘本身，请前往 observe.nestjs.com。

#它有何不同

通用的 Node.js APM 代理挂接在 HTTP 服务器和数据库驱动上，而把中间的一切留作黑盒。NestJS Observe 则围绕 Nest 自身的请求生命周期构建——控制器、守卫、拦截器、管道、解析器、队列消费者——因此遥测数据以您编写代码时使用的词汇来表达：是 OrdersService.recalculate，而不是 POST /orders。这也正是它能够按 NestJS 类和方法 展示耗时（而不仅仅是按路由）、以及未经修改的应用程序生成的追踪瀑布图读起来就像一张调用图的原因。

SDK 通过 NestFactory.create() 的 instrument 应用选项（自 @nestjs/core v11.1.4 起可用）挂接到框架上，因此在 Nest 装配它们时，它能看到每一个控制器、提供者、解析器和队列消费者——没有进程级补丁，也不需要在其余代码之前导入任何东西。

#它提供哪些功能

SDK 运行起来之后，每一档套餐——包括免费版——都能为您提供：

• 请求监控：覆盖 HTTP、GraphQL、gRPC 和 @nestjs/microservices 传输器：吞吐量、延迟（平均值与 p95）、每个操作的失败率，以及每一次执行的详情页。
• 分布式追踪：为请求运行过的每个跨度提供瀑布图，通过自有时间排名找出时间究竟花在了哪里，并在追踪 ID 传播后实现跨服务关联（参见分布式追踪）。
• 错误监控：包含堆栈跟踪、失败帧附近的源代码行，以及服务端把多次出现归组为缺陷的功能。
• 任务：队列消费者和定时任务运行（例如 BullMQ）与请求得到同等对待，另外还有队列等待时间和重试次数。
• 服务：在整个应用程序范围内，按类、按方法细分自有时间与总时间。
• 运行时性能分析：CPU、内存、事件循环延迟与利用率以及垃圾回收，从进程内部采样，并按实例进行比较。
• 版本发布：每个请求和任务都会记录服务它的版本，因此部署引入的回归会立即显现。
• 自定义指标：从您自己的代码中上报计数器、仪表和摘要。
• 用户：当您的应用程序上报用户标识符时，提供按用户的活动统计，并归纳为用户实际执行的操作。
• 复制代理提示词：一键把失败的请求、缓慢的任务或出错的追踪转换成一段自包含的编码代理提示词。

付费套餐在此基础上增加日志流式传输（与追踪关联，默认开启脱敏）、告警（阈值、异常检测、缺失检测，支持 Slack/webhook/电子邮件渠道）、问题、团队管理，以及在更高档套餐上的 SSO、带错误预算和燃烧率告警的 SLO，还有一个只读的 MCP 服务器，让兼容 MCP 的代理可以直接查询您的遥测数据（参见 MCP 服务器）。

#组织结构

NestJS Observe 把您的遥测数据组织为三个层次：

• 团队（team） 是用户的集合。每个项目恰好属于一个团队，而团队成员身份正是您一次性授予某人访问多个项目的方式。订阅按团队管理。
• 项目（project） 是一起发布的一组应用程序，通常每个产品或各环境一个（例如 storefront-production、storefront-staging）。告警、问题、SLO 和 API 密钥都以项目为作用域。
• 应用程序（application） 是单个 NestJS 服务——一个 REST API、一个工作进程、一个微服务——通过 SDK 完成插桩并向某个项目上报数据。一个项目通常包含多个应用程序（例如一个 Web API 和它背后的队列工作进程），这样您可以把它们当作一个系统整体查看，同时仍然可以向下筛选出其中任意一个。

每个项目成员拥有三种访问级别之一——读（Read）、写（Write） 或 管理员（Admin）——决定其能否查看遥测数据、创建告警规则、应用程序和 API 密钥，或管理成员与支出控制。

#订阅

在 observe.nestjs.com 注册。免费（Free） 套餐无需填写支付信息，且已包含错误监控、分布式追踪和自动插桩，因此您可以先给应用程序插桩、看到真实的追踪数据，再决定是否需要更多。

使用量以可观测性事件（Observability Events，OE） 计量——应用程序上报的每个请求、后台任务运行、错误、日志条目或追踪跨度各计一个事件。这些事件是累加而非合并的：一个运行了三个数据库跨度、写入两行日志并抛出一个错误的请求是七个事件。您的套餐决定了每月包含的事件额度、保留期限，以及解锁了哪些功能：

免费版有严格的月度上限——一旦达到，数据摄取将被拒绝，直到下一个周期。Pro 和 Scale 允许超额使用而不是硬性停止，按每增加一百万事件计费，因此繁忙的一个月并不意味着丢失遥测数据。按年计费相对月价享有折扣。有关当前价格、席位数和超额费率，请参见定价页面。

要升级套餐，请打开拥有您项目的团队的 Billing → Manage subscription。同一区域中的 Usage 页面会按项目细分，跟踪您的可观测性事件相对额度的消耗情况，并允许您设置配额通知（最多五个阈值，例如 50%、80%、100%），在使用量越过某个阈值的瞬间给您发送电子邮件。

info 提示 无需重新部署，您就可以通过按项目的支出控制来控制摄取量：保持追踪连贯性的跨度采样、每分钟速率上限，以及针对 /health* 这类已知高噪流量的丢弃过滤器。错误绝不会被这些控制采样或丢弃。您也可以从 SDK 侧完全停止生成遥测数据——参见忽略嘈杂操作。

#第一个项目

1. 创建一个项目并为它命名。
2. 向其中添加一个应用程序。应用程序只需要一个名字——它服务的路由、处理的任务以及上报的指标，都会从 SDK 发送的遥测数据中自动发现。
3. 在项目的 API Keys 页面生成一个 API 密钥。每个密钥都有一个名称（本地开发一个、CI 一个、生产环境一个）和一个可选的过期日期。密钥对（appKey 和 appSecret）只在创建时显示一次，因此请立即把它复制到您的密钥管理工具中。密钥以项目为作用域：所有遥测数据应落入该项目的应用程序都使用同一个密钥。
4. 按照 SDK 章节为您的应用程序完成插桩。应用程序开始接收流量后，遥测数据片刻之内就会出现。

warning 警告 请像对待其他任何凭据一样对待 appKey 和 appSecret：从环境变量或密钥管理器中读取它们，绝不提交到源代码管理中。您可以随时在同一页面撤销密钥——仍在使用它的应用程序将无法继续发送遥测数据。

#后续内容

• SDK——安装、三行代码的快速开始，以及所有配置选项。
• 手动插桩——自定义跨度、捕获已处理的错误、请求作用域属性和自定义指标。
• 分布式追踪——跨 HTTP、gRPC、微服务传输器和 GraphQL 传播追踪 ID。
• 仪表盘——遥测数据流动起来之后每个视图展示什么，以及告警、SLO 和问题如何构建在其之上。
• MCP 服务器——从 Claude Code、Cursor、VS Code 或您自己的代理查询遥测数据。