Documentation

If you have any questions that are beyond the scope of this documentation, Please feel free to create a Support Ticket.

Install

At present, we have released a module exclusively for Node.js. Soon, we'll begin to support Go, Python, Ruby, and other programming languages.

You can install the Errsole module in your Node.js app using the npm install command:

npm install @errsole/node

Configure

You must obtain a unique token to configure the Errsole module in your app.

Follow these steps to generate a token:

Create an Errsole account or sign in with an existing one.
Create an entry for your app.
Copy the code snippet generated for your app, which includes a unique token.
Insert the code snippet as the first line of your app's main file.
Deploy your app as usual. Once deployed, Errsole will start capturing errors and associating them with your app's entry in the Errsole platform.

Example


/**
 * Insert this Errsole code snippet as the first line of your app's main file
 */
const errsole = require('@errsole/node');
errsole.initialize({
  framework: 'express',
  token: '[Your Errsole Token]'
});
// End of Errsole code snippet

/**
 * Your app code starts here
 */
const express = require('express');
const app = express();

app.get('/', function (req, res) {
  res.send('Hello World');
});

app.listen(3000);

Advanced Configuration

Name	Type	Description
framework	string	Required. Your Node.js framework name.
token	string	Required. Create a unique token for your app on the Errsole website.
exitOnException	boolean	Optional. The default value is true. By default, Errsole will exit the process after capturing an uncaught exception. If this is not the behavior you want, you can disable it by setting exitOnException to false.
skipRoutes	Array	Optional. The default value is []. Errsole does not save any HTTP requests that match the routes specified in this list.
filterRoutes	Array	Optional. The default value is []. Errsole only captures the Method, URL, and Status Code of HTTP requests that match the routes specified in this list.
collectLogs	Array	Optional. The default value is ['info', 'error']. By default, Errsole collects both info and error logs. If you wish to limit Errsole to collecting only error logs, you can set this option to ['error']. If you prefer Errsole not to collect any logs, simply set this option to an empty array, []. Added in: v1.7.0
enableSessionLogs	boolean	Optional. The default value is true. This parameter controls whether to save session logs in addition to error details.
responseTimeThreshold	number	Optional. The default value is 1000. This parameter specifies a benchmark duration in milliseconds that Errsole uses to recognize slow HTTP requests. By default, this threshold is set to 1000 milliseconds (1 second), meaning that any HTTP request that takes longer than one second to complete is categorized as slow.
slowRequestsTimeInterval	number	Optional. The default value is 24. This parameter defines a designated time interval for gathering data on slow requests. You can select from four valid options: 1, 6, 12, and 24, corresponding to 1-hour, 6-hour, 12-hour, and 24-hour time intervals.
enableDebugger	boolean	Optional. The default value is true. If false, the Errsole Debugger is disabled.
evalExpression	boolean	Optional If true, your developers have the ability to evaluate JavaScript expressions while debugging an error. This feature allows your developers to debug your app's code more effectively, but it also grants them the ability to run arbitrary code on your server. You have two options: You can set it to false here to disable the eval expression option for all developers, or you can set it to true here and manage the permissions of each developer on the errsole website.

Advanced Configuration Example


/**
 * Insert this Errsole code snippet as the first line of your app's main file
 */
const errsole = require('@errsole/node');
errsole.initialize({
  framework: 'express',
  token: '[Your Errsole Token]',
  exitOnException: true,
  skipRoutes: [{
    method: 'POST',
    path: '/users/login'
  }],
  filterRoutes: [{
    method: 'PUT',
    path: '/users/:userId/profile'
  }],
  enableSessionLogs: true,
  responseTimeThreshold: 1000,
  slowRequestsTimeInterval: 24,
  enableDebugger: true,
  evalExpression: true
});
// End of Errsole code snippet

/**
 * Your app code starts here
 */
const express = require('express');
const app = express();

app.get('/', function (req, res) {
  res.send('Hello World');
});

app.listen(3000);

Verify Setup

Follow these steps to verify your Errsole setup:

Start by signing into Errsole and navigating to the Apps page.
Once on the Apps page, click the Processes option from your app's right menu.
On the Processes page, you will find information about your app processes listed under their respective environments.
If you do not see any app process listed, there might be a problem with your Errsole configuration. Ensure the Errsole code snippet is at the beginning of your app's main file. Examine your app logs to learn more about the error.
We advise creating a support ticket if you still face problems or have more questions.

Please create a support ticket. Our team will swiftly assist you in resolving any concerns.

Apps Page

The Apps page provides an overview of all your app entries in Errsole.

Click the Apps option in the left sidebar menu to go to the Apps page.

Before configuring the Errsole module in your app code, you must create an entry for your app in Errsole. To do this, click the Create App button and complete the form.

Errsole supports four environments for every app: Development, Testing, Staging, and Production. The app errors are categorized based on these environments for better management and tracking.

Under every app entry, you will find dedicated cards for each of the four environments, with each card offering the following information:

Environment Name: Displays the name of the environment (e.g., Development, Testing, Staging, or Production) for easy identification and differentiation.
Active Processes: Displays a real-time count of the active app processes running within the environment.
Unresolved Errors: Displays the number of unresolved errors within the environment, helping you assess the severity and impact of the issues.
Last Error Occurrence: Displays the time of the most recent error that occurred in the environment. This time serves as a reference point for understanding the error frequency and tracking the overall system stability.

On the right side of each app entry, you will find the following buttons to perform various actions:

View Errors: Clicking this button will take you to the Errors page of the app, where you can view all the errors that have occurred in the app.
Processes: This button directs you to the Processes page, which provides detailed information about all the active processes of the app.
Developers: Clicking this button will take you to the Developers page. Here, you can invite developers to the app and manage their permissions at a granular level.
App Tokens: This button takes you to the App Tokens page, where you can access the tokens generated for the app. Errsole generates a unique token for each environment.
Edit Details: Click this button to update the name and description of the app.
Setup Module: Clicking this button will direct you to the Setup Module page. Here, you can find the Errsole code snippet that needs to be placed at the beginning of the app's main file. The Errsole token is included in this code snippet.
Delete App: If you wish to delete the app entry from Errsole, click this button.

Errors Page

The Errors page presents a comprehensive view of all errors that occurred across all environments of an app.

To go to the Errors page of an app, you can follow either of these steps:

Click the View Errors button located on the right side of the app on the Apps page.
Alternatively, you can click the Errors option in the left sidebar menu.

Environment Cards

Errsole supports four environments for every app: Development, Testing, Staging, and Production. The app errors are categorized based on these environments for better management and tracking.

The Errors page displays dedicated cards for each of the four environments, with each card offering the following information:

Environment Name: Displays the name of the environment (e.g., Development, Testing, Staging, or Production) for easy identification and differentiation.
Active Processes: Displays a real-time count of the active app processes running within the environment.
Unresolved Errors: Displays the number of unresolved errors within the environment, helping you assess the severity and impact of the issues.
Last Error Occurrence: Displays the time of the most recent error that occurred in the environment. This time serves as a reference point for understanding the error frequency and tracking the overall system stability.

By clicking an environment card, you can view all the unresolved errors specific to that environment.

Errors Table

The Errors table presents a complete list of unresolved errors specific to the selected app and environment. These errors are organized chronologically, with the most recent error appearing first.

Each row in the errors table presents the following details about an error:

Expand Button: Click the "+" icon located on the left side of each error to get complete details about the error, such as the error stack, HTTP request that triggered the error, and HTTP response.
Error Details: The error details cell contains the following information:

HTTP Response Status Code: If the error is an uncaught exception, this field displays the keyword "Uncaught".
Error Message
Error Id: A unique identifier for each error within the application. You can use this identifier to reference a specific error.
Last Occurrence: The relative time when the error occurred. Hovering over this field will show the exact date and time of the error.
HTTP Request: The HTTP request that triggered the error. Only the HTTP method and path are shown here.

Occurrences: The total number of times the error has occurred.
Actions: On the right side of each error, you will find the following buttons to perform various actions:

Debug: Clicking this button will take you to the Errsole debugger. In the debugger, you can reproduce the error and debug the server code within a sandbox environment.
View Log: Clicking this button will show the logs around the timestamp when the error happened.
View Requests: In case of an error, clicking this button will display the series of requests that the user made before encountering the error.
In case of an uncaught exception, it will display the list of pending requests at the time of the exception. You can identify the specific request that caused the exception and replay it to reproduce the exception.
Assign Developer: Click this button to assign the error to a developer. Once assigned, you will see the developer's profile picture on the right side of the error.
Mark as Resolved: Click this button to mark the error as resolved.
View All Occurrences: Clicking this button will show all occurrences of the error and the associated HTTP requests for each occurrence.

Debugger Page

Errsole creates a clone of your live app on your server and connects the debugger to the app clone. Thus, any changes you make within the debugger will not impact your live app or its users.

Within the debugger, you can set breakpoints, replay the HTTP request, reproduce the error, inspect variables, identify the problem, edit code, and verify the fix, all without impacting your live app.

You have multiple options to access the Errsole debugger:

Access the ongoing debugger by selecting the Debugger option in the left sidebar menu.
On the Errors page, click the Debug button on the right side of an error to troubleshoot the error in the debugger.
In case of an uncaught exception, click the View Log button located on the right side of the exception. This will display a list of pending HTTP requests at the time of the exception. Identify the relevant HTTP request from the list and click the Debug button on its right side. This action will open the debugger. In the debugger, you can reproduce the exception by replaying the selected HTTP request.

The left section of the debugger contains the following components:

Back to the App: This button lets you exit the debugger and return to the Errors page of your app.
Add Folder to Workspace: This button lets you import a folder from your server's filesystem into the Workspace, allowing you to explore all subfolders and files within the selected folder.
Workspace: In Workspace, you can explore the folder that has been imported by clicking the "Add Folder to Workspace" button. You can navigate through the subfolders and files contained within that particular folder. It's important to note that you can only view the names of the files and folders; you cannot access the actual content of the files. Accessing the server filesystem can be useful for debugging.
File Explorer: The file explorer provides access to your app code in a clear tree view. You can navigate through the subfolders and files by expanding the tree. When you click on a file, it will open in the center of the debugger.
Reset Debugger: By clicking this button, you can revert any modifications made in the debugger. This action will discard all changes to the code and remove any set breakpoints, essentially restoring the debugger to its original state.

Code Editor

The debugger's central section features a code editor. When you choose a file from the file explorer, it opens in this section. This is where you can view and edit your app code. Since the debugger is connected to the app clone, any changes you make here will not affect your live app or its users.

You can set a breakpoint at a specific location in the code by clicking the line number displayed on the left side of the editor. When you replay the request, the execution will pause at the breakpoints, allowing you to inspect the variables and troubleshoot the error.

The bottom section of the debugger contains components that are used for troubleshooting the error:

Error Tab

The Error Tab displays the Error Id you have selected for troubleshooting, along with the Occurrence Id. The Error Id represents a specific error, and there could be multiple occurrences of that error. Each occurrence may have been triggered by a different HTTP request. By combining the Error Id and Occurrence Id, you get a unique reference to each error occurrence.

Under the Error tab, you will find the following components:

Headers, Preview, and Response: These tabs provide information about the HTTP request that triggered the error. The Headers tab shows the request details, the Response tab shows the HTTP response in plain text, and the Preview tab displays a preview of the response.
Stack Trace: This tab shows the stack trace of the error you have selected for troubleshooting.
Console: The console tab shows logs generated during the error troubleshooting process. Additionally, you can utilize the console to inspect variables, which can be helpful in effectively troubleshooting the error.
Note: If you don't have permission to execute the code, you cannot inspect variables in the Console. In such cases, you can use the Scope component to inspect variables.
Replay Request: Click this button to replay the HTTP request in the sandbox environment. Set breakpoints at the appropriate locations in the code, then replay the request and examine the variables to troubleshoot the error effectively.
Edit Request: If you suspect that the issue lies within the HTTP request, click this button to edit the request. You can replay the modified request to test your changes.
Cancel Request: Click this button to cancel the ongoing request.

When the execution is paused at a breakpoint, you will find the following buttons under the Error tab:

Resume: Click the Resume button to resume the execution of your script after a pause. This action will enable your script to continue running until it reaches the next breakpoint, if there is one.
Step Over: If you encounter a line of code that contains a function call unrelated to the problem you are debugging, you can click the Step Over button to execute that function without stepping into it.
Step Into: If you encounter a line of code that contains a function call directly related to the problem you are debugging, you can click the Step Into button to further explore and investigate that particular function.
Step Out: If you are paused inside a function that is irrelevant to the problem you are debugging, you can click the Step Out button to execute the remaining code within that function and proceed.

Log Tab

When an uncaught exception is selected for troubleshooting, the components mentioned above (Headers, Preview, Response, Console, Replay Request, Edit Request, Resume, Step Over, Step Into, Step Out, and Cancel Request) are not shown under the Error tab. Instead, they are shown under the Log tab.

Mark as Resolved

Once you have identified the root cause of the error and verified the fix, click this button to mark the error as resolved.

The right section of the debugger contains the following components to help you during the debugging process:

Watch: The Watch component enables you to monitor the values of variables or expressions. You can use either this Watch component or the Console in the bottom section to inspect variables and expressions while debugging.
Note: The watch component will be disabled if you don't have permission to execute the code. In such cases, you can use the Scope component to inspect variables.
Call Stack: While paused on a line of code, the Call Stack component provides a view of the sequence of function calls that led to the current point in the code.
Scope: While paused on a line of code, the Scope component provides a view of the properties and variables in the local, closure, and global scopes, enabling you to examine their values.
Breakpoints: In this component, you can access and manage all the breakpoints you have set. You have the option to clear individual breakpoints or remove all breakpoints from your debugging session.
Help & Support: If you encounter any problems while using the Errsole debugger, click this button to create a support ticket. Our team will swiftly assist you in resolving any concerns.

Developer Page

On the Developers page, you can view and manage the developers who are part of the app team.

You have two options to navigate to the Developers page of an app:

From the Apps page, go to the right menu of the specific app and click the Developers link.
Alternatively, click the Developers link located under the Settings section in the left sidebar.

Add Developer

On the Developers page, you will find an input field that lets you invite developers to the app team. Enter the developer's email address in the input field and click the Add Developer button. This action will add the developer to the app team and send them an invitation email.

Roles

Within an app team, each member is categorized as either an admin or a developer. Admins have full access to the app entry and can perform all actions except deleting it. Developers, on the other hand, have limited permissions primarily for troubleshooting errors.

An admin can change the roles of other team members by clicking the Change Role link located below their respective records.

Permissions

By default, all developers have permission to view errors, debug the app code, and execute custom code on the server during the debugging process in the development, testing, and staging environments of the app. However, developers do not have permission to view errors or debug the app code in the production environment.

An admin can change the permissions of a developer by clicking the Permissions link located below the developer's record.

The admin can assign or revoke the following permissions to a developer in each environment:

View Errors: This permission allows the developer to view all errors that occurred within the environment, along with the HTTP requests that triggered those errors.
Access Debugger: With this permission, the developer can use the Errsole debugger to debug the app code. It is important to note that the Errsole debugger does not affect the live app or its users.
Execute Code: With this permission, the developer can execute custom code on the server during the debugging process. This permission enables the developer to debug the app code effectively. However, it is important to note that enabling this permission also grants the developer the ability to execute arbitrary code on the server.

Remove Developer

To remove a developer from the app entry, the admin can click the Remove link below the developer's record.

Owner: The owner of the app entry is the individual who created it. The owner's status is permanent and cannot be altered or removed from the app entry. Furthermore, it is not possible to change the role or permissions of the owner.