如何使用 NestJS Observe：开发者可观测性手册
内容提要
NestJS Observe 是官方推出的框架感知可观测性工具，能自动理解控制器、服务、队列等 NestJS 执行模型，自动生成日志、指标、追踪和性能分析，无需手动埋点。文章通过构建慢速订单 API，演示如何用 Observe 定位支付环节耗时，并对比 OpenTelemetry 的通用方案，指出框架感知可降低诊断成本，但牺牲可移植性，适合重度 NestJS 应用。
延伸解读
框架感知可观测性的核心差异
NestJS Observe 与传统方案的关键区别在于，它理解 NestJS 的执行模型，能自动识别控制器、服务、守卫、拦截器等框架概念，并据此生成遥测数据。这意味着开发者无需手动埋点，就能获得带有框架语义的追踪信息，例如从 HTTP 请求直接映射到具体的 Controller 和 Service 方法。这种上下文自动捕获降低了诊断成本，但代价是牺牲了跨语言、跨框架的可移植性。
自动与手动埋点的互补关系
Observe 的自动埋点能覆盖 HTTP、GraphQL、微服务、BullMQ 等 NestJS 执行路径，但无法理解业务逻辑中关键的自定义操作，比如复杂的折扣计算。文章建议采用自动加手动的组合：自动埋点提供执行骨架，手动埋点则为重要业务操作添加语义标签。但需避免过度埋点，应聚焦于昂贵的外部调用、关键工作流和延迟敏感的操作，否则追踪会变得臃肿而难以使用。
与 OpenTelemetry 的取舍与共存
OpenTelemetry 是厂商中立的可观测性标准，优势在于可移植性和跨语言统一架构，适合多语言技术栈。Observe 则更贴近 NestJS 生态，用开发者熟悉的框架概念表达遥测，提升 NestJS 重度用户的体验。两者并非互斥：可以用 NestJS 提供框架上下文，OpenTelemetry 负责标准化遥测和上下文传播，后端平台完成存储、可视化和告警。选择取决于组织架构和团队习惯。
评估 Observe 时的成本与数据风险
文章提醒，可观测性成本不只是软件价格，还包括基础设施、存储、工程维护和事件量。Observe 免费层每月 30 万事件，但一次请求可能产生多个 span、日志和错误，高流量下事件量增长迅速。此外，遥测数据可能包含敏感信息，不应盲目将请求头、Cookie 或令牌发送到后端。采样策略（如保留全部错误和慢请求、采样成功请求）也是控制成本和数据量的重要手段。
Q&A
NestJS Observe 是什么？它和普通的日志埋点有什么不同？
NestJS Observe 是 NestJS 官方推出的框架感知可观测性工具，能自动理解控制器、服务、队列等 NestJS 执行模型，自动生成日志、指标、追踪和性能分析，无需手动埋点。普通日志埋点需要开发者手动在代码中添加 console.log 或类似语句，随着应用增长会越来越昂贵，且无法自动生成结构化的执行树。
框架感知可观测性（framework-aware observability）是什么意思？
框架感知可观测性是指插桩工具理解框架的执行模型，而不是把应用当作通用进程。例如 NestJS 知道请求经过了中间件、守卫、拦截器、管道、控制器、提供者等概念，因此可以自动生成带有这些框架语义的遥测数据，而通用工具只能看到 HTTP 请求或函数调用。
NestJS Observe 和 OpenTelemetry 有什么区别？各自适合什么场景？
OpenTelemetry 是厂商中立的可观测性框架和工具包，提供标准化的遥测生成、收集和导出方式，优势是可移植性，适合多语言、多服务的异构架构。NestJS Observe 更偏向 NestJS 框架，自动理解 NestJS 执行模型，开发者体验更简单，但牺牲了可移植性，适合重度 NestJS 应用。两者可以结合使用：NestJS 提供框架级上下文，OpenTelemetry 提供标准化遥测和互操作性，后端负责存储、可视化、告警和分析。
NestJS Observe 能自动插桩哪些执行路径？
根据当前项目文档，NestJS Observe 支持自动插桩的执行路径包括：HTTP、GraphQL、微服务/RPC、BullMQ、定时任务。此外还提供运行时指标和性能分析能力。
如何在 NestJS 应用中配置和使用 Observe？
首先安装 @nestjs/observe，然后创建 src/observe.ts 文件，使用 createObserveModule() 导出 ObserveModule 和 ObserveInstrument。在 app.module.ts 中导入 ObserveModule.forRootAsync()，通过 ConfigService 读取 OBSERVE_APP_KEY、OBSERVE_APP_SECRET 和 OBSERVE_SERVICE_ID。最后在 main.ts 中创建应用时传入 instrument: ObserveInstrument。凭证从 Observe 仪表板获取，并像其他应用密钥一样妥善保管。
使用 NestJS Observe 时，自动插桩和手动插桩分别适用于什么情况？
自动插桩能理解框架层面的执行路径（如 HTTP、控制器、服务），但无法自动识别对业务特别重要的自定义函数。手动插桩适用于昂贵的业务操作、外部调用、关键工作流、昂贵计算、延迟敏感操作和重要业务事件，例如 checkout.calculatePrice、fraud.evaluate、payment.authorize、invoice.generate。一般模型是自动插桩提供骨架，手动插桩添加应用特定含义，但不应插桩所有函数，目标是产生有用的遥测而非最大的追踪。
NestJS Observe 的定价和遥测数据量需要注意什么？
Observe 项目目前宣传每月 30 万事件的免费层，但基于事件的定价意味着遥测数据量很重要。一个应用请求可能产生 HTTP 操作、多个 span、日志、错误等遥测，高流量下会快速增长。可观测性需要自己的容量规划，更多遥测不一定更好，因为可能增加基数、存储需求、隐私问题和费用。采样策略也很重要，例如 100% 错误、100% 慢请求、10% 成功请求。定价应始终查看官方定价页面。
在什么情况下应该认真评估 NestJS Observe？
重度 NestJS 应用是明显候选，尤其是没有现有可观测性基础设施、团队希望获得生产可见性而不想自己构建和运维整个平台时。当应用大量使用 BullMQ、GraphQL、微服务、定时任务等执行路径时更有价值。如果开发者习惯用 NestJS 概念（如 OrdersController、OrdersService）思考，遥测反映相同概念可以减少认知负担。但如果已有成熟的 OpenTelemetry 可观测性栈，或架构高度多语言，引入另一个平台可能造成不必要的重复。
