https://github.com/goodwaygroup/lib-hapi-good-tracer
Hapi plugin to inject tracer UUID and Depth ID into request (either from Headers or generated) and provide Good log reporter stream to append tracer data to log lines.
https://github.com/goodwaygroup/lib-hapi-good-tracer
debugging hapi hapi-plugin hapijs logging metrics tracer tracing
Last synced: 6 months ago
JSON representation
Hapi plugin to inject tracer UUID and Depth ID into request (either from Headers or generated) and provide Good log reporter stream to append tracer data to log lines.
- Host: GitHub
- URL: https://github.com/goodwaygroup/lib-hapi-good-tracer
- Owner: GoodwayGroup
- License: mit
- Created: 2020-07-06T16:14:36.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-05T23:37:08.000Z (over 1 year ago)
- Last Synced: 2024-04-14T23:00:31.283Z (over 1 year ago)
- Topics: debugging, hapi, hapi-plugin, hapijs, logging, metrics, tracer, tracing
- Language: JavaScript
- Homepage:
- Size: 389 KB
- Stars: 2
- Watchers: 8
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# lib-hapi-good-tracer
[](https://circleci.com/gh/GoodwayGroup/lib-hapi-good-tracer)
[](https://coveralls.io/github/GoodwayGroup/lib-hapi-good-tracer?branch=master)
[](http://npm-stat.com/charts.html?package=@goodwaygroup/lib-hapi-good-tracer)
[](https://packagephobia.com/result?p=@goodwaygroup/lib-hapi-good-tracer)
## Usage
This plugin will read, generate and track a tracer header on `request`s that is then injected into the `Good` log stream via an injected `tracer` object.
```json
{
"tracer": {
"uuid": "STRING",
"depth": "INTEGER"
}
}
```
The `depth` value provides insight into the hierarchy chain of requests. Combining the `uuid` + `depth` + `timestamp` of a request will provide a mapping to the request chain.
> NOTE: This module uses the [`debug`](https://www.npmjs.com/package/debug) logging tool. Use `DEBUG=hapi:plugins:good-tracer` to view debug logging.
```
$ npm install -S @goodwaygroup/lib-hapi-good-tracer
```
In your `index.js` for the Hapi server, register the plugin:
```js
await server.register({
plugin: require('@goodwaygroup/lib-hapi-good-tracer'),
options: {
traceUUIDHeader: 'x-custom-trace-uuid', // optional defaults to 'x-gg-trace-uuid'
traceDepthHeader: 'x-custom-trace-depth', // optional defaults to 'x-gg-trace-depth'
enableStatsRoute: true, // optional defaults to false
baseRoute: '/debug', // optional defaults to ''
cache: {
stdTTL: 60 // optional defaults to 3600 seconds
},
axios: {
main: { // defaults to {}
headers: {
common: {
'user-agent': 'service-yolo'
}
}
}
}
}
});
// add stream to Good log reporters
const logReporters = {
console: [
server.plugins.goodTracer.GoodSourceTracer, // Stream Transform that will inject the tracer object
{
module: 'good-squeeze',
name: 'Squeeze',
args: [{
response: { exclude: 'healthcheck' },
log: '*',
request: '*',
error: '*',
ops: '*'
}]
}, {
module: 'good-squeeze',
name: 'SafeJson'
}, 'stdout']
};
await server.register({
plugin: Good,
options: {
reporters: logReporters
}
});
```
## axios Client Route Usage
Passing `axios` plugin or route configuration will create Axios instances on the `request`. Use these instances to have the trace headers injected. This will allow for chained request tracing.
```js
await server.register({
plugin: require('@goodwaygroup/lib-hapi-good-tracer'),
options: {
axios: {
main: {}
}
}
});
const routes = [{
method: 'GET',
path: '/proxy/google',
config: {
tags: ['proxy'],
},
handler: async (request) => {
const { axios } = request.plugins.goodTracer;
return axios.main.get('https://google.com')
}
}];
exports.routes = server => server.route(routes);
```
And with Route level configuration
```js
const routes = [{
method: 'GET',
path: '/proxy/google',
config: {
tags: ['proxy'],
plugins: {
goodTracer: {
axios: {
inroute: {}
}
}
}
},
handler: async (request) => {
const { axios } = request.plugins.goodTracer;
return axios.inroute.get('https://google.com')
}
}];
exports.routes = server => server.route(routes);
```
## Request Chain Hierarchy
Consider The following request chain:
[](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggTFJcblx0QVtTZXJ2aWNlIEFdIC0tPiB8UmVxdWVzdCAxIGRlcHRoIDB8IEJbU2VydmljZSBCXVxuXHRCIC0tPiB8UmVxdWVzdCAxIGRlcHRoIDF8IENbU2VydmljZSBDXVxuICBCIC0tPiB8UmVxdWVzdCAyIGRlcHRoIDF8IENcbiAgQSAtLT4gfFJlcXVlc3QgMiBkZXB0aCAwfCBDIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0)
The `depth` value provides insight into the hierarchy chain of requests. Combining the `uuid` + `depth` + `timestamp` of a request will provide a mapping to the request chain.
## In-Memory Cache
This plugin uses an in-memory cache that is used to pass the `tracer` information between the server, request and logger.
There is a global TTL per object that is reset on each `get` of the object.
If an object is stale for the length of the TTL, it will be culled.
There is a max number of keys that can be active at any time to help with memory concerns.
The `postResponseCleanup` option is on by default. This will delete the cached data associated with the request on a delay (default of `1000 ms`).
See [node-cache](https://github.com/node-cache/node-cache) for available settings.
## Configuration Options
> When passing a configuration option, it will overwrite the defaults.
- `traceUUIDHeader`: defaults to `x-gg-trace-uuid`. The header that is used for the Trace ID
- `traceDepthHeader`: defaults to `x-gg-trace-depth`. The header that is used for the Depth ID
- `enableStatsRoute`: defaults to `false`. Publish a route to `/good-tracer/stats` that exposes the current metrics for [`node-cache` statistics](https://github.com/node-cache/node-cache#statistics-stats).
- `baseRoute`: defaults to `''`. Prepends to the `/good-tracer/stats` route.
- Example: `baseRoute = /serivce-awesome` results in `/serivce-awesome/good-tracer/stats`
- `postResponseCleanup: (Boolean | Object)`: defaults to `true`. If set to anything, the feature is enabled.
- `delay: Number`: defaults to `1` second. The amount of time to wait after reponse to delete a key from the cache. You can pass decimal values for sub-second times.
- `axios`: Configured axios instances provided to each request
- `[key: string]: (Boolean | Object)`: if given, defaults to `{}`. Pass in any valid `axios` config options.
- `cache`: internal memory cache settings. See [node-cache configuration](https://github.com/node-cache/node-cache#options)
- `stdTTL`: default `3600` seconds (1 hour)
- `checkperiod`: default `60` seconds
- `maxKeys`: default `-1` (no limit)
- `useClones`: default `false`
- `extendTTLOnGet`: This feature will reset the TTL to the global TTL when a successful `get` occurs. This will extend the life of an item in the cache as a result. default `true`
## Route Configuration Options
> Route level plugin configuration overwrites the options passed to the plugin.
- `axios`: Configured axios instances provided to each request
- `[key: string]: (Boolean | Object)`: if given, defaults to `{}`. Pass in any valid `axios` config options.
## Running Tests
To run tests, just run the following:
```
npm test
```
All commits are tested on [CircleCI](https://circleci.com/gh/GoodwayGroup/workflows/lib-hapi-good-tracer)
## Linting
To run `eslint`:
```
npm run lint
```
To auto-resolve:
```
npm run lint:fix
```
## Contributing
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
## Versioning
We use milestones and `npm` version to bump versions. We also employ [git-chglog](https://github.com/git-chglog/git-chglog) to manage the [CHANGELOG.md](CHANGELOG.md). For the versions available, see the [tags on this repository](https://github.com/GoodwayGroup/lib-hapi-good-tracer/tags).
To initiate a version change:
```
npm version minor
```
## Authors
* **Derek Smith** - *Initial work* - [@clok](https://github.com/clok)
See also the list of [contributors](https://github.com/GoodwayGroup/lib-hapi-good-tracer/contributors) who participated in this project.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
## Acknowledgments
## Sponsors
[![goodwaygroup][goodwaygroup]](https://goodwaygroup.com)
[goodwaygroup]: https://s3.amazonaws.com/gw-crs-assets/goodwaygroup/logos/ggLogo_sm.png "Goodway Group"