Loupe Agent for JavaScript - Functionality
Update 2021:
Since the time of this post, Loupe for JavaScript has had a major update.
The Loupe Angular and Typescript agents received a large update in 2021, with added support for .NET Core. If you are looking to use Loupe with JavaScript and .NET, you can learn more about our most recent update in the following links:
Below is our original post on the Loupe Agent for JavaScript from 2015.
As promised in Loupe JavaScript Agent Released I’m going to cover more about the functionality that the new Loupe JavaScript Agent provides.
Where possible, we have tried to make the JavaScript agent mimic the normal .Net agents, so a lot of what the JavaScript Agent does will be familiar to you.
Agents, plural
Saying agent is not quite correct, there are in fact 2 agents: one built to work natively with JavaScript and the other specifically for Angular 1.x.
There are a couple of differences between the 2 agents, but for the most part they have the same functionality; its just that the Angular version has been built to work with the Angular framework to ensure that when you use it it is done in idiomatic angular.
Logging
The agent has various methods for logging:
- Verbose
- Information
- Warning
- Error
- Critical
- Write
Since JavaScript does not support method overloading there is only one method definition but you can provide as many, or as few, parameters as you wish.
Apart from the Write method, the other logging methods all have the same function signature, e.g.
loupe.information(category, caption, description, parameters, exception, details, methodSourceInfo)
These arguments will look familiar to you if you are used to working with the Loupe .Net agent; a full explanation of them can be found here on the agent’s wiki.
In general any parameters you do not supply will be set to null and no data for that field will be logged on the server when it receives the message, and conversely if you do not want to log data for a field you should supply null, e.g.
loupe.information("My Category", "My Caption", "My Description", null, null, "My details");
Just like the .Net agents, the Write method differs from the other methods as it expects to be given the severity level as its first parameter.
Unhandled Exceptions
Both the native JavaScript and Angular agents automatically capture unhandled exceptions.
Native JavaScript agent
If you are using the native JavaScript agent, when it is loaded it will attach a handler to the window.onerror event to ensure that it receives the error and can log it.
If you already handle the onerror event, the agent records any existing handler and calls that function as part of handling the error, so your chain of handlers is not broken.
Angular Agent
The Angular agent decorates the $exceptionHandler service to enable us to capture details of the exception, but lets Angular do what it would normally, be that call another decorator or execute the default behavior (calling $log.error)
Client Details
The normal .Net agent will capture as much information about a client computer as possible, but with JavaScript running in a browser sandbox the information is limited. On every request we send to the server to log a message, details of the client are included to ensure that we can record details that can help you identify the browser settings.
For a full breakdown on the data we record view the wiki for details.
Best efforts to ensure message delivered
When you’re using the normal .Net agent you can be sure not to lose any messages that you want sent as the agent holds onto them until it is able to successfully send them to the server. The JavaScript agents attempt to do the same by utilising local storage for messages, and only removing them when they know a message has been received by the server.
Unfortunately we cannot guarantee that a users browser will either allow or be able to store messages, and in that case we fall back to holding them in memory until we can log them; while this has a risk that the user may close the browser/tab before we can send them, we feel it is a good trade off against simply trying to send the message to the server and losing the message if not able to successfully contact the server.
Summary
As you can see, the functionality of the JavaScript agents is similar to the .Net agents; they provide methods to log messages, as well as the means to capture and log unhandled exceptions. Extracting client details allows you to track browser details, which can be used to help narrow down problems.
In the next post we’ll examine session tracking, and how the agents can be used to aggregate calls across processes.