Track node.js traffic, caught and uncaught errors

Brought to you by Grackle - Free, online, universal db viewer - https://www.getgrackle.com

Request bugs, changes and updates at https://www.getgrackle.com/feedback

Log and track all traffic and errors in a node.js application. Tracks uncaught promise rejection errors as well as any errors detected by specifc configuration.

Traffic

• Log all traffic to the console
• Log all traffic to your specific database table (mongodb and postgres support. submit a request for other drivers at: https://www.getgrackle.com/feedback)

Errors

• Log uncaught errors to the console and to your database
• Specify valid res.send response on any uncaught errors
• Log caught errors by specifying response fields that trigger the logging

Installation

grackle_tracking can be set up directly in the main index.js file where node.js server is created, however we recommend putting it in a separate configure.js file since the configuration provides a vast number of options.

1. Install grackle_tracking

npm i grackle_tracking@latest --save

2. Create file configure.js with contents:

const grackle_tracking = require("grackle_tracking");
const config = require('./config'); // For your db connection. Omit if don't need to track in db.

let configuration_options = { ... configuration details found below ... }
grackle_tracking.configure(configuration_option);

exports.track = grackle_tracking.track

3. Import the file into your main index file

const grackle_tracking = require('./configure');
app.use(grackle_tracking.track);

Configuration Details

Simplest configuration: no database logging

1. log uncaught errors to console
2. log all traffic to console

{
  errors: {
    log_to_console: true,
    log_to_database: false,
    track_caught_errors: false,
  },
  traffic: {
    log_to_console: true,
    log_to_database: false
  }
}

Track caught errors as well: no database logging

1. log both caught and uncaught errors
2. send valid response to caller upon catching uncaught error

{
  errors: {
    log_to_console: true, // errors less frequent - can log to server
    log_to_database: false,

    // Specify how to detect any errors that have not been unhandled
    track_caught_errors: {
      track: true, // for easy toggling between true/false, however parent can also just be left as null
      
      // This function must return { message, stack_trace } (at the least) along with other parameters you'd like to map pertaining to the error detected. If null/false, the error is not detected. Full error is logged to console if configured and logged in the database configuration at errors.log_to_database with the field **breaking_error** set to **false** indicating that the error has been caught.
      get_error_by: async (response) => {

        // This example detects an error if the response's "success" variable is set to false or null
        if(typeof response === 'string') response = JSON.parse(response);
        if(!response.success) {
          return {

            // These fields are retrieved directly from your response
            message: response.data.system_error,
            stack_trace: response.error
          }
        } else {
          return false;
        }
      }
    },

    // Specify an action to take on any uncaught errors
    on_uncaught_error: (res, grackle_error_data) => {
      // This example sends a valid 200 response with success: false back to the caller
      res.json({
        success: false,
        error: grackle_error_data.message,
        stack_trace: grackle_error_data.stack_trace
      })
    }
  },
  traffic: {
    log_to_console: true,
    log_to_database: false
  }
}

Full configuration: log traffic and errors in database

1. log traffic & errors to console
2. track traffic & errors to database
3. send valid response to caller upon catching uncaught error

{
  errors: {
    log_to_console: true, // errors less frequent - can log to server
    log_to_database: {
      log: true, /// for consistency, however parent could be null instead of log: false
      connection: {
        url: config.TRACKING_DB, // REQUIRED
        driver: grackle_tracking.types.drivers.mogodb, //REQUIRED
        field_mapping: {
          //url, user_id, body, referring ip address, method
          "Errors.request_url": grackle_tracking.types.request.original_url,
          "Errors.request_body": grackle_tracking.types.request.body,
          "Errors.request_method": grackle_tracking.types.request.method,
          "Errors.request_raw": grackle_tracking.types.request.full_request,
          "Errors.request_ip": grackle_tracking.types.request.ip,
          "Errors.error_full": grackle_tracking.types.error.stack_trace,
          "Errors.error_message": grackle_tracking.types.error.message,
          "Errors.breaking_error": grackle_tracking.types.error.breaking_error,
          "Errors.user_id": (request, error) => {
            // ability to set variable using a custom function
            //  with access to the request variable and the error thrown
          }
        }
      }
    },

    // Specify how to detect any errors that have not been unhandled
    track_caught_errors: {
      track: true, // for easy toggling between true/false, however parent can also just be left as null
      
      get_error_by: (response) => {

        // This example detects an error if the response's "success" variable is set to false or null
        if(typeof response === 'string') response = JSON.parse(response);
        if(!response.success) {
          return {

            // These fields are retrieved directly from your response
            message: response.data.system_error,
            stack_trace: response.error
          }
        } else {
          return false;
        }
      }
    },

    // Specify an action to take on any uncaught errors
    on_uncaught_error: (res, grackle_error_data) => {
      // This example sends a valid 200 response with success: false back to the caller
      res.json({
        success: false,
        error: grackle_error_data.message,
        stack_trace: grackle_error_data.stack_trace
      })
    }
  },
  traffic: {
    log_to_console: false, // Recommended to keep off for production if worried about blowing up logs on the server.
    log_to_database: {
      log_request: false, // for easy toggling between true/false, however parent can also just be left as null
      connection: {
        // connection string of the database to log traffic into
        url: config.TRACKING_DB, // REQUIRED

        driver: grackle_tracking.types.drivers.mongodb, //REQUIRED

        // Map where the traffic will be logged to in your database
        field_mapping: { // AT LEAST ONE REQUIRED
          //url, user_id, body, referring ip address, method
          "Traffic.url": grackle_tracking.types.request.original_url,
          "Traffic.body": grackle_tracking.types.request.body,
          "Traffic.method": grackle_tracking.types.request.method,
          "Traffic.raw": grackle_tracking.types.request.full_request,
          "Traffic.ip": grackle_tracking.types.request.ip,
          "Traffic.user_id": (request) => {
            // ability to set variable using a custom function
            //  with access to the request variable
          }
        }
      }
    }
  }
}