帮酷LOGO
  • 显示原文与译文双语对照的内容
文章标签:堆栈  STA  Agent  追踪  TRAC  
Experimental Node.js support for Google Cloud Trace

  • 源代码名称:cloud-trace-nodejs
  • 源代码网址:http://www.github.com/GoogleCloudPlatform/cloud-trace-nodejs
  • cloud-trace-nodejs源代码文档
  • cloud-trace-nodejs源代码下载
  • Git URL:
    git://www.github.com/GoogleCloudPlatform/cloud-trace-nodejs.git
  • Git Clone代码到本地:
    git clone http://www.github.com/GoogleCloudPlatform/cloud-trace-nodejs
  • Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/GoogleCloudPlatform/cloud-trace-nodejs
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
  • Node.js Stackdriver跟踪

    Greenkeeper badge

    NPM VersionBuild StatusTest CoverageDependency StatusdevDependency StatusKnown Vulnerabilities

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

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

    Stackdriver Trace Overview

    先决条件

    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> 跟踪> 跟踪列表中:

    Trace List

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

    Trace View

    跟踪的内容

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

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

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

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

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

    高级跟踪配置

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

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

    跟踪批处理和采样

    可以使用 flushDelaySecondsbufferSize选项在发布之前对跟踪范围的聚合进行配置。 请求完成后,记录为每个传入请求的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我们期望能够跟踪本机异步/等待功能。

    更改

    许可证



    文章标签:STA  TRAC  堆栈  Agent  追踪  

    Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备05059198号-3  |  如果智培  |  酷兔英语