Today’s blog post is the first of a two-part series written by Jason Skowronski, who serves as the lead editor for technical content at Rollbar. Jason began his career as a software developer at Amazon and now enjoys being a developer advocate for the latest technologies.
Application errors can cause frustrating problems for customers that may ultimately lead to losing their trust and business. Experienced developers know what it’s like to have a critical production problem and spend minutes or perhaps even hours diagnosing a tricky problem. It’s even harder to diagnose when several developers are making changes and deployments in parallel.
Rollbar is an error monitoring solution that can tell you what errors occurred after a deployment and show you the deployment and code change that likely caused them. It integrates with your continuous integration and delivery (CI/CD) system to track when deployments are promoted to production. When an new error occurs, it looks up the deployed version in your source code repository like GitHub to identify what code was changed and who changed it. This will help you narrow down errors due to code bugs faster.
In this post, we’ll run through an example showing how Rollbar can integrate with CircleCI and GitHub to make this work. You’ll be able to see the code changes that may have caused the error in just a few clicks.
A simple example
Rollbar integrates with most major programming languages, frameworks, CI/CD solutions, and source code repositories. In this example, we’ll use CircleCI as well as Angular so we can demonstrate JavaScript source code mapping. Our example is freely available and simple to run or modify. The source code is available on the angular-circleCI repository on Github.
If your app is using a different language or framework, you can still follow these instructions, but the part that will be most relevant is adding the deployment API call to Rollbar. This API call is the same for any language.
Open your CircleCI config
First, we are going to show you how to set up CircleCI for our example app. Then we are going to send deployment notifications to Rollbar so it can track when deployments are made.
We will assume that you already have an account with CircleCI. If not, sign up and then configure the source code repository such as GitHub or BitBucket.
CircleCI looks for configuration in a folder named .circleci under the project directory. It should contain a file named config.yml. This file has your deployment command. In my case, the config file deploys to an S3 bucket since the Angular example is a static site. Yours will be different depending on where you deploy your app.
# Deploy our app to the S3 by copying the files
- run:
name: Deploy to S3
command: |
aws --region us-east-2 s3 sync dist s3://rollbar-example/ --delete --acl public-read
Send deployment notifications to Rollbar
Now we can notify Rollbar after successful deployments so it can track the deployed version. Insert the below Rollbar deployment notification after the deployment script. Make sure to replace the example variables with your own access token, username, etc.
- run:
name: Deployment notification to Rollbar
command: |
# Deployment script
…
# Notify rollbar
curl https://api.rollbar.com/api/1/deploy/ \
-F access_token=2a208f30fa1b4f0183adb694c4432038 \
-F environment=production \
-F revision=$CIRCLE_SHA1 \
-F rollbar_username=RollbarExample \
-F local_username=$CIRCLE_USERNAME \
-F comment='Deploy with bug'
access_token: The destination project token on Rollbar. This token is generated when a project is created on Rollbar.
environment: The deployment environment where the service is deployed. We can configure different environments such as development, staging and production.
revision: The deployed application version. This should be the repository comumit ID. Rollbar will create a link to the repository commit source code if the supplied version is the commit ID.
local_username: The user who deployed the build to server.
The deployment version history can now be seen on Rollbar. It can also can identify the code changes made with each deployment. Later, we’ll show you how Rollbar uses this to identify which errors occurred in this deployment.
Add the Rollbar SDK to your app
In previous sections, we learned how to set up the continuous delivery job and integration with Rollbar. Now we will learn how to integrate Rollbar’s SDK to monitor application errors. If handled or unhandled exceptions are thrown in, the application we will catch them and notify Rollbar with the error details.
Step 1:
Prerequisites:
Create an account with Rollbar https://rollbar.com. Create your project and select Java from the list of notifiers. Select the server side access token that is generated when the project is created.
Step 2:
Add the dependency in the package.json file for the Rollbar-Angular in the project. As we mentioned earlier, Rollbar offers SDKs for many other languages.
"dependencies": {
"rollbar": "2.2.8"
}
Step 3:
Configure the Rollbar in your app.module.ts with the mandatory parameters. You can learn more about these parameters in the Javascript SDK docs. Remember to add your own access token in the configuration.
const rollbarConfig = {
accessToken: 'f627d5e044a24b9987a23e54c5df352e',
captureUncaught: true,
captureUnhandledRejections: true,
enabled: true,
source_map_enabled: true,
environment: 'production',
payload: {
server: {
branch: 'master',
root: 'webpack:///./'
},
client: {
javascript: {
code_version: versions.versions.revision
}
}
}
};
The code version should match the version you are deploying and is usually set to the SHA of the git commit. The server root helps Rollbar locate the base path of your source code. They allow Rollbar to match the error reported in your traceback to the source code for the deployed version. We’ll cover this in more depth in the 2nd part of this series.
Step 4:
We will be using the rollbar package to notify Rollbar of errors. Let’s start with the app.component.ts which generates the error. To track errors in Rollbar we need to configure it with the access token we just created. To test it, we can trigger an error with a method sendError() method as shown below. When the exception is thrown, the manualHandle() method will notify Rollbar with a rollbar.error(e) method call.
export class AppComponent {
constructor(private rollbar: Rollbar) {
}
title = 'Angular 4 with Rollbar';
errorMessage = 'Hello World, Error Message';
sendError() {
console.log('Introducing an error code here');
throw new Error(this.errorMessage);
}
}
Step 5:
Now we will test all the pieces that we just put together. We will execute our build on CircleCI, run the application, then generate a test error.
Find the root cause of errors
Check the Rollbar dashboard for the error logging on the Items menu tab which will show the error details along with the link to the source code file that caused the error. The error will show the suspected deployment version along with the piece of code causing the error.
A second way to investigate the cause of errors is by using the Suspect Deploy tab. It shows the revision where the error was first observed, along with changes that were made to the code since the previous deployment. We can see the commit message indicating that an error code was introduced.
Clicking on the link with the revision signature shows us a diff where we can see the source code changes that may have caused this error.
In summary, we have successfully generated an error, tracked the error with Rollbar, and identified the root cause of the problem quickly with Rollbar.
A new feature Rollbar recently launched in its beta features lab is the ability see all the errors occurring after a deployment. This is the reverse of starting with an error and then identifying the deployment. This is helpful for monitoring your application after making a deployment to see which new errors are occurring, which have reactivated, and which are resolved. Below, we can see this deployment was made 2 hours ago and generated our “Hello World” error.
Conclusion Rollbar is a great way to track errors occuring in production. For each deployment, it will tell you which errors have occurred and which code changes were responsible. This can dramatically speed up your troubleshooting time, which will make your team happier and your customers happier too.
Read on for part two of our blog series on how to automatically identify which code changes caused errors. We’ll dive deeper into how source code integration works, including JavaScript source maps.
