JavaScript

Search…
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 app​
Vue
See demo Vue app​
Cypress automated tests integration
See demo Cypress integration​
Angular
TypeScript
​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 setup connection with RevDeBug Monitor.
revdebug.json
1
{
2
    "host": 	     "revdebug.server.address",
3
    "port":     	 "42734",
4
    "apm":         true,
5
    "release":	   "",
6
    "version":     "1.0.0"
7
    "solution":    "Example Project",
8
    "application": "ExampleApplication",
9
    "type":        "module",
10
    "runtime":     "inject",
11
    "mode":        "onevent",
12
    "sourceMap":   true,
13
    "path":        "src",
14
    "files":       "**/*.{js,ts}",
15
    "index":       "src/index.html",
16
    "postPath":    "dist",
17
    "postFiles":   "*.js"
18
}
19
​
Copied!
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.
Environment variables may be accessed in revdebug.json as such:
1
"mode": "${MODE}"
Copied!
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 which takes a number or boolean value then you must use a string:
1
"port": "${RECORD_PORT}"
Copied!
For more detailed configuration go to Advanced configuration.
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 reference to the @revdebug module repository:
1
npm config set @revdebug:registry https://nexus.revdebug.com/repository/npm/
Copied!
Or you can just set the repository for a single project by adding an .npmrc file with the line:
1
@revdebug:registry=https://nexus.revdebug.com/repository/npm/
Copied!
Then install as a local dependency:
1
npm install @revdebug/revdebug
Copied!
You can verify that RevDeBug is available by running node in interactive mode and doing:
1
> require('@revdebug/revdebug')
2
{}
Copied!
Instrument your project with RevDeBug:
1
> npx revd
Copied!
Advanced configuration
revd script is used to either compile individual groups of files or to compile from a revdebug.json configuration file that can be present in the topmost directory of the project. revdebug.json can contain only options, options and files for the project or multiple hierarchical subprojects with their own options each of which can be instrumented individually. Command line configuration options can override options in revdebug.json if you wish to build a subproject with different options than are specified in revdebug.json.
revd manages the source files you are instrumenting by copying the clean originals to a parallel directory tree under revdsrc/ at the top level directory of the project and replacing the original files with instrumented versions. This is done so that the original project does not have to be aware of or changed for RevDeBug.
The top level directory for the project is considered to be the first at or above the current level which contains a package.json or revdebug.json file. All operations are executed with respect to this directory, even if you run revd in a subdirectory.
For example, the following will instrument all the Javascript files in the current directory:
1
revd *.js
Copied!
For all Javascript files in all subdirectories as well:
1
revd "**/*.js"
Copied!
Note: The quotes are needed to prevent the shell from expanding the wildcards incorrectly on its own. Use quotes around wildcards whenever there is doubt.
If the previous commands are not run in the top project directory then an appropriate path configuration value will be set to make sure the compilation is relative to the top.
If project files are defined in revdebug.json then the project can be instrumented by doing: revd
And if multiple projects or subprojects are defined then they may be instrumented as follows:
1
revd .project1 
Copied!
Or for a subproject of .project1:
1
revd .project1.subproject1
Copied!
Project names always start with a dot character and the alias for the top level project is just dot.
Compiler
In addition to being able to specify all project options on the command line, there are options which can only be passed on the command line in order to tell the compiler what to do or to control behavior, they are:
Actions:
​
--help
Print help info. (short: -h)
--version
Print the version. (short: -v)
--post
Do source map postprocessing after any tools farther down the chain have been run (typescript, webpack, etc...).
--clean
Restore original uninstrumented source files for given config or specified directly.
--remove
Restore ALL original source files in managed source directory and remove directory.
--dump
Dump processed configuration which would be used (don't actually do anything).
​
​
Behavior:
​
--arg ARG=VAL
Add argument for substitution in revdebug.json, "\${ARG}" will be replaced with "VAL". (short: -a)
-force
Force certain actions even if errors would otherwise prevent it. (short: -f)
--skip
Skip certain actions. (short: -s)
-j NUM
Maximum number of threads to use, Node 12+. (default: all logical CPUs)
--verbose
Show all error messages with stack traces. (short: --verb)
--chost ADDR
Compile-time record server override address to send metadata. (default: from --host or config)
--cport PORT
Compile-time record server override port to send metadata. (default: from --port or config)
revdebug.json file structure
The structure of the revdebug.json configuration file may be as follows (please note the names "option1", "option2" etc... used are just placeholders for the actual option names listed farther down):
1
{
2
    "option1": option1,
3
    "option2": option2,
4
     ...
5
}
6
​
Copied!
This is for a simple configuration which only specifies options, files would be specified on the command line. For a configuration which specifies what files to instrument:
1
{
2
    "option1": option1,
3
    "option2": option2,
4
     ...
5
    "files": "files" or ["files", "more files", ...]
6
}
7
​
Copied!
You can even specify multiple hierarchical nested projects with their own options as:
1
{
2
    "option1": option1, top-level options (inherited by subprojects),
3
    "option2": option2,
4
     ...
5
    ".project1": {
6
        "option1": option1, options here override parent
7
        "option2": option2,
8
        ...
9
        "files": "files" or ["files", "more files", ...]
10
    },
11
    ".project2": {
12
        "option1": option1, options here override parent
13
        "option2": option2,
14
        ...
15
        ".subproject1": {
16
            "option1": option1, options here override parent
17
            "option2": option2,
18
            ...
19
            "files": "files" or ["files", "more files", ...]
20
        },
21
        ".subproject2": {
22
            "option1": option1, options here override parent
23
            "option2": option2,
24
            ...
25
            "files": "files" or ["files", "more files", ...]
26
        }
27
    }
28
}
29
​
Copied!
List of options 
The actual options are as follows:
Information:
​
Network:
​
host
The hostname or IP address as a string of the record server.
port
The port of the record 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.
secure
Use secure connections.
connectTimeout
Timeout for connection attempt in milliseconds.
reconnectWait
Amount of time to wait before attempting reconnect after disconnect or failed connect in milliseconds.
Project:
​
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.
version
The version string. If package.json is present this comes from the version field.
release
The release string, normally git commit hash (retrieved automatically if not provided).
authToken
RevDeBug authorization token.
​
​
Application Performance Monitoring:
​
apm
Enable or disable  Application Performance Monitoring for project, can be true or false, default is false.
apmHost
Hostname of APM OAP server if different from record server host, the default is same as host. ("node" target only, ignored for "web")
apmPort
Port of APM OAP server, the default is 11800. ("node" target only, ignored for "web")
excludeIn
Single or list of HTTP status codes to exclude from generating error recordings on incoming requests. Since normally only codes between 400 and 599 generate error traces, it only really makes sense to exclude codes in this range. Status code 0 is a special code which represents errors which can not be determined at the time of filtering. This may represent a 500 internal server error or some other kind of error where the code was not available. For this reason this code was left apart to leave more granular control.
excludeOut
Single or list of HTTP status codes to exclude from generating error recordings on
sw_agent_name
Agent service name.
sw_agent_disable_plugins
Comma separated list of modules for which to disable APM.
sw_agent_max_buffer_size
Rough maximum number of spans per second limiter, anything over this is not reported.
sw_cold_endpoint
When a cold start is detected append "" to the endpoint name.
sw_trace_ignore_path
Comma separated list of wildcard endpoint names to exclude from recording.
sw_ignore_suffix
Comma separated list of endpoint suffixes to exclude from APM recording, the default is ".jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg".
sw_http_ignore_method
Comma-delimited list of http metods to ignore (GET, POST, HEAD, OPTIONS, etc...).
 Node APM: 
​
sw_sql_trace_parameters
Record potentially large sql parameters to queries, can be true or false, default is false.
sw_sql_parameters_max_length
Maximum string length of sql parameters string to send.
sw_mongo_trace_parameters
Record potentially large mongodb parameters to queries, can be true or false, default is false.
sw_mongo_parameters_max_length
Maximum string length of mongodb parameters string to send.
​
​
 Browser APM: 
("web" target only, ignored for "node")
entrySpan
Create entry span for web client, can be true or false, default is true.
useFmp
Collect FMP (first meaningful paint) data of the first screen, can be true or false, default is false.
enableSPA
Monitor the page hashchange event and report PV, which is suitable for single page application scenarios, can be true or false, default is false.
autoTracePerf
Support sending of performance data automatically, can be true or false, default is true.
jsErrors
Javascript error monitoring, can be true or false, default is true.
apiErrors
API error monitoring, can be true or false, default is true.
resourceErrors
Resource error monitoring, can be true or false, default is true.
vueErrors
Vue error monitoring, otherwise will be reported as js error if that is enabled. Can be true or false, default is false. To clarify, this does not "turn on" error reporting from Vue, that is always on, it will simply log those errors as "Vue" as opposed to "JS".
​
​
 Browser screen recording: 
("web" target only, ignored for "node")
screen
Enable or disable screen recording, can be true or false, default is false.
screenTime
Minimum number of seconds of screen recording for crash reports.
​
​
Compile:
​
target
The type of application you are instrumenting, node,webor  azure.The default is node if package.json is present and has a main field, otherwise it is web.
For use with Azure Functions (serverless) use azure.
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.
instrument
The default instrumentation setting for the project. Normally a whole project will be instrumented except for any functions which may opt out (for performance reasons or whatever). This option allows you to start with instrumentation turned off globally and allow only certain functions or methods to opt-in to being recorded. The possible options are on, err or off, these are explained in more detail in the section on errors.
excludeInst
Blacklist of lexical function name calls to exclude from instrumentation because they have a special meaning to a tool farther down the chain, e.g. "require.context". Filename style * and ** wildcards are accepted so "a.*" matches "a.b" and "a.c" but not "a.b.c", while "a.**" matches all the previous. The matching is exact with the source, not syntactically cleaned up by parsing (comments will affect it, but spaces are stripped). This is a string or an array of strings.
functionCode
Include original uninstrumented function source code to return when a function .toString() is called. true or false, default is true for node projects and false for web. This is intended to allow things like MongoDB mapReduce to work properly when it is passed actual functions. It is off by default for web projects but can be turned on, in which case it is up to the user to make sure the source information survives any minification or mangling processing.
copyRuntime
Special case field which allows you to suppress copying the RevDeBug runtime to a directory where the compiler thinks it should go. Intended for configurations where you will be loading the runtime from a custom location. true or false, default is true.
jsx
Specifies whether JSX parsing is to be used for ALL files or only .jsx and .tsx, except for .ts which is never parsed with JSX grammar. true or false, default is true.
ts
Specifies whether Typescript parsing is to be used for ALL files instead of only .ts and .tsx files, true or false, default is false.
​
​
Runtime:
​
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.
logging
Console logging level, options are "critical", "error", "warn", "info" or "debug".
logTime
Log timestamps or not.
mutable
Normally mutable objects and arrays are stringified for serialization at the point of record. That can be slow so this option allows you to defer stringifiction to the point of a crash or live record block send (at which point the object contents may have changed), or turn it off altogether. The default normal stringification is full, deferred is dirty and to turn off specify none. See below for details.
recordings
Maximum concurrent number of snapshots and exception recordings backlog for send, excess will be dropped, 0 = no limit.
backlog
Desired maximum length of crash recordings or snapshots.
blocks
Enable code isolation blocks for asynchronous code allowing only a certain branch to be recorded irrespective of any other async code being executed in parallel. Only works for node projects as browsers don't have a way to track async context yet.
symbols
Whether to show Symbol keys in properties or not, true or false, default is false.
classProps
Whether to show properties of non-Object objects like class instances. By default this is true and they are shown with their properties listed like a standard object following the class name. If this is false then these will be shown instead with the class name followed by a unique integer ID for each new instance (this is faster). true or false, default is true.
functionProps
Whether to show properties of functions, true or false, default is false.
stdObjects
Whether to show details of some standard Javascript objects like Date, Set, Map, ArrayBuffer, SharedArrayBuffer and DataView. true or false, default is true.
typedArrays
Whether to show details of typed arrays or just the length. true or false, default is true.
objectIds
Assign and show globally unique object numeric identifiers on objects which are not Object.preventExtensions(). This is intended to allow differentiation between two otherwise identical objects which evaluate unequal, e.g. "{a: 1} !== {a: 1}". true or false, default is false.
depth
Maximum recursion depth for object stringification, has same meaning as "console.dir(obj, {depth: value})". Default is 1 which is 1 less than "console.log()", so "{name: {name: [Object]}}".
strLen
The maximum(ish) length for stringification of objects or arrays, this value is not strictly obeyed but rather serves as a guide. An actual object stringification may even get to about 2x this length in extreme circumstances. This must be a number.
​
​
 Files / Paths: 
* Note: These are not inherited from parent or are inherited with path append.
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 specifed 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.
exclude
This is specified the same as files but is a list of files which are explicitly to be excluded from this project. Like files this is also a string or an array of strings.
main
If the runtime type is inject then this must be a single file where the RevDeBug runtime code is injected. If the project contains only one source filename then this option does not need to be present and that single source file will be assumed main.
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.
runtimePath
For a web global or local or a node local project, this will override the default location where the RevDeBug runtime is copied. This path is always relative to the root path of the project irrespective of path.
runtimePrefix
This is a string which is not transformed in any way that is inserted right before the RevDeBug runtime name in any node or web import statement or web index script "src" tag. This allows for setting a different URL source for the RevDeBug runtime script (such as a "cdn/js" directory). For local imports, with judicious use of the runtimePath option, this allows for relocating the runtime to a location other than at the top of a project.
runtimeCopy
Special case field which allows you to suppress copying the RevDeBug runtime to a directory where the compiler thinks it should go. Intended for configurations where you will be loading the runtime from a custom location. true or false, default is true.
excludeSys
Global wildcard specifiers of files and directories to completely exclude from all processing in all subprojects. (e.g. "**/node_modules/**").
All these options can be specified on the command line to override any options in the revdebug.json file, so for example to set host on the command line specify --host address. Options which are boolean such as --apm or --sourceMap can be specified on the command line as such to indicate true or --noapm and --nosourceMap to indicate false, --apm=true and --apm=false are also accepted.
Record exclusion/inclusion
Using RevDeBug in runtime
Last modified 7mo ago
Copy link
Contents
Requirements
Configure RevDeBug.json with your project
Basic setup
Install RevDeBug NPM repository
Advanced configuration
Compiler
revdebug.json file structure
List of options