git://www.github.com/GoogleCloudPlatform/cloud-trace-nodejs.git
git clone http://www.github.com/GoogleCloudPlatform/cloud-trace-nodejs
$ svn co --depth empty http://www.github.com/GoogleCloudPlatform/cloud-trace-nodejs
Checked out revision 1.
$ cd repo
$ svn up trunk
测试版。这是Stackdriver跟踪代理的测试版版本。 这些库可能以向后不兼容的方式更改,不受任何SLA或者否决策略的影响。
这里 MODULE 为 node.js 应用程序提供Stackdriver跟踪支持。 Stackdriver Trace是Google云平台的一个特性,它从你的应用程序收集延迟数据,并在 Google控制台实时显示。
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 。
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云平台中托管 node.js 应用程序。
如果你使用的是 Google App Engine 灵活环境,则无需执行任何额外的配置。
对于计算引擎实例,你需要显式地启用 https://www.googleapis.com/auth/trace.append
每个实例的访问范围。 通过Google云平台控制台创建新实例时,你可以在标识和API访问下执行以下操作: 使用Compute默认服务 account,为每个 API 访问范围选择 access,确保的Stackdriver跟踪访问设置为 Write Write 。
为了启用现有的GCE实例,你可以按照在其他地方运行的服务帐户的说明进行操作。
计算引擎一样,需要创建容器引擎节点, 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
你需要向你的应用程序提供服务帐户凭据。 推荐方法是通过应用程序缺省凭证。
将密钥复制到应用程序可以访问的位置。 一定不要公开公开密钥。
将环境变量 GOOGLE_APPLICATION_CREDENTIALS
设置为密钥的完整路径。 跟踪代理程序将自动查找这里环境变量。
当你在使用 gcloud
命令行 工具插件的开发机器或者测试环境中运行你的应用程序时,你可以使用gcloud beta auth application-default login
你已经有足够的凭据,并且不需要服务帐户密钥。
或者,你可以将 keyFilename
或者 credentials
配置字段设置为密钥文件的完整路径或者内容。 设置这两个字段之一将覆盖 GOOGLE_APPLICATION_CREDENTIALS
设置或者使用 gcloud
登录。 ( 请参见默认配置插件以获得更详细
运行应用程序并开始向应用程序发送一些请求。 在大约 30秒左右,你应该会看到跟踪数据收集在控制台中的 STACKDRIVER> 跟踪> 跟踪列表中:
这是显示应用程序接收到的传入请求抽样的跟踪列表。 你可以单击一个URI来深入到细节。 这将显示应用程序所做的rpc及其相关的延迟:
跟踪代理可以自动跟踪以下网页框架:
代理还将自动跟踪以下类型的rpc:
http
和 https
核心模块的出站HTTP请求*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可以用于向跟踪中添加自定义范围。 span 是跟踪中的特定工作单元,如RPC请求。 span可以嵌套;最外层的span 称为 root,即使没有嵌套的子元素。 典型的root span与传入请求相对应,而子范围通常与传出请求相对应,或者与响应传入请求时触发的其他工作相对应。
对于我们为它的提供插件插件的web框架,只要收到传入请求,就自动启动 root span 。 如果你想在这些框架之外记录 span,任何跟踪的代码都必须在你自己创建的root span 中运行。
调用 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 来跟踪跨异步边界的。
这种方法依赖于异步监听器( ) 来保护异步边界上的延续,在大多数情况下。 但是,它确实有一些限制,可以阻止我们正确地传播跟踪上下文: