在 Nest.js 中接入 highlight.io：错误监控、日志采集与分布式追踪完整实战指南

可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本篇技术指南基于 highlight.io 开源仓库中的 Nest.js 快速开始文档docs-content/getting-started/4_server/2_js/nestjs.md及其配套 QuickStart 内容展开。highlight.io 是一款开源的全栈可观测性平台统一提供错误监控Error Monitoring、会话回放Session Replay、日志Logging与分布式追踪Distributed Tracing。本文聚焦其服务端 JavaScript SDK 在 Nest.js 场景下的接入读完本文你将掌握如何安装highlight-run/nestSDK、初始化配置参数的含义、如何通过全局拦截器捕获后端异常、如何手动上报错误、如何用自定义 Logger 采集日志以及整个接入链路在源码层面的工作原理。接入前置条件在开始接入 Nest.js 之前需要先在 highlight.io 平台创建一个项目并获取你的Project ID形如YOUR_PROJECT_ID该 ID 是所有初始化配置的核心参数。仓库中提供了完整的快速开始目录结构服务端 JS 各框架的接入说明位于 docs-content/getting-started/4_server/2_jsNest.js 的 QuickStart 内容定义在 highlight.io/components/QuickstartContent/server/js/nestjs.tsx。同时仓库在 highlight.io/middleware.ts 中维护了文档路由的兼容重定向旧路径getting-started/backend-sdk/js/nestjs与getting-started/backend-logging/js/nestjs都会统一指向/docs/getting-started/server/js/nestjs因此无论从哪个入口进入看到的都是同一份 Nest.js 接入指南。安装 Highlight SDKNest.js 场景下需要安装的是 Node.js 相关的highlight-run/nest包。仓库中的jsGetSnippet辅助函数定义于 highlight.io/components/QuickstartContent/server/js/shared-snippets-monitoring.tsx会在页面上为每个 SDK slug 生成安装命令npm install --save highlight-run/nest该包是 highlight.io 为 Nest.js 框架提供的官方集成包其实现位于仓库 sdk/highlight-nest/src/index.ts内部依赖highlight-run/node作为底层 SDK 引擎。初始化 highlight.io 并注册全局拦截器安装完成后在应用的启动入口通常是main.ts中初始化 SDK并注册HighlightInterceptor全局拦截器。这是 QuickStart 中给出的完整代码import { NestFactory } from nestjs/core; import { AppModule } from ./app.module; import { HighlightInterceptor, H } from highlight-run/nest; const env { projectID: YOUR_PROJECT_ID, serviceName: my-nestjs-app, serviceVersion: git-sha, environment: production, debug: false, }; async function bootstrap() { H.init(env); const app await NestFactory.create(AppModule); app.useGlobalInterceptors(new HighlightInterceptor(env)); await app.listen(3000); } bootstrap();H.init(env)负责初始化底层 Node SDKapp.useGlobalInterceptors(new HighlightInterceptor(env))则把拦截器注册为全局中间件使所有 HTTP 请求都经过错误采集链路。需要注意HighlightInterceptor构造时如果检测到 SDK 尚未初始化会自动调用H.init(env)见 sdk/highlight-nest/src/index.ts因此即使忘记手动调用H.init拦截器也会兜底完成初始化。env 配置参数说明QuickStart 中的env对象是 SDK 的标准配置项各字段含义如下参数示例值含义projectIDYOUR_PROJECT_ID必填。highlight.io 项目 ID决定数据上报到哪个项目空间serviceNamemy-nestjs-app服务名称用于在平台上区分不同服务建议与部署单元一致serviceVersiongit-sha服务版本标识实践中可填入 Git commit SHA 或发布版本号便于定位回归environmentproduction运行环境如production、development用于环境维度过滤debugfalse是否开启 SDK 调试日志排查接入问题时置为true可观察上报细节错误捕获原理HighlightInterceptor 做了什么从源码看HighlightInterceptor实现了 NestJS 的NestInterceptor接口sdk/highlight-nest/src/index.ts其工作流程可以拆解为三步开启请求 Span在intercept方法中取出 HTTP 上下文调用NodeH.startWithHeaders(...)以${request.method} ${request.url}为名开启一个追踪 Span并把http.method、http.url写入 Span 属性同时通过api.context.bind把 OpenTelemetry 上下文绑定到后续处理器上——这正是分布式追踪得以串联请求的关键一步。捕获异常对next.handle()返回的 Observable 管道挂载catchError一旦下游处理器抛出错误就调用NodeH.consumeError(err, ...)把异常连同当前请求 Span 上报到 highlight.io然后原样throwError重新抛出不会吞掉业务异常Nest 自身的异常处理机制不受影响。结束 Span在finalize回调中调用requestSpan.end()无论请求成功还是失败Span 都会被正确关闭。因此 QuickStart 中注册的这个拦截器同时承担了错误监控与自动追踪两件事这也是其标题Use theHighlightErrorFiltermiddleware to capture backend errors的实质含义。手动上报错误拦截器只能覆盖经过 Nest 路由管道的异常。如果需要在拦截器覆盖范围之外例如定时任务、队列消费、消息处理器上报错误QuickStart 提供了手动上报方式const parsed H.parseHeaders(request.headers) H.consumeError(error, parsed?.secureSessionId, parsed?.requestId)H.parseHeaders会从请求头中解析出 highlight.io 的会话标识secureSessionId与请求标识requestId从而把后端错误关联到对应的前端会话与请求H.consumeError则负责实际写入错误事件。这样即使错误发生在拦截器之外也能保持与用户会话的上下文关联。验证错误上报是否生效接入完成后需要验证 SDK 是否真的在报告错误。QuickStart 给出了一段可以直接放入 Nest.jsAppService的验证代码import { Injectable } from nestjs/common Injectable() export class AppService { getHello(): string { console.log(hello, world!) console.warn(whoa there! , Math.random()) if (Math.random() 0.2) { // error will be caught by the HighlightErrorFilter throw new Error(a random error occurred! ${Math.random()}) } return Hello World! } }该服务以 20% 的概率抛出一个随机错误同时打印一条console.log与一条console.warn。访问对应的 API 处理器后可以前往 highlight.io 控制台的错误列表页确认错误是否出现控制台日志则会由下面的日志采集机制自动上报。记录后端日志HighlightLogger日志是服务端可观测性的另一块拼图。Nest.js 的日志接入同样复用同一份初始化代码只需注意日志场景下拦截器会额外承担日志转发职责。对应的日志 QuickStart 内容定义在 highlight.io/components/QuickstartContent/logging/js/nestjs.tsx其核心说明是使用HighlightLogger中间件把后端日志记录到 highlight.io。从源码看HighlightLogger继承自 NestJS 内置的ConsoleLogger并重写了五个日志方法sdk/highlight-nest/src/index.ts重写方法对应上报级别loginfoerrorerrorwarnwarndebugdebugverbosetrace每个方法都在调用父类输出控制台日志的同时通过NodeH.log(message, level)把日志转发到 highlight.io并做了异常兜底上报失败只输出_debug提示不影响应用正常运行。这意味着应用内使用Logger、console.log等途径产生的日志都会自动被采集无需逐个埋点。HighlightLogger还实现了OnApplicationShutdown在应用关闭时调用NodeH.flush()确保内存中的日志与错误在进程退出前被完整冲刷。分布式追踪与前端会话自动串联QuickStart 的entries中包含了verifyTraces验证步骤配合HighlightInterceptor在第 1 步开启的请求 Span后端每个 HTTP 请求都会成为一条可追踪的链路。由于H.parseHeaders可以从入站请求头还原前端会话与请求 ID前后端数据能够在追踪视图中自动关联——即前端会话回放、后端错误、日志与追踪可以围绕同一个用户请求完整串联这正是 highlight.io 全栈监控 的核心体验。关于追踪的上报与验证细节仓库还提供了独立的追踪快速开始模板见 highlight.io/components/QuickstartContent/shared-snippets-tracing.tsx。进阶使用 HighlightModule 以模块化方式接入除了手动初始化与注册全局拦截器SDK 还提供了 Nest 模块化的接入方式。HighlightModulesdk/highlight-nest/src/index.ts暴露了两个静态方法HighlightModule.forRoot(options)同步注册内部初始化 Node SDK并把HighlightLogger与HighlightInterceptor同时注册为 provider 并导出HighlightModule.forRootAsync(options)异步变体同样完成初始化与 provider 注册。两种方式都内置了幂等判断if (!NodeH.isInitialized())不会重复初始化 SDK。在AppModule的imports中引入HighlightModule.forRoot(env)即可在依赖注入体系中直接使用HighlightLogger与HighlightInterceptor更适合大型 Nest.js 工程的模块化管理。结语一次接入三面覆盖从 highlight.io/components/QuickstartContent/server/js/nestjs.tsx 可以看出Nest.js 快速开始共包含 6 个步骤前端安装、SDK 安装、注册拦截器、手动错误上报、错误验证、日志验证最终同时覆盖 Errors、Logs、Traces 三个产品能力。接入的核心就是三件事npm install highlight-run/nest安装 SDK用H.init(env)配置项目 ID 与服务元信息注册HighlightInterceptor全局拦截器错误 追踪并借助HighlightLogger或继承ConsoleLogger的日志机制自动采集日志。所有能力都有对应的源码实现可查sdk/highlight-nest/src/index.ts接入过程中若遇到问题可先将debug置为true观察 SDK 内部上报日志再结合控制台数据逐项排查。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐highlight.io 接入 Python FastAPI错误监控、日志采集与分布式追踪完整指南highlight.io 接入 Python FastAPI错误监控、日志采集与分布式追踪完整指南 本篇指南围绕 highlight.io 官方为 Pytho可观测性后端highlight.io Java SDK 后端接入指南错误监控、日志采集与分布式追踪实战highlight.io Java SDK 后端接入指南错误监控、日志采集与分布式追踪实战 本文围绕 highlight.io开源全栈可观测平台的 Jav可观测性后端在 Node.js 服务端接入 highlight.io错误监控、日志与分布式追踪完整指南在 Node.js 服务端接入 highlight.io错误监控、日志与分布式追踪完整指南 本指南以 highlight.io 官方文档 Node.js Qu可观测性后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考