If you're trying to install the Node agent and see the following errors when using
npm install, you must set up a compiler.
npm ERR! @firstname.lastname@example.org build: `node-gyp rebuild` npm ERR! Exit status 1 npm ERR! npm ERR! Failed at the @email@example.com build script. npm ERR! This is probably not a problem with npm. There is likely additional logging output above. npm WARN Local package.json exists, but node_modules missing, did you mean to install?
Here are a few things you can do:
Part of our instrumentation process involves rewriting source as it's loaded into the module cache. The agent may fail to rewrite some files for a number of reasons: unexpected syntax, weird character encodings, etc. When this happens, the agent will log its failure and load the original, unmodified source into the module cache. While we may have difficulty following dataflow through these files, everything else should work as normal. Simply, if you are seeing these messages: please let us know!
An Invalid ELF Header error occurs when a native C++ module targeting Linux has been compiled for a non-Linux target. This error typically occurs when the agent is installed on one system and then copied over to another. To fix, ensure that you are installing the agent from a compatible system.
While very uncommon, our instrumentation can introduce some errors. These types of problems are very high priority for us and are usually quickly escalated to one of our engineers; any information you can provide about the bug is very helpful to us in getting it fixed as fast as possible. When this happens, it's usually in one of three ways.
Contrast itself throws an error. This usually results in a clear error message. If there isn't one, run the agent with the
agent.logger.level option set to
debug, which will enable more verbose logging. The error message and stack trace is often enough for us to fix the issue, since it occurred in our code.
Contrast has changed data in a way that causes the application to throw an error. This will also probably result in an error message. Again, use the
agent.logger.level option to enable more verbose logging from the agent. When we cause an error to be thrown in your code, it's almost always because we've manipulated the type of an argument being passed to a function. In this case, any information you can provide about the types the function expects, and what the function does with its arguments, can help us more quickly reproduce and patch the issue.
Contrast has changed data in a way that changes the behavior of the application. For example, data has been malformed by the agent and may break some business logic or cause conditional statements to pass or fail incorrectly. This is very rare, as Contrast tries to avoid ever modifying the meaning of the data. This is often the hardest type of problem to pin down, as on the surface it may seem like the application is fully functional. If you suspect the agent is doing this somewhere, please try to track down what behavior is changing and how it is changing from when the application is run without Contrast. With a known behavior, it becomes easier to track which data is being incorrectly changed. If it is possible to cause a stack trace once you know where this is happening, this information can make it much easier for us to figure out what we're breaking.
From versions 2.0.0 to 2.5.1 of the Node agent, you must have installed:
A C++ compiler toolchain (e.g., Clang, GCC or MSVC) and a POSIX-compatible
Python (which is needed for Node-gyp, Node's build tool, to function)
To install the necessary compiler toolchain on Windows, run
npm install -g --production windows-build-tools. If you're using a Node version older than 8.0, you must use
windows-build-tools version 3.0 (not 4.0, the newest version).
macOS ships with the
clang compiler suite. Use
clang --version to ensure that you have the compiler installed. If Clang is not already installed, run
$ xcode-select --install to install it.
Linux distributions often ship with a C++ compiler toolchain. You can verify that the compiler is installed with
c++ --version. If you don't have a C++ compiler installed, install the
g++ package available from most Linux package managers.