Node.js
Supported Technologies
Confirm that the tCell agent supports your Node.js configuration, as shown below:
Version | App Servers | Web Frameworks | OS | Authentication Frameworks |
---|---|---|---|---|
ES6 | 6.x, 7.x, 8.x, 9.x, 10.x, 11.x, 12.x, 13.x*, 14.x, 15.x, 16.x, 17.x | Hapi 16-19 Express 4.x** | Ubuntu 14+ Debian 8+ Alpine 3.7.1+ | Passport 0.4.x |
Node.js Support Legend
* - 13.3, 13.4, and 13.5 are not supported
** - tCell does not support automatic JS agent injection when sending static HTML files with the res.sendFile
function in Express applications. However, you can manually add the JS agent script tag to these pages instead with the procedure described in Add JavaScript Agent - Manual.
Prerequisites
- A tCell account setup
- An application created (Admin > Applications)
- Allow outbound HTTPS connections to the tCell cloud: What IPs do tCell agents connect to?
- Download the agent and the config file:
- Click on "tCell Admin" in top nav bar
- Click "Download Agent"
- Select "Node" agent
- Select "Create New API Key" (default)
- Click "Download Config File" to download the agent's config file (which is pre-populated with the application and API key information)
Installation
- Run
npm install tcell-agent --save
which adds the dependency to the package.json file. - Alternatively, edit package.json and add
"tcell-agent": "VERSION"
to the dependencies map. Note: VERSION should be set to the latest version, like 1.1.1. Run:npm install
- Run
- Add
require('tcell-agent');
to the top of your main server/app script. This is typically the file called server.js, main.js, index.js or app.js in your application's root directory. - Alternatively run
sed -i "1i require('tcell-agent');" <main server file>
Note
Make sure that the instruction to
require
orimport
the tCell agent is the first instruction in your script. If you import the tCell agent after importing your app, the agent will not work correctly.- Add
- Add tcell_agent.config configuration file to the root of the application
- Restart the application (e.g.
npm restart
)
Verification
To verify that data is being sent to tCell go to your tCell console and ensure that the number of app server agents listed for the application you just created is more than 0.
Troubleshooting
Log files can be found in tcell/log directory.
Log level can be customized in tcell_agent.config file by adding a block such as the following:
json
1"logging_options": {2"enabled": true,3"level": "INFO"4}
Valid log levels are:
- ERROR
- WARN
- INFO (default)
- DEBUG
- TRACE
The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the higher log levels are also enabled. For example, if you enable WARN, then ERROR is also enabled.
When a log file becomes full, logging continues in a new log file. See Log Rolling for more information.
In the tcell directory, see tcell_agent.config.template for an example.
Limitations
The Node agent does not have access to HTTP request information during Local Files instrumentation. You can only filter by the following properties that are not associated with the HTTP request:
- Blocked?
- Rule Id
- File Path
- Mode
- Dir Type
- File Type
- Path Style
- File Exists?
The Node agent (v2.5.0 and later) can detect SQL exceptions (and database exceptions in general) when the application uses Sequelize. Otherwise, it doesn't support SQL exceptions.