{"id":21893784,"url":"https://github.com/goodwaygroup/lib-hapi-good-tracer","last_synced_at":"2025-04-15T15:22:52.655Z","repository":{"id":42754538,"uuid":"277590469","full_name":"GoodwayGroup/lib-hapi-good-tracer","owner":"GoodwayGroup","description":"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.","archived":false,"fork":false,"pushed_at":"2024-04-05T23:37:08.000Z","size":398,"stargazers_count":2,"open_issues_count":16,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-14T23:00:31.283Z","etag":null,"topics":["debugging","hapi","hapi-plugin","hapijs","logging","metrics","tracer","tracing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoodwayGroup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-06T16:14:36.000Z","updated_at":"2024-04-30T23:39:28.699Z","dependencies_parsed_at":"2024-04-30T23:39:19.910Z","dependency_job_id":"b419ae71-a734-4579-a4f2-03c20f20422d","html_url":"https://github.com/GoodwayGroup/lib-hapi-good-tracer","commit_stats":{"total_commits":108,"total_committers":7,"mean_commits":"15.428571428571429","dds":0.4444444444444444,"last_synced_commit":"5d46d16ac18fc469a299e8b5dbc33504706a84e8"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodwayGroup%2Flib-hapi-good-tracer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodwayGroup%2Flib-hapi-good-tracer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodwayGroup%2Flib-hapi-good-tracer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoodwayGroup%2Flib-hapi-good-tracer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoodwayGroup","download_url":"https://codeload.github.com/GoodwayGroup/lib-hapi-good-tracer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226918888,"owners_count":17703183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugging","hapi","hapi-plugin","hapijs","logging","metrics","tracer","tracing"],"created_at":"2024-11-28T13:16:55.037Z","updated_at":"2024-11-28T13:16:55.860Z","avatar_url":"https://github.com/GoodwayGroup.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lib-hapi-good-tracer\n\n[![CircleCI](https://circleci.com/gh/GoodwayGroup/lib-hapi-good-tracer.svg?style=svg)](https://circleci.com/gh/GoodwayGroup/lib-hapi-good-tracer)\n[![Coverage Status](https://coveralls.io/repos/github/GoodwayGroup/lib-hapi-good-tracer/badge.svg?branch=master)](https://coveralls.io/github/GoodwayGroup/lib-hapi-good-tracer?branch=master)\n[![npm downloads](https://img.shields.io/npm/dm/@goodwaygroup/lib-hapi-good-tracer.svg?style=flat-square)](http://npm-stat.com/charts.html?package=@goodwaygroup/lib-hapi-good-tracer)\n[![install size](https://packagephobia.com/badge?p=@goodwaygroup/lib-hapi-good-tracer)](https://packagephobia.com/result?p=@goodwaygroup/lib-hapi-good-tracer)\n\n## Usage\n\nThis 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.\n\n```json\n{\n  \"tracer\": {\n    \"uuid\": \"STRING\",\n    \"depth\": \"INTEGER\"\n  }\n}\n```\n\nThe `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.\n\n\u003e NOTE: This module uses the [`debug`](https://www.npmjs.com/package/debug) logging tool. Use `DEBUG=hapi:plugins:good-tracer` to view debug logging.\n\n```\n$ npm install -S @goodwaygroup/lib-hapi-good-tracer\n```\n\nIn your `index.js` for the Hapi server, register the plugin:\n\n```js\nawait server.register({\n    plugin: require('@goodwaygroup/lib-hapi-good-tracer'),\n    options: {\n        traceUUIDHeader: 'x-custom-trace-uuid', // optional defaults to 'x-gg-trace-uuid'\n        traceDepthHeader: 'x-custom-trace-depth', // optional defaults to 'x-gg-trace-depth'\n        enableStatsRoute: true, // optional defaults to false\n        baseRoute: '/debug', // optional defaults to ''\n        cache: {\n            stdTTL: 60 // optional defaults to 3600 seconds\n        },\n        axios: {\n            main: { // defaults to {}\n                headers: {\n                    common: {\n                        'user-agent': 'service-yolo'\n                    }\n                }\n            }\n        }\n    }\n});\n\n// add stream to Good log reporters\nconst logReporters = {\n    console: [\n        server.plugins.goodTracer.GoodSourceTracer, // Stream Transform that will inject the tracer object\n        {\n            module: 'good-squeeze',\n            name: 'Squeeze',\n            args: [{\n                response: { exclude: 'healthcheck' },\n                log: '*',\n                request: '*',\n                error: '*',\n                ops: '*'\n            }]\n        }, {\n            module: 'good-squeeze',\n            name: 'SafeJson'\n        }, 'stdout']\n};\n\nawait server.register({\n    plugin: Good,\n    options: {\n        reporters: logReporters\n    }\n});\n```\n\n## axios Client Route Usage\n\nPassing `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.\n\n```js\nawait server.register({\n    plugin: require('@goodwaygroup/lib-hapi-good-tracer'),\n    options: {\n        axios: {\n            main: {}\n        }\n    }\n});\n\nconst routes = [{\n    method: 'GET',\n    path: '/proxy/google',\n    config: {\n        tags: ['proxy'],\n    },\n    handler: async (request) =\u003e {\n        const { axios } = request.plugins.goodTracer;\n        return axios.main.get('https://google.com')\n    }\n}];\n\nexports.routes = server =\u003e server.route(routes);\n```\n\nAnd with Route level configuration\n\n```js\nconst routes = [{\n    method: 'GET',\n    path: '/proxy/google',\n    config: {\n        tags: ['proxy'],\n        plugins: {\n            goodTracer: {\n                axios: {\n                    inroute: {}\n                }\n            }\n        }\n    },\n    handler: async (request) =\u003e {\n        const { axios } = request.plugins.goodTracer;\n        return axios.inroute.get('https://google.com')\n    }\n}];\n\nexports.routes = server =\u003e server.route(routes);\n```\n\n## Request Chain Hierarchy\n\nConsider The following request chain:\n\n[![](https://mermaid.ink/img/eyJjb2RlIjoiZ3JhcGggTFJcblx0QVtTZXJ2aWNlIEFdIC0tPiB8UmVxdWVzdCAxIGRlcHRoIDB8IEJbU2VydmljZSBCXVxuXHRCIC0tPiB8UmVxdWVzdCAxIGRlcHRoIDF8IENbU2VydmljZSBDXVxuICBCIC0tPiB8UmVxdWVzdCAyIGRlcHRoIDF8IENcbiAgQSAtLT4gfFJlcXVlc3QgMiBkZXB0aCAwfCBDIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggTFJcblx0QVtTZXJ2aWNlIEFdIC0tPiB8UmVxdWVzdCAxIGRlcHRoIDB8IEJbU2VydmljZSBCXVxuXHRCIC0tPiB8UmVxdWVzdCAxIGRlcHRoIDF8IENbU2VydmljZSBDXVxuICBCIC0tPiB8UmVxdWVzdCAyIGRlcHRoIDF8IENcbiAgQSAtLT4gfFJlcXVlc3QgMiBkZXB0aCAwfCBDIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0)\n\nThe `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.\n\n## In-Memory Cache\n\nThis plugin uses an in-memory cache that is used to pass the `tracer` information between the server, request and logger.\n\nThere is a global TTL per object that is reset on each `get` of the object.\n\nIf an object is stale for the length of the TTL, it will be culled.\n\nThere is a max number of keys that can be active at any time to help with memory concerns.\n\nThe `postResponseCleanup` option is on by default. This will delete the cached data associated with the request on a delay (default of `1000 ms`).  \n\nSee [node-cache](https://github.com/node-cache/node-cache) for available settings.\n\n## Configuration Options\n\n\u003e When passing a configuration option, it will overwrite the defaults.\n\n- `traceUUIDHeader`: defaults to `x-gg-trace-uuid`. The header that is used for the Trace ID\n- `traceDepthHeader`: defaults to `x-gg-trace-depth`. The header that is used for the Depth ID\n- `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).\n- `baseRoute`: defaults to `''`. Prepends to the `/good-tracer/stats` route.\n    - Example: `baseRoute = /serivce-awesome` results in `/serivce-awesome/good-tracer/stats`\n- `postResponseCleanup: (Boolean | Object)`: defaults to `true`. If set to anything, the feature is enabled. \n    - `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.\n- `axios`: Configured axios instances provided to each request\n    - `[key: string]: (Boolean | Object)`: if given, defaults to `{}`. Pass in any valid `axios` config options.\n- `cache`: internal memory cache settings. See [node-cache configuration](https://github.com/node-cache/node-cache#options)\n    - `stdTTL`: default `3600` seconds (1 hour)\n    - `checkperiod`: default `60` seconds\n    - `maxKeys`: default `-1` (no limit)\n    - `useClones`: default `false`\n    - `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`\n\n## Route Configuration Options\n\n\u003e Route level plugin configuration overwrites the options passed to the plugin.\n\n- `axios`: Configured axios instances provided to each request\n    - `[key: string]: (Boolean | Object)`: if given, defaults to `{}`. Pass in any valid `axios` config options.\n\n## Running Tests\n\nTo run tests, just run the following:\n\n```\nnpm test\n```\n\nAll commits are tested on [CircleCI](https://circleci.com/gh/GoodwayGroup/workflows/lib-hapi-good-tracer)\n\n## Linting\n\nTo run `eslint`:\n\n```\nnpm run lint\n```\n\nTo auto-resolve:\n\n```\nnpm run lint:fix\n```\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n## Versioning\n\nWe 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).\n\nTo initiate a version change:\n\n```\nnpm version minor\n```\n\n## Authors\n\n* **Derek Smith** - *Initial work* - [@clok](https://github.com/clok)\n\nSee also the list of [contributors](https://github.com/GoodwayGroup/lib-hapi-good-tracer/contributors) who participated in this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details\n\n## Acknowledgments\n\n## Sponsors\n\n[![goodwaygroup][goodwaygroup]](https://goodwaygroup.com)\n\n[goodwaygroup]: https://s3.amazonaws.com/gw-crs-assets/goodwaygroup/logos/ggLogo_sm.png \"Goodway Group\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodwaygroup%2Flib-hapi-good-tracer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoodwaygroup%2Flib-hapi-good-tracer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodwaygroup%2Flib-hapi-good-tracer/lists"}