{"_id":"56a1f77642dfda0d0004628b","sync_unique":"","title":"Getting started","project":"56a1f77442dfda0d00046285","api":{"results":{"codes":[]},"settings":"","url":"","auth":"required","params":[]},"isReference":false,"link_external":false,"next":{"description":"","pages":[]},"slug":"getting-started","version":"56a1f77542dfda0d00046288","__v":47,"createdAt":"2016-01-22T09:33:42.742Z","hidden":false,"link_url":"","updates":[],"user":"56a1f7423845200d0066d71b","category":"56a3e78a94ec0a0d00b39fed","excerpt":"Monitoring your application and micro-services infrastructure is easy! Follow these 5 simple steps.","githubsync":"","order":0,"parentDoc":null,"type":"basic","body":"## 1. Make sure you meet all requirements\n\n- You are running Node.js v0.12 or later with npm:::at:::2.7 or greater\n- https://trace-collector-api.risingstack.com is allowed or proxied through your firewall.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"With 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  \"title\": \"Make sure you install a recent version\"\n}\n[/block]\n## 2. Register an infrastructure and get your API Key\n\n1. Visit the [registration page](https://trace.risingstack.com/app/#/register).\n2. The app will propose you to create your first infrastructure. For info on what an infrastructure is and best practices on creating one [click here](how-to-name-your-infrastructure-and-services).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"API key\",\n  \"body\": \"You can find your unique api key under the **Settings** page > **Integration status ** tab .\"\n}\n[/block]\n## 3. Install the Trace collector\n\nInstall the Trace collector as a dependency of your Node.js app using the following command:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"npm install @risingstack/trace --save\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nImport Trace in your application. Best if it's included before anything else, as it instruments your other dependencies. Instrumentations for dependencies required before Trace will not work properly.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// index.js\\n\\nrequire([email protected]/trace') // trace should be on top\\n\\n// your application code\\n\\nvar express = require('express') \\nvar app = express()\\n\\n// so on ...\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## 4. Run your app\n\nIn order to start collecting, you should provide your *service name* and the *API key* of the Trace infrastructure with which you wish to associate it.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"As the service name serves as an identifier, be sure yo use different names for each service.\",\n  \"title\": \"Unique service names\"\n}\n[/block]\nThese can be specified with environment variables when you start your app:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"TRACE_SERVICE_NAME\",\n    \"h-0\": \"Key Name\",\n    \"h-1\": \"Value\",\n    \"0-1\": \"Your service name\",\n    \"1-0\": \"TRACE_API_KEY\",\n    \"1-1\": \"The infrastructure API Key\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"TRACE_SERVICE_NAME=MyService TRACE_API_KEY=apiKey node index.js\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You can also specify these (and other configuration) in a configuration file. Check  [Advanced usage: Configuring from file](doc:advanced-usage#section-configuring-from-file) to learn how to configure Trace using a config file and more options.\",\n  \"title\": \"Does not fancy using environment variables?\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Tip: Infrastructure and service naming\",\n  \"body\": \"You can always rename your infrastructure.\\nFor the best practices check out our [How to name your infrastructure and services](https://trace-docs.risingstack.com/docs/how-to-name-your-infrastructure-and-services) documentation.\"\n}\n[/block]\nCongratulations! You're done. If the API key is valid your application will send data to our servers.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Receiving the data will take a couple of minutes after you deployed your application with the Trace collector.\\n\\nVisit the [integration status](https://trace.risingstack.com/app/#/integration/status) page to validate your integration.\",\n  \"title\": \"Receiving data\"\n}\n[/block]\n## 5. Profit!\n\nCheck out your [service topology](https://trace-app.risingstack.com/#/topology).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/dd12ac7-integration-success-1.png\",\n        \"integration-success-1.png\",\n        2560,\n        1156,\n        \"#2f5267\"\n      ],\n      \"caption\": \"Successfully integrated service\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"In this case please check out our [Troubleshooting](doc:troubleshooting) guide.\\nIf you feel that you need more help, feel free to ask our Team via our in-app messenger.\",\n  \"title\": \"What can I do if I don't see my data in Trace after 5 minutes\"\n}\n[/block]\nAfter generating some traffic to your application you will see how your service is communication with databases other services and external API(s) as well.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8d06d2e-integration-success-2.png\",\n        \"integration-success-2.png\",\n        2560,\n        1148,\n        \"#2b4d61\"\n      ],\n      \"caption\": \"Successfully integrated service with traffic\"\n    }\n  ]\n}\n[/block]\nInfrastructures with multiple services and databases looks like this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/49fd110-topology.png\",\n        \"topology.png\",\n        3360,\n        1704,\n        \"#2a4b6a\"\n      ],\n      \"caption\": \"Infrastructure with multiple services, API calls and databases\"\n    }\n  ]\n}\n[/block]\n## Next steps\n\nTo get the most out of Trace by RisingStack, integrate all of your services and see how your applications communicating with each other or check out [Trace view](doc:trace-view) to investigate distributed transactions in your product.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"It's a best practice to integrate your Trace infrastructure with multiple services to see your data at one place. Trace is also able to visualize the communication between your applications and provide distributed debugging and stack traces.\",\n  \"title\": \"Multiple applications and microservices\"\n}\n[/block]\nTo read more about Trace features check out the \"Features\" section in our documentation.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Setup deployment hooks\",\n  \"body\": \"[Deployment hook](/docs/deployment-hook) enable you to compare revisions of your applications. With them you can see if a revision slowed down significantly or started to leak memory.\"\n}\n[/block]\n## Use cases\n\nTrace provides different tools to investigate and solve issues in your application. Check out our tutorials to see how you can boost up your daily work with Trace by RisingStack.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Investigate slow Node.js apps\",\n  \"body\": \"Check out our [Investigate slow Node.js apps](/docs/investigate-slow-nodejs-apps) tutorial to learn more about how to use solve production issues with Trace by RisingStack.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Fix crashing Node.js apps\",\n  \"body\": \"Check out our [Fix crashing Node.js apps](/docs/fix-crashing-nodejs-applications-with-trace) tutorial to learn more about how to use solve production issues with Trace by RisingStack.\"\n}\n[/block]","childrenPages":[]}

Getting started

Monitoring your application and micro-services infrastructure is easy! Follow these 5 simple steps.

## 1. Make sure you meet all requirements - You are running Node.js v0.12 or later with [email protected] or greater - https://trace-collector-api.risingstack.com is allowed or proxied through your firewall. [block:callout] { "type": "warning", "body": "With 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.", "title": "Make sure you install a recent version" } [/block] ## 2. Register an infrastructure and get your API Key 1. Visit the [registration page](https://trace.risingstack.com/app/#/register). 2. The app will propose you to create your first infrastructure. For info on what an infrastructure is and best practices on creating one [click here](how-to-name-your-infrastructure-and-services). [block:callout] { "type": "info", "title": "API key", "body": "You can find your unique api key under the **Settings** page > **Integration status ** tab ." } [/block] ## 3. Install the Trace collector Install the Trace collector as a dependency of your Node.js app using the following command: [block:code] { "codes": [ { "code": "npm install @risingstack/trace --save", "language": "shell" } ] } [/block] Import Trace in your application. Best if it's included before anything else, as it instruments your other dependencies. Instrumentations for dependencies required before Trace will not work properly. [block:code] { "codes": [ { "code": "// index.js\n\nrequire([email protected]/trace') // trace should be on top\n\n// your application code\n\nvar express = require('express') \nvar app = express()\n\n// so on ...", "language": "javascript" } ] } [/block] ## 4. Run your app In order to start collecting, you should provide your *service name* and the *API key* of the Trace infrastructure with which you wish to associate it. [block:callout] { "type": "warning", "body": "As the service name serves as an identifier, be sure yo use different names for each service.", "title": "Unique service names" } [/block] These can be specified with environment variables when you start your app: [block:parameters] { "data": { "0-0": "TRACE_SERVICE_NAME", "h-0": "Key Name", "h-1": "Value", "0-1": "Your service name", "1-0": "TRACE_API_KEY", "1-1": "The infrastructure API Key" }, "cols": 2, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "TRACE_SERVICE_NAME=MyService TRACE_API_KEY=apiKey node index.js", "language": "shell" } ] } [/block] [block:callout] { "type": "info", "body": "You can also specify these (and other configuration) in a configuration file. Check [Advanced usage: Configuring from file](doc:advanced-usage#section-configuring-from-file) to learn how to configure Trace using a config file and more options.", "title": "Does not fancy using environment variables?" } [/block] [block:callout] { "type": "success", "title": "Tip: Infrastructure and service naming", "body": "You can always rename your infrastructure.\nFor the best practices check out our [How to name your infrastructure and services](https://trace-docs.risingstack.com/docs/how-to-name-your-infrastructure-and-services) documentation." } [/block] Congratulations! You're done. If the API key is valid your application will send data to our servers. [block:callout] { "type": "info", "body": "Receiving the data will take a couple of minutes after you deployed your application with the Trace collector.\n\nVisit the [integration status](https://trace.risingstack.com/app/#/integration/status) page to validate your integration.", "title": "Receiving data" } [/block] ## 5. Profit! Check out your [service topology](https://trace-app.risingstack.com/#/topology). [block:image] { "images": [ { "image": [ "https://files.readme.io/dd12ac7-integration-success-1.png", "integration-success-1.png", 2560, 1156, "#2f5267" ], "caption": "Successfully integrated service" } ] } [/block] [block:callout] { "type": "danger", "body": "In this case please check out our [Troubleshooting](doc:troubleshooting) guide.\nIf you feel that you need more help, feel free to ask our Team via our in-app messenger.", "title": "What can I do if I don't see my data in Trace after 5 minutes" } [/block] After generating some traffic to your application you will see how your service is communication with databases other services and external API(s) as well. [block:image] { "images": [ { "image": [ "https://files.readme.io/8d06d2e-integration-success-2.png", "integration-success-2.png", 2560, 1148, "#2b4d61" ], "caption": "Successfully integrated service with traffic" } ] } [/block] Infrastructures with multiple services and databases looks like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/49fd110-topology.png", "topology.png", 3360, 1704, "#2a4b6a" ], "caption": "Infrastructure with multiple services, API calls and databases" } ] } [/block] ## Next steps To get the most out of Trace by RisingStack, integrate all of your services and see how your applications communicating with each other or check out [Trace view](doc:trace-view) to investigate distributed transactions in your product. [block:callout] { "type": "success", "body": "It's a best practice to integrate your Trace infrastructure with multiple services to see your data at one place. Trace is also able to visualize the communication between your applications and provide distributed debugging and stack traces.", "title": "Multiple applications and microservices" } [/block] To read more about Trace features check out the "Features" section in our documentation. [block:callout] { "type": "success", "title": "Setup deployment hooks", "body": "[Deployment hook](/docs/deployment-hook) enable you to compare revisions of your applications. With them you can see if a revision slowed down significantly or started to leak memory." } [/block] ## Use cases Trace provides different tools to investigate and solve issues in your application. Check out our tutorials to see how you can boost up your daily work with Trace by RisingStack. [block:callout] { "type": "success", "title": "Investigate slow Node.js apps", "body": "Check out our [Investigate slow Node.js apps](/docs/investigate-slow-nodejs-apps) tutorial to learn more about how to use solve production issues with Trace by RisingStack." } [/block] [block:callout] { "type": "success", "title": "Fix crashing Node.js apps", "body": "Check out our [Fix crashing Node.js apps](/docs/fix-crashing-nodejs-applications-with-trace) tutorial to learn more about how to use solve production issues with Trace by RisingStack." } [/block]