将 OpenTelemetry 与 Node.js 搭配使用

您可以使用 OpenTelemetry 为 Node.js 应用启用 Cloud Trace。OpenTelemetry 是一组用于收集兼容多个后端的跟踪记录数据和指标数据的插桩库。有关适用于 Node.js 的 OpenTelemetry 的最新详情以及其他文档和示例,请转到 https://opentelemetry.io/

安装和配置

要收集跟踪记录,您需要执行以下操作:

  • 安装 OpenTelemetry 客户端库。
  • 导入 OpenTelemetry 跟踪记录软件包。
  • 配置 OpenTelemetry,将 span 导出到 Cloud Trace。
  • 启用 Cloud Trace API 访问权限范围

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

OpenTelemetry 提供了三种对应用进行插桩处理的方法:

  • 自动对 Node.js 应用进行插桩
  • 手动跟踪
  • 对 Web 应用进行自动插桩

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

自动插桩

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

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

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

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

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

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

手动插桩

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

对 Web 应用进行自动插桩

@opentelemetry/web 模块会为 Web 应用提供自动插桩和跟踪。它会收集用户端性能数据(包括延迟时间和分布式跟踪记录),从而为您提供诊断前端问题和监控整体应用状态所需的信息。

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

Compute Engine

安装以下软件包:

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

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

const opentelemetry = require('@opentelemetry/api');
const {NodeTracerProvider} = require('@opentelemetry/node');
const {SimpleSpanProcessor} = require('@opentelemetry/tracing');
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 send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

GKE

将以下内容添加到 Dockerfile 中:

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

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

const opentelemetry = require('@opentelemetry/api');
const {NodeTracerProvider} = require('@opentelemetry/node');
const {SimpleSpanProcessor} = require('@opentelemetry/tracing');
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 send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

使用 Express 框架的示例应用

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

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

  1. 安装以下软件包:

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

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

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

创建自定义 span

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

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


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
opentelemetry.trace.setGlobalTracerProvider(provider);
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 访问权限范围

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

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

  • Google Kubernetes Engine (GKE)

  • Compute Engine

如果您使用自定义访问权限范围,则必须确保已启用 Cloud Trace API 访问权限范围。对于 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) 查找应用的凭据。您可以通过设置 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"

查看跟踪记录

部署后,您可以在 Cloud Console 跟踪记录查看器中查看跟踪记录。

转到“跟踪记录查看器”页面

问题排查

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