Get your application events and errors to Trakerr via the Trakerr API.
You can send both errors and non-errors (plain log statements, for example) to Trakerr with this API.
The 3-minute guide is primarily oriented around sending errors or warnings and does not let you specify additional parameters. Option-4 in the detailed integration guide describes how you could send a non-error (or any log statement) along with additional parameters.
The SDK takes performance impact seriously and all communication between the SDK <=> Trakerr avoids blocking the calling function. The SDK also applies asynchronous patterns where applicable.
A Trakerr Event can consist of various parameters as described here in TrakerrApi.AppEvent. Some of these parameters are populated by default and others are optional and can be supplied by you.
Since some of these parameters are common across all event's, the API has the option of setting these on the TrakerrClient instance (described towards the bottom) and offers a factory API for creating AppEvent's.
- Log Level This enum specifies the logging level to be used for this event ('debug','info','warning','error' or 'fatal')
- Event Type This defines the type of event or logger name. This is automatically set for errors.
- Classification This is a user settable property that controls how the events are grouped. Defaults to 'Issue'. Set this to a different value to group this event in a different group.
- Event User This is the user that is associated with this event. This can be any user data or could be encrypted if privacy is required.
- Event Session This is any session specific information associated with this event.
- Cross App Correlation ID This is an additional ID that can be used for cross-application correlation of the same event.
- Operation Time This property in milliseconds measures the operation time for this specific event.
In addition to the above, you can use custom properties and segments to send custom event, performance data. These can then be visualized in Trakerr's dashboards.
Supports running in a NodeJS environment. Also supports running within any Javascript supported Browser with the following dependencies.
Include the following in your HTML
<script src="https://cdnjs.cloudflare.com/ajax/libs/superagent/3.5.2/superagent.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/stacktrace.js/1.3.1/stacktrace.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/trakerr-com/trakerr-javascript@1.1.0/dist/trakerr.min.js"></script>
<script>function initTrakerr() { var c = new TrakerrClient('<api-key>', '1.0', 'production'); c.handleExceptions(false); } initTrakerr();</script>
You can replace 1.0
and production
with the values of app version and deployment stage of your codebase.
This will catch all errors using javascript's onerror and send them to trakerr. While this code is fast and clean, we recommend using the Detailed Integration Guide below to send more useful information about errors.
If you use NPM, install as follows:
npm install --only=prod --save trakerr-com/trakerr-javascript
If you use Bower, install as follows:
bower install https://github.com/trakerr-io/trakerr-javascript
Install global handler
var TrakerrClient = require('trakerr-javascript'); //This is only necessary for NPM use.
var client = new TrakerrClient('<api-key>', //Your API key
'1.0', //Your app version
'production'); //Custom deployment stage of your code.
//any error thrown with throw new Error('...'); will now be sent to Trakerr
client.handleExceptions(false);
Include the dependencies and initialize the global client variable with your API key:
<script src="https://cdnjs.cloudflare.com/ajax/libs/superagent/3.5.2/superagent.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/stacktrace.js/1.3.1/stacktrace.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/trakerr-com/trakerr-javascript@1.1.0/dist/trakerr.min.js"></script>
<!-- initialize the client globally -->
<script> trakerr = new TrakerrClient('<api-key>', //Your API key
'1.0', //Your app version
'production'); //Custom deployment stage of your code.
</script>
And in the angular module, install an $exceptionHandler as shown below:
angular.module('your app').factory('$exceptionHandler', ['$window', function ($window) {
//Replace value within quotes with your API key instead
// create a new event
var appEvent = $window.trakerr.createAppEvent();
return function (exception, cause) {
// ...
$window.trakerr.sendError(exception, "Error", function(error, data, response) {
// ... handle or log response if needed ...
$log.error(exception, cause);//Relogs the error on the console
});
};
}]);
This library works with both node apps and browser apps seamlessly.
In your script, the first thing before sending an event is to create a client. For npm apps, you may use require, but other options are also listed below.
var TrakerrClient = require('trakerr-javascript'); //This is only necessary for NPM use.
var client = new TrakerrClient('<api-key>', //Your API key
'<app version here>', //Your app version
'<deployment stage here>'); //Custom deployment stage of your code.
Calling handleExceptions will send any following error to Trakerr using the onerror handler. If you are calling this from the browser, the shouldDie flag is not relevent to you; and this will catch all unhandled thrown errors. If you are not calling the library from the browser, read about handleException's shouldDie flag.
// Option-1: Add a global exception handler,
//any error thrown with throw new Error('...'); will now be sent to Trakerr
client.handleExceptions(false);
This will allow you to catch and send a specific error to trakerr, also allowing you to handle it afterwards.
try {
....
} catch(err) {
// send it to Trakerr
client.sendError(err);
}
Passing a function to sendError will allow you to quickly populate the properties of the created AppEvent. For AppEvent's properties, see it's docs in the generated folder. The function must take in a parameter.
try {
....
} catch(err) {
// send it to Trakerr
client.sendError(err, "Error", function(event) {
// set some custom properties on the event
event.contextOperationTimeMillis = 1000
event.eventUser = "jake@trakerr.io"
event.eventSession = "20"
event.contextDevice = "pc"
event.contextAppSku = "mobile"
event.contextTags = ["client", "frontend"]
event.customProperties = {
customString: {
customData1: "Some data"
}
};
});
}
You may also send non-errors in a similar fashion from the sendEvent method (as opposed to the sendError method). We recommend that you pass this one a function, and fill it out with custom properties useful to you.
try {
// create a new event
var appEvent = client.createAppEvent();
// ... populate any member data ...
// send it to Trakerr
client.sendEvent(appEvent, function(error, data, response) {
if(error) {
console.error('Error Response: ' + error + ', data = ' + data + ', response = ' +
JSON.stringify(response));
} else {
console.log('Response: data = ' + data + ', response = ' + JSON.stringify(response));
}
});
} catch(err) {
console.err("Error: " + err);
}
We recommend with the above samples 2-4 you populate the EventUser and EventSession fields of app event with the pertinant data to help you identify issues. Option 1 sends no custom data at this time.
The TrakerrClient
's constructor initalizes the default values to all of TrakerrClient's properties.
var exports = function TrakerrClient(apiKey,
contextAppVersion,
contextDevelopementStage)
The TrakerrClient module has a lot of exposed properties. The benefit to setting these immediately after after you create the TrakerrClient is that AppEvent will default it's values against the TrakerClient that created it. This way if there is a value that all your AppEvents uses, and the constructor default value currently doesn't suit you; it may be easier to change it in TrakerrClient as it will become the default value for all AppEvents created after. A lot of these are populated by default value by the constructor, but you can populate them with whatever string data you want. The following table provides an in depth look at each of those.
If you're populating an app event directly, you'll want to take a look at the AppEvent properties as they contain properties unique to each AppEvent which do not have defaults you may set in the client.
Name | Type | Description | Notes |
---|---|---|---|
apiKey | string | API key generated for the application | |
contextAppVersion | string | Application version information. | Default value: 1.0 |
contextDevelopmentStage | string | One of development, staging, production; or a custom string. | Default Value: development |
contextEnvLanguage | string | Constant string representing the language the application is in. | Default value: JavaScript |
contextEnvName | string | Name of the interpreter the program is run on. | Default Value: JavaScript |
contextEnvVersion | string | "Version" of JavaScript this program is running on. While this field is useful in other languages, since each browser or server impements their own features, sometimes not along version specification lines, the default value instead provided another useful value that may come close to being a version. | Default Value: navigator.userAgent if navigator is defined, undefined otherwise |
contextEnvHostname | string | Hostname or ID of environment. | Default value: os.hostname() in a non-browser enviroment, undefined otherwise. |
contextAppOS | string | OS the application is running on. | Default value: OS name (ie. Windows, MacOS). |
contextAppOSVersion | string | OS Version the application is running on. | Default value: OS Version. |
contextAppOSBrowser | string | An optional string browser name the application is running on. | Defaults to the browser name if the app is running from a browser. |
contextAppOSBrowserVersion | string | An optional string browser version the application is running on. | Defaults to the browser version if the app is running from a browser. |
contextDataCenter | string | Data center the application is running on or connected to. | Defaults to 'undefined' |
contextDataCenterRegion | string | Data center region. | Defaults to 'undefined' |
contextTags | Array. | Array of string tags you can use to tag your components for searching., | Defaults to 'undefined' |
contextAppSKU | string | Application SKU. | Defaults to 'undefined' |
Dependencies: grunt.js (if you want to build from source)
Installation via NPM: To install off a branch which may have experimental features, you can use:
npm install --only=prod --save trakerr-com/trakerr-javascript#<branch name>
Building from Source: If you want to build from source for the browser, use the following command:
npm install [--save] trakerr-com/trakerr-javascript
or
npm install [--save] trakerr-com/trakerr-javascript#<branch name>
you can then use grunt to compile your own minified version of the code. The grunt task we use can be executed with:
grunt build
in the folder with gruntFile.js. If you wish to modify or fork our code, simply run grunt build
after modifying the code to try it out in your browser locally.