Node.js 和 OpenTelemetry

此页面适用于希望使用 OpenTelemetry 收集 Node.js 应用的 Cloud Trace 数据的开发者。OpenTelemetry 是一个供应商中立的插桩框架,可用于收集跟踪记录和指标数据。如需了解如何对代码进行插桩,请参阅插桩和可观测性

  • 安装 OpenTelemetry 软件包。
  • 配置应用以将 span 导出到 Cloud Trace。
  • 配置您的平台。

如需了解版本信息,请参阅以下内容:

如需了解 OpenTelemetry 参考内容,请参阅以下内容:

有关适用于 Node.js 的 OpenTelemetry 的最新详细信息以及其他文档和示例,请参阅 OpenTelemetry

准备工作

  1. 在 Google Cloud 控制台的导航面板中,选择 API 和服务,点击启用 API 和服务,然后启用 Cloud Trace API:

    转到 Cloud Trace API 设置

  2. 如果系统显示 API 已启用,则表示此 API 已经启用。如未显示,请点击启用按钮。

安装、初始化和使用客户端

OpenTelemetry 提供以下插桩应用的方法:

  • 自动对 Node.js 应用进行插桩

    使用此方法时,您需要配置应用以包含 @opentelemetry/sdk-trace-node SDK。不过,您不必更改所使用的任何库的代码。

  • 手动跟踪

    使用此方法时,您可以修改用于收集轨迹信息的库。

以下部分显示了每种插桩的使用场景。

自动插桩

@opentelemetry/sdk-trace-node 模块会为 Node.js 应用提供自动插桩。

自动插桩可自动识别应用中的以下各项:

  • 框架,例如 Express
  • 常见协议,例如 HTTP、HTTPS 和 gRPC
  • 数据库,例如 MySQL、MongoDB、Redis 和 PostgreSQL
  • 应用中的其他库

自动插桩会提供现成可用的跟踪功能,因此您无需对所使用的任何库进行代码更改。插桩代码会自动执行以下操作:

  • 从入站请求中提取跟踪上下文标识符,以允许进行分布式跟踪(如果适用)。
  • 确保在事务遍历应用时传播当前的跟踪上下文。
  • 将跟踪上下文标识符添加到出站请求,并允许分布式跟踪继续到下一个跃点(如果适用)。
  • 创建并结束 span。

该模块会使用插件自动对您的应用进行插桩以生成 span,并且只需几行代码即可提供端到端跟踪。

手动插桩

手动跟踪模块 @opentelemetry/sdk-trace-base 会提供对插桩和 span 创建的完整控制。它不会加载 async_hooks。默认情况下,它不会使用连续本地存储或任何插桩插件。与自动插桩模块相比,手动跟踪对性能开销的影响要小一些。

示例

以下说明演示了如何为 Compute Engine 和 Google Kubernetes Engine 使用自动插桩模块。

Compute Engine

安装以下软件包:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

将以下代码添加到您的应用中,以初始化并注册导出器:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

GKE

将以下内容添加到 Dockerfile 中:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

将以下代码添加到您的应用中,以初始化并注册导出器:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

使用 Express 框架的示例应用

借助 OpenTelemetry Express Instrumentation 插桩,您可以自动收集跟踪记录数据并将其导出到所选后端,从而对分布式系统进行监测。

如需为使用 Express 框架的应用使用 OpenTelemetry,请完成以下步骤:

  1. 安装以下软件包:

    npm install --save @opentelemetry/instrumentation-http
    npm install --save @opentelemetry/instrumentation-express
    
  2. 将以下代码添加到您的应用中,以加载所有受支持的插件

    const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
    const provider = new NodeTracerProvider();
    

如需查看基本示例,请参阅 OpenTelemetry Express 示例

创建自定义 span

您可以通过创建自定义 span 来向系统创建的跟踪记录添加其他信息。

如需创建自定义 span,请将以下代码添加到源代码中:


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
provider.register();
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();
  • getTracer 会返回跟踪器的实例,其中 basic 是跟踪器或插桩库的名称。这会告诉 OpenTelemetry 由谁创建 span。

  • foo 是自定义 span 的名称。

  • invoking work 是示例事件的名称。它会演示如何使用 addEvent API。

如需查看创建自定义 span 的基本示例,请参阅 OpenTelemetry 示例

配置平台

您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

在 Google Cloud 上运行

当您的应用在 Google Cloud 上运行时,您无需向客户端库提供服务账号形式的身份验证凭据。但是,您需要确保 Google Cloud Platform 已启用 Cloud Trace API 访问权限范围

如需查看受支持的 Google Cloud 环境的列表,请参阅环境支持

对于以下配置,默认的访问权限范围设置会启用 Cloud Trace API:

  • App Engine 柔性环境
  • App Engine 标准环境

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

如果您使用自定义访问权限范围,则必须确保已启用 Cloud Trace API 访问权限范围

  • 如需了解如何使用 Google Cloud 控制台为您的环境配置访问权限范围,请参阅配置 Google Cloud 项目

  • 对于 gcloud 用户,请使用 --scopes 标志指定访问权限范围,并添加 trace.append Cloud Trace API 访问权限范围。例如,如需创建仅启用了 Cloud Trace API 的 GKE 集群,请执行以下操作:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

在本地和其他位置运行

如果您的应用在 Google Cloud 之外运行,则必须向客户端库提供服务账号形式的身份验证凭据。该服务账号必须包含 Cloud Trace Agent 角色。如需查看说明,请参阅创建服务账号

Google Cloud 客户端库使用应用默认凭据 (ADC) 查找应用的凭据。

您可以通过以下三种方式之一提供这些凭据:

  • 运行:gcloud auth application-default login

  • 将服务帐号放置在操作系统的默认路径中。 下面列出了 Windows 和 Linux 的默认路径:

    • Windows:%APPDATA%/gcloud/application_default_credentials.json

    • Linux:$HOME/.config/gcloud/application_default_credentials.json

  • GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号的路径:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

查看跟踪记录

在 Google Cloud 控制台的导航面板中,选择 Trace,然后选择 Trace 探索器

转到 Trace 探索器

问题排查

如需了解如何排查 Cloud Trace 的问题,请转到“问题排查”页面