This add-on is operated by RisingStack
Debugger and monitoring solution for your Node.js apps and microservices
Trace by RisingStack Node.js APM
Last updated 01 October 2016
Table of Contents
Trace from RisingStack is a microservice monitoring and debugging tool that empowers developers to capture all the essential metrics required to successfully operate microservice-oriented applications.
Features included: anomaly detection, distributed transaction tracking, and process monitoring for your services.
Trace is currently available for Node.js.
Provisioning the Trace add-on
Add Trace add-on to your existing application
Add via Dashboard
You can add Trace add-on under the Dashboard -> my-app -> Resources.
On the next step, you can choose the plan that fits the best for your need.
Add via CLI
Trace can be attached to a Heroku application via the CLI:
A list of all plans available can be found here.
$ heroku addons:create trace -----> Adding trace to sharp-mountain-4005... done, v18 (free)
Once Trace has been added the
TRACE_API_KEY environment variable will be available in the app configuration and will meet the minimum requirements to use Trace service. This can be confirmed using the
heroku config:get command.
$ heroku config:get TRACE_API_KEY <YOUR API KEY>
Trace needs a service/application name to attach to your running processes. For that, you have to set the
TRACE_SERVICE_NAME environment variable (config).
Setup with Dashboard
You can also set
TRACE_SERVICE_NAME environment variable (config) with the Heroku Dashboard.
Dashboard -> my-app -> Settings
Setup with CLI
$ heroku config:set TRACE_SERVICE_NAME=my-frontend-api
After installing Trace the application should be configured to fully integrate with the add-on.
Service and infrastructure naming
You can always rename your infrastructure. For the best practices check out our How to name your infrastructure and services documentation.
After provisioning the add-on, please do not replicate the config vars for your local development environment. For more information, see the Trace for Heroku article.
Using with Node.js
Ensure that all prerequisites are met
- Have npm version 2.7 or greater installed. To update simply use
npm install npm -g
Be sure to use npm version greater than 2.7.0. - as Trace uses scoped packages. If you can’t update to firstname.lastname@example.org for whatever reason, you can still install Trace using
npm i risingstack/trace-nodejs.
Install Trace agent to your Heroku app
- Install the Trace collector as a dependency of your Node.js application using the following command:
$ npm install @risingstack/trace --save
- Import Trace in the main script of your application. It should be the first module you require:
// index.js require('@risingstack/trace') // trace should be on top // your application code var express = require('express') var app = express() // so on ...
- Deploy your application with the
heroku-cli, run the following code:
git add --all git commit -m 'Install Trace collector agent' git push heroku master
- Congratulations! That’s all, now you can start using Trace.
- Go to your Heroku dashboard, select the app that has the Trace add-on
- From the installed add-ons, click Trace
- Heroku will open Trace’s website and you can start to monitor your application
Generate some data If you use Trace for the very first time, please don’t forget to generate some traffic on your service and give us some minutes to be able to collect the first traces.
New in Trace? Check out our tutorial about how you can investigate a slow Node.js application with Trace By RisingStack.
What can I do if I don’t see my data in Trace after 5 minutes In this case please check out our Troubleshooting guide. If you feel that you need more help, feel free to ask our Team via our in-app messenger.
Add a new application to your existing Trace add-on
It’s a best practice to integrate your existing Trace Heroku add-on with multiple applications to see your infrastructure at one place. Trace is also able to visualize the communication between your applications and provide distributed debugging and stack traces.
The Trace Heroku add-on is sharable. All you need to do is share the Trace add-on, and set the
TRACE_SERVICE_NAME for the new application as well.
Adding Trace as a shared add-on via UI
With Heroku Dashboard you can easily attach your existing Trace add-on to you multiple applications yo reach the full power of our monitoring tool.
On the next screen, you can select the app that you would like to add to your Trace By RisingStack infrastructure.
TRACE_SERVICE_NAMElike in the previous section
- Install Trace agent like in the previous section
Adding Trace as a shared add-on via CLI
heroku addons:create trace --name <the-name-of-your-trace-addon> -a <application-name>
heroku addons:attach <the-name-of-your-trace-addon> -a <the-name-of-the-app-you-attach-to>
Read more about Heroku add-on management: https://devcenter.heroku.com/articles/managing-add-ons
For more information on the features available within the Trace dashboard please see the docs at http://trace-docs.risingstack.com/.
The Trace service can be accessed via the CLI:
$ heroku addons:open trace Opening trace for sharp-mountain-4005
or by visiting the Heroku Dashboard and selecting the application in question. Select Trace from the Add-ons menu.
If you encounter any issue, please check the Trace documentation for additional help.
Migrating between plans
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
heroku addons:upgrade command to migrate to a new plan.
$ heroku addons:upgrade trace:newplan -----> Upgrading trace:newplan to sharp-mountain-4005... done, v18 ($49/mo) Your plan has been updated to: trace:newplan
Removing the add-on
Trace can be removed via the CLI.
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy trace -----> Removing trace from sharp-mountain-4005... done, v20 (free)