一: 安装@qnpm/qtrace-node

yarn add @qnpm/qtrace-node

or

npm install @qnpm/qtrace-node

注⚠️: 如果您还没有配置公司私有源需要先配置

npm config set registry http://npmrepo.corp.qunar.com/

注⚠️: @qnpm/qtrace-node 对应的node最低版本要求8.0.0，如果你的项目node版本低于8.0.0请安装@qnpm/qtrace-node-degradation包

二: 创建配置文件

1: 在根目录config文件夹中创建名为config.qtrace.js的文件

config/config.qtrace.js

module.exports = {
 autoTrace: true,                         // 如果开启自动探测，则trace中间件会自动劫持并收集所有路由过来的信息。（如果你只需要记录一个简单版本trace信息可以用这个）
 backup: true,                            // 是否需要备份
 memoryLimit: 95, // 95代表当前内存使用达到95%的时候不再写入trace，等内存释放到95%以下的时候会继续记录trace,默认95
 expireTime: 5000, // 用于清理过期未使用的trace上下文来释放内存，默认5000ms，如果业务本身的并发不大可调大一点，默认5000ms
 maxLogSize : 512,                        // 默认512M，超过512M自动备份
 logFile: './logs/qtracer.span.log',      // trace日志地址，qtracer.span.log文件名禁止修改，否则数据组抓取不到,logs文件夹必须跟业务的日志文件夹保持一致
 backupDir: './logs/backup'               // trace日志备份地址,logs文件夹必须跟业务的日志文件夹保持一致
}

2: 在应用中心下载用于后台拉取日志的配置文件qunar-app.properties将里面的name和token字段添加到config/config.qtrace.js中

config/qunar-app.properties

#organization=platform
#owner=[blue.yang, aweleey.li, heng.du, jingjing.geng, leix.xie]
#developer=[blue.yang, aweleey.li, heng.du, jingjing.geng, leix.xie]
#mailGroup=[pptc-fe@qunar.com]
name=qtrace_node_test
token=wjaQ/1i+sJQKQv/3Nvfk2LYTiLpn52tVJCT0A8V5sk0rxLtbAbH0bT1Ak5e/kqRGvq5GHPsmKKKiUxxjxxk1UVdW938sAw50x91gsOObZYWdsJDiQSasdgfuasfysudfSHHSHSH

添加后的配置文件

config/config.qtrace.js

module.exports = {
  name:'qtrace_node_test', // 此字段来自qunar-app.properties
  token: 'wjaQ/1i+sJQKQv/3Nvfk2LYTiLpn52tVJCT0A8V5s' ,  // 此字段来自qunar-app.properties
  autoTrace: true,                         // 如果开启自动探测，则trace中间件会自动劫持并收集所有路由过来的信息。（如果你只需要记录一个简单版本trace信息可以用这个）
  backup: true,                            // 是否需要备份
  memoryLimit: 95, // 95代表当前内存使用达到95%的时候不再写入trace，等内存释放到95%以下的时候会继续记录trace,默认95
  expireTime: 5000, // 用于清理过期未使用的trace上下文来释放内存，默认5000ms，如果业务本身的并发不大可调大一点，默认5000ms
  maxLogSize : 512,                        // 默认512M，超过512M自动备份
  logFile: './logs/qtracer.span.log',      // trace日志地址，qtracer.span.log文件名禁止修改，否则数据组抓取不到,logs文件夹必须跟业务的日志文件夹保持一致
  backupDir: './logs/backup'               // trace日志备份地址,logs文件夹必须跟业务的日志文件夹保持一致
}

注⚠️: 如果想先本地调试可以直接用这个代码，但是上线前您需要替换，否则不能正确拉取到您的trace日志

三: 接入

在app.js中所有中间件之前开启一个根 trace

  const Koa = require('koa');
  const app = new Koa();
  const router = require('koa-router')();

  const {  TraceConnect  } =  require('@qnpm/qtrace-node');

  // 1: 在所有中间件之前开启一个根 trace
  // 2: 此处会记录下基本信息后把实例化的trace存入全局作为 ctx.qtrace 存在,qtrace同时会挂载到global下，你也可以用global.qtrace来使用
  app.use(TraceConnect());

注⚠️: 如果您需要自动收集，您只需要集成以上代码就可以了

四: node对外请求

在node服务中对外发起请求需要使用经过qtrace包装的请求库 q-fetch，请求库主要是在发起请求和请求返回的时候把请求信息记录到trace日志，这样就能串起node对外的请求。

注⚠️: 第三步是拦截上游请求到node的信息记录到trace日志，第四步是记录node对外的请求。