In our previous post, we demonstrated how to easily run an Ionic app on devices without installing the native SDKs using Ionic DevApp. For Part 3 in our series, we will use Ionic Monitor to find and fix errors before they are caught by users.
Ionic Monitor
Ionic Monitor is a great tool as it enables monitoring runtime errors automatically. It is perhaps the only solution that provides error tracking to the typescript source files. Compared to other error tracking mechanisms, the most appealing thing about Ionic Monitor is the way it tracks the error from the web layer to the typescript source maps.
Combining Ionic Monitor with Ionic Deploy allows for rolling out hot updates with fixes quickly. In essence, with Ionic Monitor you can:
- Find out the root cause of runtime errors with tracing to the typescript layer.
- Get real time notifications and alerts so you are notified as soon as something goes bad in the app.
- Fix the errors quickly, even in apps already live in app stores.
Getting started with Ionic Monitor
If you do not have the latest version of the Ionic CLI installed, run the command:
npm install -g ionic
In terminal, from the project’s root folder, install the Ionic Pro client from NPM:
npm install -S @ionic/pro
Make sure that you’re running @ionic/app-scripts version 3.1.0 or later, and @ionic/pro version 1.0.12 or later. You can verify the versions in the package.json file.
To setup and integrate Ionic Monitor in our notes-app , we will create an Ionic Provider named AppErrorHandlerProvider . In terminal, from the project’s root folder, run the command below to create the provider:
ionic g provider AppErrorHandler
Open the file providers/app-error-handler/app-error-handler.ts and replace the contents with the code below:
import { Pro } from '@ionic/pro';
import { Injectable, ErrorHandler, Injector } from '@angular/core';
import { IonicErrorHandler } from 'ionic-angular';
// initializing the Ionic Pro client
const IonicPro = Pro.init('APP_ID', {
appVersion: "APP_VERSION"
});
@Injectable()
export class AppErrorHandlerProvider implements ErrorHandler {
ionicErrorHandler: IonicErrorHandler;
constructor(injector: Injector) {
try {
this.ionicErrorHandler = injector.get(IonicErrorHandler);
} catch(e) {
// Unable to get the IonicErrorHandler provider, ensure
// IonicErrorHandler has been added to the providers list below
}
}
handleError(err: any): void {
IonicPro.monitoring.handleNewError(err); // Remove this if you want to disable Ionic's auto exception handling in development mode.
this.ionicErrorHandler && this.ionicErrorHandler.handleError(err);
}
}
Replace the APP_ID and APP_VERSION with your application’s values for each of them. Go to Ionic Dashboard and copy your Ionic Pro App ID as shown in the image below. This APP_ID makes sure that Ionic Monitor is targeting the appropriate app for error tracking.
You will also need the value for the APP_VERSION . This is useful when shipping newer versions of the app and identifying which version the errors on Ionic Monitor are referring to. The value of APP_VERSION should be similar to the version of your package.json or config.xml (highly recommended).
package.json or config.xml
Once that is taken care of, add AppErrorHandlerProvider to the providers in the app.module.ts file as shown below:
...
import { NgModule, ErrorHandler } from '@angular/core';
import { IonicApp, IonicModule } from 'ionic-angular';
import { AppErrorHandlerProvider } from '../providers/app-error-handler/app-error-handler';
...
@NgModule({
...,
providers: [
...,
{ provide: ErrorHandler, useClass: AppErrorHandlerProvider }
]
})
export class AppModule {}
Ionic Monitor is now set up. As an example, I created a page in the application named Monitor containing several buttons, each triggering a different implementation of the monitoring service. See the page in action and the results below:
Notice that the Exception Detail contains references to main.js, and on the right the information shows Source Mapped value as NO . This means that the source maps have not been configured/synced with the Ionic Pro services. To do that, run the command below (using Ionic CLI 3.9.0 or greater) in your terminal:
ionic monitoring syncmaps
Using SourceMaps
When using source maps, make sure to do the following:
- Sync the source maps before pushing a release to Ionic Pro.
- Do not sync more than once per release as mentioned in Ionic Monitor docs:
- Before doing a release, ensure you’ve synced source maps and make sure to not send new source maps for that version in the future.
- The version number of the running app should match the version of the source maps.
- Utilizing semver for versioning helps in detecting regressions by comparing the version of the app in which the error occurred versus future releases of the app.
You can also upload the source maps manually. To do that, go to Ionic Dashboard. Click the Monitoring tab, then click the source maps button on the top right. You need to do a dev or prod build to generate source maps in YOUR_APP/.sourcemaps/. Upload main.js.map along with other .map files related to your code.
After following the steps above, you should see your synced source maps in the Ionic Dashboard as follows:
When you open the app again, tap the Call wrapped function button to trigger the same error as in the prior images. You will now see the .ts stack trace as well.
Besides having manual triggers, our app also catches any errors automatically since we’re using AppErrorHandlerProvider as the ErrorHandler. Below is an example of an error that occurred when the app property is set to null:
Summary
Ionic Monitor is a great tool that helps you find errors before they become painful for end users. With email alerts, you are notified as soon as something goes bad in your application. Since Monitor can pinpoint the errors to their exact .ts sources, there is less chance of panic attacks for you in the process of fixing the issues.
Part 4
In Part 4, we will go through Ionic Deploy, a service that makes it super easy to deploy app updates in real time.
