JavaScript

How to setup recording & monitoring for JavaScript applications

Requirements

• JavaScript application written in:

  • Node.js

    • See demo Node.js app

  • React

    • See demo React JavaScript app

    • See demo React TypeScript app

  • Vue

    • See demo Vue app

  • Angular

    • See demo Angular app

  • TypeScript

    • See demo TypeScript app

  • Cypress automated tests integration

• Configured & installed RevDeBug Server

To setup RevDeBug you will need to:

1. Add RevDeBug.json configuration file to your project

2. Install RevDeBug package from RevDeBug NPM repository

Configure RevDeBug.json with your project

Create a file revdebug.json in main app folder of your project where you have package.json to set up a connection with RevDeBug Monitor.

Node.js

revdebug.json

{
  "host":         "revdebug.server.address",
  "apm":          true,
  "mode":         "onevent",
  "solution":     "Node.js Application",
  // Server instrumentation options
  ".server": {
    "application":  "Node.js Application Server",
    "target":       "node",
    // All js files that are responsible for the server side
    // If you want to instrument all js files type ""**/*.js""
    "files":        ["src/*.js", "app.js"]
  },
  // Browser Recording instrumentation options
  // If you only want to use monitoring of the server side, remove this section
  ".client": {
    "application":  "Node.js Application Client",
    "useFMP":       true,
    "screen":       true,
    "target":       "web",
    "sourceMap":    true,
    "files":        "public/YourFrontendScript.js",
    "index":        "public/index.html"
  }
}

Angular

revdebug.json

{
    "host": 	       "revdebug.server.address",
    "apm":             true,
    "screen":          true,
    "screenTime":      10,
    "solution":        "Angular Example",
    "application":     "Angular Example",
    "type":            "module",
    "mode":            "onevent",
    "sourceMap":       true,
    "path":            "src",
    "files":           "**/*.{js,ts}",
    "index":           "src/index.html",
    "target":          "web",
    "entrySpan":       "single",
    "useFMP":          true,
    "postPath":        "dist",
    "postFiles":       "*.js",
    "framework":       "angular"
}

Vue.js

revdebug.json

{
    "host":                 "revdebug.server.address",
    "apm":                  true,
    "solution":             "Vue Project", 
    "application":          "Vue Example",
    "sw_trace_ignore_path": "/sockjs-node/**",
    "vueErrors":            true,
    "screen":               true,
    "screenTime":           10,
    "target":               "web",
    "type":                 "module",
    "mode":                 "onevent",
    "logging":              "info",
    "sourceMap":            true,
    "path":                 "src",
    "files":                "**/*.{js,vue}",
    "index":                "public/index.html",
    "entrySpan":            "single", 
    "useFMP":               true
}

React - JavaScript

revdebug.json

{
    "host":            "revdebug.server.address",
    "apm":             true, 
    "screen":          true,
    "screenTime":      10,
    "solution":        "React Project", 
    "application":     "React Example", 
    "type":            "module", 
    "mode":            "onevent", 
    "sourceMap":       true,
    "path":            "src", 
    "files":           "**/*.js", 
    "index":           "public/index.html", 
    "excludeInst":     "import",
    "target":          "web", 
    "entrySpan":       "single", 
    "useFMP":          true
}

React - TypeScript

revdebug.json

{
    "host":            "revdebug.server.address",
    "apm":             true, 
    "screen":          true,
    "screenTime":      10,
    "solution":        "TypeScript and React", 
    "application":     "TypeScript and React Example", 
    "type":            "module", 
    "mode":            "onevent", 
    "sourceMap":       true,
    "path":            "src", 
    "files":           "**/*.{ts,tsx}", 
    "index":           "public/index.html", 
    "excludeInst":     "import",
    "target":          "web", 
    "entrySpan":       "single", 
    "useFMP":          true
}

Install RevDeBug NPM repository

Before compiling your project with RevDeBug you should have configured revdebug.json. Everything is done using the revd script. Depending on how you have the RevDeBug npm module installed you either execute it directly or run it with npx revd. For a full list of options run revd --help.

First, add a reference to the @revdebug module repository:

npm config set @revdebug:registry https://nexus.revdebug.com/repository/npm/

Or you can just set the repository for a single project by adding an .npmrc file with the line:

@revdebug:registry=https://nexus.revdebug.com/repository/npm/

Then install as a local dependency:

npm install @revdebug/revdebug

You can verify that RevDeBug is available by running node in interactive mode and doing:

require('@revdebug/revdebug')
{}

Instrument your project with RevDeBug:

npx revd

RevDeBug will instrument your application's code in-place and will preserve the original code in the “__revd/” folder in your project’s directory. Running “npx revd --remove” will reverse the operation.

Instrumentation is meant to be executed on CI/CD Server and not on local development environment, but when running locally keep in mind the above and use “npx revd --remove” to restore the codebase to its uninstrumented state. If you would locally change the kept original source files in “__revd/” folder, running “npx revd” again will instrument the altered code (i.e. your uninstrumented code is kept safe in “__revd/” folder).

Basic setup

Parameter	Effect
host	The hostname or IP address as a string of the RevDeBug Server.
port	The port of the RevDeBug Server, this must be a number.
webPort	The port of the record server for web projects, this must be a number. A value of 0 indicates that the appropriate port 80 or 443 be used according to the secure status.
release	The release string, normally git commit hash (retrieved automatically if not provided).
version	Human readable version string. If package.json is present this comes from the version field.
solution	Solution name. If package.json is present this comes from the name field.
application	Application name. If package.json is present this comes from the main field.
type	How to parse .js and .jsx files, can be commonjs or module. If package.json is present this comes from the type field. All .mjs, .ts and .tsx" files are always parsed as module and all .cjs files are parsed as commonjs regardless of this setting.
runtime	How the RevDeBug runtime is incorporated into the project, can be inject, local or global. The default is global, see below for details.
mode	The record mode you want this project to start in, options are continuous, onevent or standby. When in standby nothing will be recorded even if an unhandled exception occurs. A project that is set to standby or onevent can not be set to continuous through the use of the RevDeBug API and a project in standby can not be changed either. Though this setting can be overridden through the use of environment variables, see below for details.
sourceMap	Specifies whether file.map source maps are to be written alongside instrumented sources, true or false, default is false.
path	This allows you to specify a common path prefix for any files or excludes you specify for the current project or subproject. This value will also be excluded from any web project exception localization filename matching. Paths are inherited from parent projects and this path is joined with and treated as a subpath of the parent.
files	This is where you specify the files to be instrumented for this project. If a project has files then it is a full project and not just a bunch of options for command line compiling or subprojects. This can be specified as either a string or an array of strings, and each one is treated as a wildcard match specifier and all files in the current path which match are included in the project. All files of all subprojects of this project are also automatically excluded from this project.
index	For a web runtime type inject or global this specifies the name of the index HTML-ish file to be modified for the inclusion of the RevDeBug script. For a global project a <script src="__revdebug.js"> tag is inserted into the file whereas for an inject project the full RevDeBug runtime is inlined. For a global project this this is optional, if not specified then you are responsible for loading the RevDeBug runtime script somewhere yourself. This file is always relative to the root path of the project irrespective of path. Also for a global project, if a runtimePath is not explicitly specified then the directory where this index file is located becomes the runtimePath where the RevDeBug runtime is copied.
postPath	Path to the final output of the toolchain for postprocessing. Serves the same purpose for postFiles as path does for files.
postFiles	Wildcard specifiers of final output files for postprocessing.
framework	Option adjusting other parameters for a specific framework. Currently available only for Angular.

Environment variables may be accessed in revdebug.json as such:

"mode": "${MODE}"

These variables can also be passed in on the command line via the -a var=value or --arg var=value option. If you wish to use an environment variable or command line specified argument for an option that takes a number or boolean value then you must use a string:

"port": "${RECORD_PORT}"

For more detailed configuration go to Advanced configuration.