{"id":20419446,"url":"https://github.com/risingstack/trace-nodejs","last_synced_at":"2025-04-12T22:29:34.268Z","repository":{"id":28706069,"uuid":"32226594","full_name":"RisingStack/trace-nodejs","owner":"RisingStack","description":"Trace is a visualised distributed tracing platform designed for microservices.","archived":false,"fork":false,"pushed_at":"2018-11-21T12:31:06.000Z","size":1023,"stargazers_count":471,"open_issues_count":4,"forks_count":90,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-04T01:39:42.935Z","etag":null,"topics":["debugging","distributed-transactions","microservices","monitoring","nodejs","performance","profiling"],"latest_commit_sha":null,"homepage":"https://trace.risingstack.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"talos/nyc-geoclient","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RisingStack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-14T18:42:30.000Z","updated_at":"2024-09-18T08:50:30.000Z","dependencies_parsed_at":"2022-07-24T16:01:58.661Z","dependency_job_id":null,"html_url":"https://github.com/RisingStack/trace-nodejs","commit_stats":null,"previous_names":[],"tags_count":175,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RisingStack%2Ftrace-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RisingStack%2Ftrace-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RisingStack%2Ftrace-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RisingStack%2Ftrace-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RisingStack","download_url":"https://codeload.github.com/RisingStack/trace-nodejs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248639477,"owners_count":21137848,"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","distributed-transactions","microservices","monitoring","nodejs","performance","profiling"],"created_at":"2024-11-15T06:37:00.158Z","updated_at":"2025-04-12T22:29:34.244Z","avatar_url":"https://github.com/RisingStack.png","language":"JavaScript","readme":"![Trace logo](https://s3-eu-west-1.amazonaws.com/risingstack-resources/trace_by_risingstack.png)\n\n[![Build status](https://img.shields.io/circleci/project/github/RisingStack/trace-nodejs.svg)](https://circleci.com/gh/RisingStack/trace-nodejs)\n[![npm version](https://img.shields.io/npm/v/@risingstack/trace.svg)](https://www.npmjs.com/package/@risingstack/trace)\n[![Website](https://img.shields.io/website-up-down-green-red/https/trace.risingstack.com.svg)](https://trace.risingstack.com)\n[![Slack Status](https://trace-slack.risingstack.com/badge.svg)](https://trace-slack.risingstack.com)\n[![Twitter URL](https://img.shields.io/twitter/url/https/trace.risingstack.com.svg?style=social)](https://twitter.com/TraceAPM)\n***\n[App](https://trace.risingstack.com/app) | [Documentation](https://trace-docs.risingstack.com/) | [Status page](https://trace-status.risingstack.com/) | [Case study](https://blog.risingstack.com/case-study-node-js-memory-leak-in-ghost/)\n***\n\n## ⚠️ Trace-Nodejs is discontinued ⚠️ The client is not longer being developed and the backend has been shut down. \n\n## ⚠️ Breaking change\n\nWith version 3.x.x we have dropped support for Node v0.10. This means that\nfuture releases under this major version might contain code changes that are\nincompatible with Node.js v0.10 to an extent of crashing your application.\nPlease consider updating to a newer runtime, especially that the\n[maintenance of v0.10 has already ended](node-lts). See our compatibility table\nbelow.\n\nAlso, since 3.1.0 we switched to a different API backend for collecting traces\nwhich is incompatible with the old one. The old endpoint is still supported, but\nwe would like it to be phased out eventually. Please update your agents to\n3.1.0 or newer.\n\n## Installation and usage\n\nAs Trace uses scoped packages, be sure to use npm version greater than 2.7.0.\n\n```\nnpm install --save @risingstack/trace\n```\n\n\u003e ⚠️ \n\n\u003eTrace depends on a couple of native addons. We host precompiled\nbinaries of these for Linux and Darwin 64-bit platforms at https://oss.risingstack.com. \nThe installer will attempt to download these dependencies, so it should be allowed \nthrough your firewall, or else the download will fail and the installer will fall back\nto building from source. This also happens if there isn't a precompiled binary for your platform. Note that compiling native addons requires native toolchain.\n\nAfter you installed Trace as a dependency, you just require it at the beginning of your main file.\n```javascript\nvar trace = require('@risingstack/trace');\n```\n\n### Configuration\n\nYou can specify the configuration two ways. Configuration options can be set via environment variables or using a config module. We look for a config module named `trace.config.js` at your current working directory by default, which can be overridden with the `TRACE_CONFIG_PATH` environment variable. Having a config module is optional, but some options may be set only with it. In order to use our service, you need to specify an api key and and a service name at minimum. The corresponding environment variables are: `TRACE_API_KEY` and `TRACE_SERVICE_NAME`.\n\nAn example for how to start your app with environment variables:\n\n```\nnode TRACE_SERVICE_NAME=MyApp TRACE_API_KEY=1 index.js\n```\n\nAn example with a custom config file using the Trace servers:\n\n```\nnode TRACE_CONFIG_PATH=/path/to/my/config.js index.js\n```\n\nor simply\n\n\n```\nnode index.js\n```\n\nif it's in the current working directory.\n\n```javascript\n/**\n* Your Trace configuration file at /path/to/my/config.js\n*/\n\nmodule.exports = {\n  serviceName: 'your-awesome-app',\n  apiKey: 'KEEP_ME_SECRET',\n  ignoreHeaders: {\n    'user-agent': ['007']\n  },\n  ignorePaths: [\n    '/healthcheck'\n  ],\n  ignoreStatusCodes: [\n    401,\n    404\n  ],\n  ignoreOutgoingHosts: [\n    'google.com'\n  ],\n  disableInstrumentations: [\n    'mongodb'\n  ],\n  proxy: 'http://168.63.76.32:3128',\n  keepQueryParams: true\n}\n```\n\nFor the complete set of configuration options, visit the [docs](https://trace-docs.risingstack.com/docs/advanced-usage#section-available-options).\n\n\n\u003e ⚠️ \n\n\u003eIf you are running your app with NODE_ENV=test, Trace won't start\n\n## API\n\n### trace.report(name, object)\n\nThis method can be use to report additional data to the Trace servers which later on helps with debugging.\n\n```javascript\ntrace.report('name', {\n  userId: 10\n});\n```\n\nThrows an error if first parameter is not a String.\nThrows an error if second parameter is not an Object.\n\n### trace.reportError(name, error)\n\nThis method can be used to send errors to the Trace servers.\n\n```javascript\ntrace.reportError('mysql_error', new Error('connection refused'));\n```\n\nThrows an error if first parameter is not a String.\n\n### trace.getTransactionId()\n\nThis method can be use to get the current transactionId. It can be useful if you want to integrate trace with your\ncurrent logging systems.\n\n```javascript\nvar transactionId = trace.getTransactionId();\n```\n\n### trace.recordMetric(name, value)\n\nThis method can be used to record custom metrics values.\n\n```javascript\ntrace.recordMetric('user/imageUpload', 6)\n```\n\nThe name must have the following format: `\u003cCategory\u003e/\u003cName\u003e`\nThe value must be a number.\n\n### trace.incrementMetric(name, [amount])\n\nThis method can be used to record increment-only type of metrics.\n\n```javascript\ntrace.incrementMetric('user/signup')\n```\n\nThe name must have the following format: `\u003cCategory\u003e/\u003cName\u003e`\n\n### trace.stop([cb])\n\nThis method gracefully stops trace.\n\n```javascript\ntrace.stop(cb)\n```\nAccepts a node-style callback to be called when trace stopped.\n\nNote: There is no way to restart trace after calling this method. You should end your process after calling this\nmethod.\n\n## Troubleshooting\n\n### Debug logs\nIf you have problems using Trace, e.g it doesn't seem to report anything you can\nturn on logging. We use the lightweight\n[debug](https://github.com/visionmedia/debug). If you are not familiar with it\nyet, please read its documentation to learn how it works.\n\n\n#### Quickstart\nTo turn it only for Trace start your app with the `DEBUG`\nenvironment variable set to `risingstack/trace*`.\n\n```\nDEBUG=risingstack/trace* node my_app.js\n```\n\n#### Configure logging\n\nTo make it possible to filter severities and components in Trace we use\nsubnamespaces. The namespace will start with `trace/risingstack` then a `:` then\na mandatory severity specifier,\n- `error`,\n- `warn` or\n- `info`.\n\nThen come zero or more namespaces led by colons. The namespaces are\nhierarchically organized according to components inside of Trace.\n\nCurrently these namespaces (and their subnamespaces) are used:\n\n- `config`\n- `instrumentation`\n- `agent`\n- `agent:tracer`\n- `agent:metrics`\n- `agent:profiler`\n- `agent:security`\n- `api`\n\nAs they can have subnamespaces, always append an `*` to them to get all\nmessages.\n\nExamples:\n\n- get all error messages: `DEBUG=risingstack/trace:error*`\n\n- get all messages from agents: `DEBUG=risingstack/trace:*:agent*`\n\n- get all error messages and all messages from agents: `DEBUG=risingstack/trace:error*,risingstack/trace:*:agent*`\n\n\n## Compatibility with Node versions\n\n* node v0.12\n* node v4\n* node v5\n* node v6\n* node v7\n\n## Migrating from previous versions\n\n### Versions below 2.x\n\nThe `trace.config.js` file changed, and has the following format:\n\n```\nmodule.exports = {\n  serviceName: 'your-awesome-app',\n  apiKey: 'KEEP_ME_SECRET'\n}\n```\n\nAlso, from `2.x` you can specify these values using only environment variables: `TRACE_SERVICE_NAME` and `TRACE_API_KEY`.\n\nCustom reporters are no longer supported in trace 2.x*\n\n### Versions below 3.x\n\nWe dropped support for Node v0.10. [Update your runtime](node) to a more recent version to continue using Trace.\n\n[node]: https://nodejs.org/en/\n[node-lts]: https://github.com/nodejs/LTS#lts-schedule\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisingstack%2Ftrace-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frisingstack%2Ftrace-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisingstack%2Ftrace-nodejs/lists"}