# 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:
```
revd *.js
```
For all Javascript files in all subdirectories as well:
```
revd "**/*.js"
```
{% hint style="info" %}
**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.
{% endhint %}
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:
```
revd .project1
```
Or for a subproject of .project1:
```
revd .project1.subproject1
```
Project names always start with a dot character and the alias for the top-level project is just a dot.
### Compiler
In addition to being able to specify all project options on the command line, there are options that 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):
```json
{
"option1": option1,
"option2": option2,
...
}
```
This is for a simple configuration that only specifies options, files would be specified on the command line. For a configuration that specifies what files to instrument:
```json
{
"option1": option1,
"option2": option2,
...
"files": "files" or ["files", "more files", ...]
}
```
You can even specify multiple hierarchical nested projects with their own options as:
```json
{
"option1": option1, top-level options (inherited by subprojects),
"option2": option2,
...
".project1": {
"option1": option1, options here override parent
"option2": option2,
...
"files": "files" or ["files", "more files", ...]
},
".project2": {
"option1": option1, options here override parent
"option2": option2,
...
".subproject1": {
"option1": option1, options here override parent
"option2": option2,
...
"files": "files" or ["files", "more files", ...]
},
".subproject2": {
"option1": option1, options here override parent
"option2": option2,
...
"files": "files" or ["files", "more files", ...]
}
}
}
```
### 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 outgoing requests. |
| `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` | Determines whether page open events should be registered as a separate trace segment. Default value is `multi`. Can be set to: `none` - traces won’t include page open events and will start from requests made to the backend, `single` - a single browser entry span and all exit spans are children of this, which can be a long period of time if the person spends a long time on the page, `multi` - a new "/" entry span for each outgoing exit span, regardless if it is from the same non-reloaded page, `split` - same as "multi" except that it is done in a way that the outgoing exit span also appears on the left side in the trace view. Otherwise it is hidden and part of the entry span and not searchable. |
| `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.
|
| `framework` | |
| `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. |
| `legacyDecorators` | Babel legacy decorator parse mode. Use this if you are using decorators on function parameters (like in Angular for example). `true` or `false`, default is `false`. |
| `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 `onevent` or `off`. When in `off` nothing will be recorded even if an unhandled exception occurs. A project that is set to `off` can not be set to `onevent` through the use of the RevDeBug API. 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 stringification to the point of a crash 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. |
| `recordingProb` | The probability (ranging from 0.0 to 1.0) of sending a recording for statistical throttling is set to a default value of 1 (always). |
| `ignoreError` | Comma separated list of Error names not to send recordings for, including non-Error to specify thrown objects which do not derive from the Error class. The error names are checked respecting class hierarchy so that ignoring a base error class will ignore all derived error classes. For an extreme example, ignoring Error also ignores ReferenceError, TypeError, etc... Currently this is only honored for the APM span where the error occurs. If an error is ignored, no indication is propagated back upstream to store recordings of their own (which normally would be), but if the resulting returned status indicates an error (for example http status code 400+) the upstream component may store a recording anyway due to the general error status. |
| `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 `