cloud-trace-nodejs, Stackdriver跟踪的node.js 代理

测试版。这是Stackdriver跟踪代理的测试版版本。 这些库可能以向后不兼容的方式更改，不受任何SLA或者否决策略的影响。

这里 MODULE 为 node.js 应用程序提供Stackdriver跟踪支持。 Stackdriver Trace是Google云平台的一个特性，它从你的应用程序收集延迟数据，并在 Google控制台实时显示。

先决条件

• 你的应用程序需要使用 node.js 版本 4.0或者更高版本。
• 你将需要一个项目在 Google Developers Console 项目。 应用程序可以在任何位置运行，但跟踪数据与特定项目关联。
• 为你的项目启用跟踪API插件。

带 async/await的跟踪

默认情况下，不支持使用跟踪代理跟踪使用 untranspiled async/await的应用程序。

版本 2.2 + 附带支持 async/await的实验实现( 使用 node 8 async_hooks API ) 。 要启用这里实现，请在环境变量 GCLOUD_TRACE_NEW_CONTEXT 设置的环境中运行你的应用程序：

# Requires Node 8+$ GCLOUD_TRACE_NEW_CONTEXT=1 npm start

我们正积极寻找关于这个新实现的反馈。 如果遇到意外或者不需要的行为，请提交一个问题。

有关更多信息，请参见本节中的 。

安装

使用 npm 安装或者添加到你的 package.json 。

# Install through npm while saving to the local 'package.json'npm install --save @google-cloud/trace-agent

设置GCLOUD_PROJECT环境变量。 你可以在中找到项目 ID，也可以通过运行命令来查找项目 ID 。 你可以确保在启动时将该环境变量放在 package.json 中的启动脚本中，从而设置该环境变量：

"scripts": {
 "start": "GCLOUD_PROJECT=<YOUR_PROJECT_ID> node server.js",
},

包括并启动库插件，作为应用程序插件的第一个操作：

var agent =require('@google-cloud/trace-agent').start();

如果在启动命令中使用 --require，请确保跟踪代理是 --required 。

• 在本地运行应用程序，或者在使用 Google的机器上，请确保使用默认的凭据登录：

gcloud beta auth application-default login

如果你在Google云平台之外运行，请参见在其他地方运行 。

配置

有关可能配置选项的列表，请参见默认配置 。 可以通过对象参数将这些选项传递给上面显示的启动命令的代理：

require('@google-cloud/trace-agent').start({samplingRate:500});

或者，你可以通过配置文件提供配置。 如果你想在 命令行 上使用 --require 加载 MODULE 而不是编辑主脚本，那么这可能很有用。 你可以从复制缺省配置文件并修改它以满足你的需要。 GCLOUD_TRACE_CONFIG 环境变量应该指向你的配置文件。

export GCLOUD_TRACE_CONFIG=./path/to/your/trace/configuration.js

在Google云平台上运行

有三种不同的服务可以在Google云平台中托管 node.js 应用程序。

Google App Engine 灵活环境

如果你使用的是 Google App Engine 灵活环境，则无需执行任何额外的配置。

Google计算引擎

对于计算引擎实例，你需要显式地启用 https://www.googleapis.com/auth/trace.append 每个实例的访问范围。 通过Google云平台控制台创建新实例时，你可以在标识和API访问下执行以下操作： 使用Compute默认服务 account，为每个 API 访问范围选择 access，确保的Stackdriver跟踪访问设置为 Write Write 。

为了启用现有的GCE实例，你可以按照在其他地方运行的服务帐户的说明进行操作。

Google容器引擎

计算引擎一样，需要创建容器引擎节点， https://www.googleapis.com/auth/trace.append 作用域，在创建群集期间可以配置：

• 如果群集正在使用 gcloud CLI创建，则使用 --scopes 命令( 可以用逗号分隔多个作用域( ) 。) 将作用域传递给命令：

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

• 如果群集正在通过云控制台UI创建，请确保将"stackdriver跟踪"项目访问设置为"只写入"( 这是默认值) 。

另外，也可以按照在其他地方运行的服务帐户的指示进行操作。 建议你将服务帐户凭据存储为 Kubernetes密钥。

在其他地方运行

如果应用程序在Google云平台之外( 如本地。在其他云提供商或者其他云提供商) 之外运行，你仍然可以使用Stackdriver跟踪。

启动跟踪代理时，你需要指定项目 ID 。

GCLOUD_PROJECT=particular-future-12345 node myapp.js

你需要向你的应用程序提供服务帐户凭据。 推荐方法是通过应用程序缺省凭证。

创建一个新的JSON服务帐户密钥。

将密钥复制到应用程序可以访问的位置。 一定不要公开公开密钥。

将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为密钥的完整路径。 跟踪代理程序将自动查找这里环境变量。

当你在使用 gcloud 命令行 工具插件的开发机器或者测试环境中运行你的应用程序时，你可以使用gcloud beta auth application-default login 你已经有足够的凭据，并且不需要服务帐户密钥。

或者，你可以将 keyFilename 或者 credentials 配置字段设置为密钥文件的完整路径或者内容。 设置这两个字段之一将覆盖 GOOGLE_APPLICATION_CREDENTIALS 设置或者使用 gcloud 登录。 ( 请参见默认配置插件以获得更详细

查看你的跟踪

运行应用程序并开始向应用程序发送一些请求。 在大约 30秒左右，你应该会看到跟踪数据收集在控制台中的 STACKDRIVER> 跟踪> 跟踪列表中：

这是显示应用程序接收到的传入请求抽样的跟踪列表。 你可以单击一个URI来深入到细节。 这将显示应用程序所做的rpc及其相关的延迟：

跟踪的内容

跟踪代理可以自动跟踪以下网页框架：

• express ( 版本 4 )
• gRPC * 服务器( 版本 1 )
• hapi ( 8 - 16 )
• koa ( 版本 1 )
• restify ( 版本 3 - 6 )

代理还将自动跟踪以下类型的rpc:

• 通过 http 和 https 核心模块的出站HTTP请求
• gRPC * 客户端( 版本 1 )
• mongodb核心插件( 版)
• Mongoose ( 版本 4 )
• Redis ( 版本 0.12 - 2 )
• MySQL ( 版本 ^2.9 )

*Note: gRPC ( 版本 1.1和更高版本)的最新版本放弃了对 node.js <4.0的支持。 我们不支持在不支持的Node.js. 版本上跟踪 gRPC

可以使用跟踪 API 跟踪应用程序中的其他进程。

我们正在努力扩展我们可以自动跟踪的框架和服务的类型。 我们还感兴趣听到你对它的他框架或者版本的反馈，你希望看到支持的内容。 这将帮助我们优先考虑支持的。 如果需要对特定框架或者RPC的支持，请将 Bug 或者 +1文件归档到现有的Bug 。

高级跟踪配置

可以通过将配置对象传递给代理 start 方法来配置跟踪代理。 这里配置选项接受默认配置文件中的所有值。

notes的一个配置选项是 enhancedDatabaseReporting 。 将这个选项设置为 true 将导致redis和MongoDB的数据库操作记录查询摘要和结果，作为报告的跟踪范围的标签。

跟踪批处理和采样

可以使用 flushDelaySeconds 和 bufferSize选项在发布之前对跟踪范围的聚合进行配置。 请求完成后，记录为每个传入请求的span将放入缓冲区中。 当从 bufferSize 请求中的跨度排队或者者 flushDelaySeconds 从上次发布之后，第一次发布时，跨区将发布到 UI 。

跟踪配置另外公开了 samplingRate 选项，它设置每秒捕获的跟踪请求数的上限。 某些Google云环境可能会覆盖这里采样策略。

跟踪附加模块

除了列出的模块 ，跟踪代理可以配置为通过使用插件跟踪附加的模块。 要加载附加插件，请在代理的配置中指定它：

require('@google-cloud/trace-agent').start({
 plugins: {
 // You may use a package name or absolute path to the file.'my-module':'@google-cloud/trace-agent-plugin-my-module',
 'another-module':path.join(__dirname, 'path/to/my-custom-plugins/plugin-another-module.js')
 }
 });

这个插件列表将与插件加载程序加载的插件列表合并。 每个插件只加载加载的MODULE ；换句话说，没有用于列出未使用模块插件的计算开销。

要为 MODULE 创建插件，请参见插件开发人员指南。

自定义跟踪 API

定制跟踪API可以用于向跟踪中添加自定义范围。 span 是跟踪中的特定工作单元，如RPC请求。 span可以嵌套；最外层的span 称为 root，即使没有嵌套的子元素。 典型的root span与传入请求相对应，而子范围通常与传出请求相对应，或者与响应传入请求时触发的其他工作相对应。

对于我们为它的提供插件插件的web框架，只要收到传入请求，就自动启动 root span 。 如果你想在这些框架之外记录 span，任何跟踪的代码都必须在你自己创建的root span 中运行。

访问 API

调用 start 函数将返回 TraceApi的实例，该实例提供用于跟踪的接口：

var traceApi =require('@google-cloud/trace-agent').start();

它还可以通过在其他地方对 get的后续调用来检索：

// after start() is calledvar traceApi =require('@google-cloud/trace-agent').get();

即使禁用了代理，TraceApi 对象也保证由这两个调用返回。

这里有一个关于 TraceApi 对象的完整的概述，这里是。

：自动跟踪工作如何工作？

跟踪代理自动修补已知模块，插入对启动。标签和结束span的调用，以测量 rpc ( 例如 mysql，redis，等等 ) 和传入请求的延迟。 由于每个RPC通常代表传入请求，我们必须确保该关联正确反映在 span 数据中。 为了为跟踪哪个RPC属于哪个RPC提供统一的通用方法，我们依赖于 continuation-local-storage 来跟踪跨异步边界的。

这种方法依赖于异步监听器( ) 来保护异步边界上的延续，在大多数情况下。 但是，它确实有一些限制，可以阻止我们正确地传播跟踪上下文：

• 可以使用JavaScript代码自己的回调函数排队- 有效地合并异步执行上下文。 例如，可以以编写一个http请求缓冲库来排队请求，然后在一个快照中执行它们。 在这种情况下，当所有回调激发时，它们将在刷新队列而不是添加回调的上下文中执行。 这个问题叫做池问题或者用户空间排队问题，这是JavaScript的基本限制。 如果应用程序使用这样的代码，则会注意到来自多个请求的rpc显示在单个跟踪中。 在这种情况下，我们尝试通过monkey修补解决问题，或者通过与库作者一起修复代码来正确传播上下文。 然而，查找有问题的代码并不总是那么简单。
• 在目前的异步监听程序中，不可能跟踪ES7异步/等待函数中的异步转换( 在 node 0 + 中可用) 。 如果应用程序使用untranspiled异步函数，我们将不会正确跟踪 rpc 。 we 异步侦听器支持new异步/等待功能once我们期望能够跟踪本机异步/等待功能。

更改

• 请参见 CONTRIBUTING.md

许可证

• 请参见许可协议。