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

Node.js

ClickStack 使用 OpenTelemetry 标准来采集遥测数据（日志 logs、指标 metrics、追踪 traces 和异常 exceptions）。Traces 通过自动插桩自动生成，因此无需手动插桩即可从 tracing 中获益。

本指南集成了：

  • Logs
  • Metrics
  • Traces
  • Exceptions

开始使用​

安装 HyperDX OpenTelemetry Instrumentation 包​

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

npm install @hyperdx/node-opentelemetry

初始化 SDK​

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

const HyperDX = require('@hyperdx/node-opentelemetry');

HyperDX.init({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});

这将自动从你的 Node.js 应用程序中采集跟踪、指标和日志数据。

设置日志采集​

默认情况下，会自动采集 console.* 日志。如果您使用的是 winston 或 pino 等 logger，则需要在 logger 中添加一个 transport，将日志发送到 ClickStack。 如果您使用的是其他类型的 logger，欢迎联系我们，或者根据需要使用我们的平台集成（例如 Kubernetes）。

如果您使用 winston 作为 logger，需要在 logger 中添加以下 transport。

    import winston from 'winston';
    import * as HyperDX from '@hyperdx/node-opentelemetry';

    const logger = winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      transports: [
        new winston.transports.Console(),
        HyperDX.getWinstonTransport('info', { // 发送 info 级别及以上的日志
          detectResources: true,
        }),
      ],
    });

    export default logger;

设置错误收集​

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

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

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});
const app = express();

// 在这里添加您的路由等

// 在所有路由之后添加此行，
// 但要在定义任何其他错误处理中间件之前
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

故障排除​

如果在使用 SDK 时遇到问题，可以通过将 OTEL_LOG_LEVEL 环境变量设置为 debug 来启用详细日志输出。

export OTEL_LOG_LEVEL=debug

高级埋点配置​

捕获控制台日志​

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

export HDX_NODE_CONSOLE_CAPTURE=0

附加用户信息或元数据​

若要轻松为与给定属性或标识符（例如 user id 或 email）相关的所有事件添加标签，可以调用 setTraceAttributes 函数。该函数会在调用后，将声明的属性附加到与当前 trace 关联的每一条 log/span 上。建议在给定 request/trace 的生命周期中尽可能早地调用该函数（例如在 Express middleware 栈中尽量靠前的位置）。

通过这种方式，可以方便地确保所有 logs/spans 都会自动带上正确的标识符，便于后续检索，而无需手动为每条日志打标签并自行传播这些标识符。

userId、userEmail、userName 和 teamName 会在 sessions UI 中填充相应的值，但它们是可选的。还可以指定任意其他附加字段，并使用这些字段来搜索事件。

import * as HyperDX from '@hyperdx/node-opentelemetry';

app.use((req, res, next) => {
  // 从请求中获取用户信息...

  // 将用户信息附加到当前跟踪
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

要启用跟踪属性，请确保通过将环境变量 HDX_NODE_BETA_MODE 设置为 1，或在调用 init 函数时传入 betaMode: true 来开启 beta 模式。

export HDX_NODE_BETA_MODE=1

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 后，可以使用更多已支持自动插桩的库和框架。

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

OTEL_SERVICE_NAME 环境变量用于在 HyperDX 应用中标识你的服务，可以是任意你指定的名称。

启用异常捕获​

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

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

随后，如需自动捕获来自 Express、Koa 的异常或手动捕获异常，请按照上文 设置错误收集 一节中的说明进行配置。

自动插桩的库​

通过上述安装方法，以下库将被自动插桩（用于追踪）：