Merge pull request #236 from midwayjs/feat/#228

feat: trace interface

docs/source/en/monitor/trace.md

@@ -28,7 +28,6 @@ curl http://127.0.0.1:7002/trace?appName=my-site # my-site 是您的应用名
 It can also be viewed through GUI Dashboard, [check docs](../other/dashboard.html).
 
 
-
 ### about sampling rate
 
 Default sampling rate is:
@@ -49,7 +48,24 @@ That can be changed via global config, [docs](../base/global_config.html).
 
 ### How to add a new kind of spans
 
-TODO
+You can access all the interfaces about tracing via the single instance TraceManager object.
+
+```javascript
+const {traceManager} = require('dorapan');
+```
+Get the current available tracer object via `getCurrentTracer()`, like: 
+
+```javascript
+const tracer = traceManager.getCurrentTracer(); // If not in a trace link, will got a undefined
+const span = tracer.startSpan('custom_span');
+span.finish();
+```
+
+More please check API References:
+
+* [TraceManager](http://www.midwayjs.org/pandora/api-reference/metrics/classes/tracemanager.html)
+* [Tracer](http://www.midwayjs.org/pandora/api-reference/metrics/classes/tracer.html)
+* The Tracer object extended and implemented [OpenTracer](https://github.com/opentracing/opentracing-javascript), so please check it also.
 
 ### Principle
 

docs/source/zh-cn/monitor/trace.md

@@ -47,7 +47,25 @@ curl http://127.0.0.1:7002/trace?appName=my-site # my-site 是您的应用名
 
 ### 如何新增一个链路节点
 
-待补充
+通过获得单例 TraceManager 对象，可以实现对链路功能的全部接口访问。 
+
+```javascript
+const {traceManager} = require('dorapan');
+```
+
+可以通过 `getCurrentTracer()` 接口获得当前活跃的链路对象，通过：
+
+```javascript
+const tracer = traceManager.getCurrentTracer(); // 如果不在一个链路中，将会获得 undefined
+const span = tracer.startSpan('custom_span');
+span.finish();
+```
+
+更多请参考这两个对象的 API Reference：
+
+* [TraceManager](http://www.midwayjs.org/pandora/api-reference/metrics/classes/tracemanager.html)
+* [Tracer](http://www.midwayjs.org/pandora/api-reference/metrics/classes/tracer.html)
+* Tracer 对象继承和实现自 [OpenTracer](https://github.com/opentracing/opentracing-javascript，请同样参考一下。
 
 ### 实现原理
 

packages/pandora/src/Facade.ts

@@ -10,6 +10,7 @@ export class Facade {
       .access('env')
       .access('environment')
       .access('hub')
+      .access('traceManager')
       .method('getService')
       .method('getServiceClass')
       .method('getHub')
@@ -24,6 +25,8 @@ export class Facade {
   processName: typeof ProcessContextAccessor.prototype.processName;
   env: typeof ProcessContextAccessor.prototype.env;
   environment: typeof ProcessContextAccessor.prototype.environment;
+  traceManager: typeof ProcessContextAccessor.prototype.traceManager;
+
   getService: typeof ProcessContextAccessor.prototype.getService;
   getServiceClass: typeof ProcessContextAccessor.prototype.getServiceClass;
   getHub: typeof ProcessContextAccessor.prototype.getHub;

packages/pandora/src/application/ProcessContextAccessor.ts

@@ -6,6 +6,7 @@ import {Environment} from 'pandora-env';
 import {Service} from '../domain';
 import {Facade as HubFacade} from 'pandora-hub';
 import {DefaultObjectProxy, ObjectDescription, ConsumerExtInfo} from 'pandora-hub';
+import {TraceManager} from 'pandora-metrics';
 
 /**
  * Class ProcessContextAccessor
@@ -117,4 +118,9 @@ export class ProcessContextAccessor {
     return hub.publish(obj, objDesc);
   }
 
+
+  get traceManager(): TraceManager {
+    return TraceManager.getInstance();
+  }
+
 }

packages/pandora/src/index.ts

@@ -86,6 +86,7 @@ delegate(exports, 'facade')
   .access('env')
   .access('environment')
   .access('hub')
+  .access('traceManager')
   .method('getService')
   .method('getServiceClass')
   .method('getHub')
@@ -105,6 +106,8 @@ export declare const appDir: typeof Facade.prototype.appDir;
 export declare const processName: typeof Facade.prototype.processName;
 export declare const env: typeof Facade.prototype.env;
 export declare const environment: typeof Facade.prototype.environment;
+export declare const traceManager: typeof Facade.prototype.traceManager;
+
 export declare const getService: typeof Facade.prototype.getService;
 export declare const getServiceClass: typeof Facade.prototype.getServiceClass;
 export declare const getHub: typeof Facade.prototype.getHub;

packages/pandora/test/application/ProcessContextAccessor.test.ts

@@ -2,6 +2,7 @@ import {ProcessContextAccessor} from '../../src/application/ProcessContextAccess
 import {ProcessContext} from '../../src/application/ProcessContext';
 import {expect} from 'chai';
 import mm = require('mm');
+import {TraceManager} from 'pandora-metrics';
 
 describe('ProcessContextAccessor', function () {
 
@@ -133,4 +134,15 @@ describe('ProcessContextAccessor', function () {
 
   });
 
+  it('should get traceManager be ok', async () => {
+    const processContext = new ProcessContext(precessRepresentation);
+    const accessor = new ProcessContextAccessor(processContext);
+    const x = {};
+    mm(TraceManager, 'getInstance', () => {
+      return x;
+    });
+    expect(accessor.traceManager).to.be.equal(x);
+    mm.restore();
+  });
+
 });