跳到主要内容
跳到主要内容

Node.js

ClickStack 使用 OpenTelemetry 标准来收集遥测数据(日志、指标、跟踪和异常)。跟踪通过自动仪器生成,因此不需要手动仪器来获取跟踪的价值。

本指南集成了:

  • 日志
  • 指标
  • 跟踪
  • 异常

入门

安装 HyperDX OpenTelemetry 仪器包

使用以下命令来安装 ClickStack OpenTelemetry 包

初始化 SDK

要初始化 SDK,您需要在应用程序的入口点顶部调用 init 函数。

这将自动捕获来自您的 Node.js 应用程序的跟踪、指标和日志。

设置日志收集

默认情况下,console.* 日志会被收集。如果您使用的是 winstonpino 等记录器,您需要向记录器添加一个传输,以将日志发送到 ClickStack。如果您使用其他类型的记录器,请 联系我们 或查看我们的某些平台集成(例如 Kubernetes)。

如果您将 winston 作为记录器使用,您需要在记录器中添加以下传输。

设置错误收集

ClickStack SDK 可以自动捕获应用程序中的未捕获异常和错误,并提供完整的堆栈跟踪和代码上下文。

要启用此功能,您需要将以下代码添加到应用程序的错误处理中间件末尾,或者使用 recordException 函数手动捕获异常。

疑难解答

如果您遇到 SDK 的问题,可以通过将 OTEL_LOG_LEVEL 环境变量设置为 debug 来启用详细日志记录。

高级仪器配置

捕获控制台日志

默认情况下,ClickStack SDK 将捕获控制台日志。您可以通过将 HDX_NODE_CONSOLE_CAPTURE 环境变量设置为 0 来禁用它。

附加用户信息或元数据

为了轻松标记与给定属性或标识符(例如用户ID或电子邮件)相关的所有事件,您可以调用 setTraceAttributes 函数,该函数将在调用后使用声明的属性标记与当前跟踪关联的每个日志/跨度。建议在给定请求/跟踪内尽早调用此函数(例如,在 Express 中间件栈尽早)。

这是确保所有日志/跨度自动标记正确标识符以便于稍后搜索的便捷方法,而无需手动标记和传播标识符。

userIduserEmailuserNameteamName 会填充会话 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_onOTEL_TRACES_SAMPLER_ARG=1 以实现相同的结果。

要了解更多信息,并强制跟踪特定请求,请参阅 Google Cloud Run 文档

自动仪器库

以下库将通过 SDK 自动进行仪器(跟踪):

替代安装

使用 ClickStack OpenTelemetry CLI 运行应用程序

或者,您可以使用 opentelemetry-instrument CLI 或使用 Node.js --require 标志在不进行任何代码更改的情况下自动仪器您的应用程序。CLI 安装公开了更广泛的自动仪器库和框架。

OTEL_SERVICE_NAME 环境变量用于在 HyperDX 应用中标识您的服务,可以是您想要的任何名称。

启用异常捕获

要启用未捕获异常捕获,您需要将 HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE 环境变量设置为 1。

之后,自动捕获来自 Express、Koa 的异常或手动捕获异常,请按照上面 设置错误收集 部分中的说明进行操作。

自动仪器库

以下库将通过上述安装方法自动进行仪器(跟踪):