Node.js
ClickStack 使用 OpenTelemetry 标准来收集遥测数据(日志、指标、跟踪和异常)。跟踪通过自动仪器生成,因此不需要手动仪器来获取跟踪的价值。
本指南集成了:
- 日志
- 指标
- 跟踪
- 异常
入门
安装 HyperDX OpenTelemetry 仪器包
使用以下命令来安装 ClickStack OpenTelemetry 包。
- NPM
- Yarn
初始化 SDK
要初始化 SDK,您需要在应用程序的入口点顶部调用 init
函数。
- require
- import
这将自动捕获来自您的 Node.js 应用程序的跟踪、指标和日志。
设置日志收集
默认情况下,console.*
日志会被收集。如果您使用的是 winston
或 pino
等记录器,您需要向记录器添加一个传输,以将日志发送到 ClickStack。如果您使用其他类型的记录器,请 联系我们 或查看我们的某些平台集成(例如 Kubernetes)。
- Winston
- Pino
- console.log
如果您将 winston
作为记录器使用,您需要在记录器中添加以下传输。
如果您将 pino
作为记录器使用,您需要在记录器中添加以下传输,并指定一个 mixin
来将日志与跟踪进行关联。
默认情况下,console.*
方法开箱即用,无需额外配置。
您可以通过将 HDX_NODE_CONSOLE_CAPTURE
环境变量设置为 0 或将 consoleCapture: false
传递给 init
函数来禁用此功能。
设置错误收集
ClickStack SDK 可以自动捕获应用程序中的未捕获异常和错误,并提供完整的堆栈跟踪和代码上下文。
要启用此功能,您需要将以下代码添加到应用程序的错误处理中间件末尾,或者使用 recordException
函数手动捕获异常。
- Express
- Koa
- Manual
疑难解答
如果您遇到 SDK 的问题,可以通过将 OTEL_LOG_LEVEL
环境变量设置为 debug
来启用详细日志记录。
高级仪器配置
捕获控制台日志
默认情况下,ClickStack SDK 将捕获控制台日志。您可以通过将 HDX_NODE_CONSOLE_CAPTURE
环境变量设置为 0 来禁用它。
附加用户信息或元数据
为了轻松标记与给定属性或标识符(例如用户ID或电子邮件)相关的所有事件,您可以调用 setTraceAttributes
函数,该函数将在调用后使用声明的属性标记与当前跟踪关联的每个日志/跨度。建议在给定请求/跟踪内尽早调用此函数(例如,在 Express 中间件栈尽早)。
这是确保所有日志/跨度自动标记正确标识符以便于稍后搜索的便捷方法,而无需手动标记和传播标识符。
userId
、userEmail
、userName
和 teamName
会填充会话 UI 中的相应值,但可以省略。可以指定任何其他额外值并用于搜索事件。
确保通过将 HDX_NODE_BETA_MODE
环境变量设置为 1 或将 betaMode: true
传递给 init
函数来启用 beta 模式,以启用跟踪属性。
Google Cloud Run
如果您在 Google Cloud Run 上运行应用程序,Cloud Trace 会自动将采样标头注入到传入请求中,目前限制每个实例为每秒 0.1 个请求的跟踪。
@hyperdx/node-opentelemetry
包默认将采样率覆盖为 1.0。
要更改此行为或配置其他 OpenTelemetry 安装,您可以手动配置环境变量 OTEL_TRACES_SAMPLER=parentbased_always_on
和 OTEL_TRACES_SAMPLER_ARG=1
以实现相同的结果。
要了解更多信息,并强制跟踪特定请求,请参阅 Google Cloud Run 文档。
自动仪器库
以下库将通过 SDK 自动进行仪器(跟踪):
dns
express
graphql
hapi
http
ioredis
knex
koa
mongodb
mongoose
mysql
mysql2
net
pg
pino
redis
winston
替代安装
使用 ClickStack OpenTelemetry CLI 运行应用程序
或者,您可以使用 opentelemetry-instrument
CLI 或使用 Node.js --require
标志在不进行任何代码更改的情况下自动仪器您的应用程序。CLI 安装公开了更广泛的自动仪器库和框架。
- 使用 NPX
- 自定义入口点(例如 Nodemon、ts-node 等)
- 代码导入
OTEL_SERVICE_NAME
环境变量用于在 HyperDX 应用中标识您的服务,可以是您想要的任何名称。
启用异常捕获
要启用未捕获异常捕获,您需要将 HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE
环境变量设置为 1。
之后,自动捕获来自 Express、Koa 的异常或手动捕获异常,请按照上面 设置错误收集 部分中的说明进行操作。
自动仪器库
以下库将通过上述安装方法自动进行仪器(跟踪):