Eaglr

Track flows through a distributed microservices architecture.

How to install

npm install --save eaglr

How to use

1. Append as middleware to server

var Eaglr = require('eaglr');
var express = require('express');

var app = express();

app.use(Eaglr());

This will (1) check for an eaglr-token header in each incoming request, and (2) generate one if no such token exists.

2. Pass on ealgr-token header to subsequent calls to other APIs

var rp = require('request-promise');

var eaglrToken = req.headers['eaglr-token'];
rp({
  method: ...,
  headers: {
    ...,
    'eaglr-token': eaglrToken
  }
})

3. Use your logger to record the eaglr token at various parts of your application

console.log(req.headers['eaglr-token'])

Two critical areas to record these are at the points of incoming and outgoing http requests.

Description

This main aim of this utility is to embed a token into the headers of requests that allows tracing of http requests through a web of microservice applications. One of the key problems of distributed architectures is that of request traceability, which this module hopes to solve via injection of a tracing token embedded into the headers of requests.

Tips

• Usage of this utility in all microservices within an ecosystem will provide the best coverage of flows.
• Always pass the eaglr-token header in downstream calls.
• Log the incoming req.headers in all microservices to capture the eaglr token. This includes the start of each flow, after the eaglr-token has been created.
• Include a datetime stamp with all logs that is synced between microservices - to ensure better trace accuracy.

Options

Eaglr is also able to accept options (optional) on initialization:

app.use(Eaglr({
  header: ..., // tracing header instead of the default 'eaglr-token'
  prefix: ...  // token prefix instead of the default 'eaglr'
}))

TODO

• Add microservice step number (number of microservices traversed before the current microservice)
• Custom request promise encapsulation that automatically adds the eaglr-token
• Add appName to options, which complements step number and allows identification of the service that the flow enters
• req.eaglr as a convenience accessor