egg-opentracing

egg-opentracing

Implementation of opentracing in Egg.js

• Integrate httpserver and httpclient span
• Customize carrier
• Customize collector

Install

$ npm i egg-opentracing --save

Usage

// {app_root}/config/plugin.js
exports.opentracing = {
  enable: true,
  package: 'egg-opentracing',
};

Configuration

see config/config.default.js for more detail.

Start a span

You can start a span by startSpan with operationName

const span = ctx.tracer.startSpan('request_egg');
await ctx.curl('https://eggjs.org');
span.finish();

Note: httpclient has been supported by default

Customize carrier

Carrier can be injected and extracted, so you can define a class for that.

// lib/rpc_carrier.js
class RPCCarrier {
  inject(spanContext) {
    return {};
  }

  extract(carrier) {
    return {
      // traceId,
      // spanId,
      // baggage,
    }
  }
}

Then configure it in config/config.default.js with a format name.

// config/config.default.js
exports.opentracing = {
  carrier: {
    RPC: require('../lib/rpc_carrier'),
  },
};

After that, you can use the format to inject or extract.

// inject
const span = ctx.tracer.startSpan('rpc');
const carrier = {};
ctx.tracer.inject(span, 'RPC', carrier);
await ctx.rpc.invoke({}, { carrier });
span.finish();

Customize collector

Collector will be triggered when span finished, you can implement it to write logs or report to server.

// lib/log_collector.js
class LogCollector {
  constructor(app) {
    this.app = app;
  }

  collect(span) {
    this.app.logger.info('%s,%s', span.traceId, span.spanId);
  }
}

Then configure it in config/config.default.js.

// config/config.default.js
exports.opentracing = {
  collector: {
    log: require('../lib/log_collector'),
  },
};

Note: zipkin collector has been implemented in egg-zipkin.

API

Tracer

Tracer extends Tracer of opentracing, you can get the instance by ctx.tracer.

Span

Span extends Span of opentracing, it's instantiated by ctx.tracer.startSpan.

• {String} name: operation name
• {String} traceId: the traceId of the span
• {String} spanId: the id of the span
• {String} parentSpanId: the id of parent span, it will be '' if there's no parent span.
• {String} getTag(key): return the value of the specified tag
• {Object} getTags(): return all tags

SpanContext

SpanContext extends SpanContext of opentracing, it's instantiated by span.context().

• {String} traceId: the traceId of the span
• {String} spanId: the id of the span
• {Void} setBaggage(key, value): set one baggage
• {String} getBaggage(key): return the value of the specified baggage
• {Void} setBaggages(baggages): set multiple baggages
• {Object} getBaggages(): return all baggages

Carrier

Carrier is a class that transform between SpanContext and carrier.

• {Object} inject(SpanContext): implement this method that transform SpanContext to carrier object.
• {Object} extract(carrier): implement this method that transform carrier object to SpanContext, extract must return traceId and spanId.

Collector

• {Void} collect(span): implement this method that report span.

Questions & Suggestions

Please open an issue here.

License

MIT