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

Node.js

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

本指南集成了：

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

入门​

安装 HyperDX OpenTelemetry 仪器包​

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

初始化 SDK​

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

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

设置日志收集​

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

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

设置错误收集​

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

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

疑难解答​

如果您遇到 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 自动进行仪器（跟踪）：

替代安装​

使用 ClickStack OpenTelemetry CLI 运行应用程序​

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

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

启用异常捕获​

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

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

自动仪器库​

以下库将通过上述安装方法自动进行仪器（跟踪）：