Node.js

Supported Technologies

Confirm that the tCell agent supports your Node.js configuration, as shown below:

VersionApp ServersWeb FrameworksOSAuthentication Frameworks
ES66.x, 7.x, 8.x, 9.x, 10.x, 11.x, 12.x, 13.x*, 14.x, 15.xHapi 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:
    1. Click on "tCell Admin" in top nav bar
    2. Click "Download Agent"
    3. Select "Node" agent
    4. Select "Create New API Key" (default)
    5. Click "Download Config File" to download the agent's config file (which is pre-populated with the application and API key information)

Installation

    1. Run npm install tcell-agent --save which adds the dependency to the package.json file.
    2. 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
    1. 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.
    2. Alternatively run sed -i "1i require('tcell-agent');" <main server file>

    Note

    Make sure that the instruction to require or import 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.

  3. Add tcell_agent.config configuration file to the root of the application
  4. Restart the application (e.g. npm restart)

ffi build errors

If you encounter errors building ffi, likely you are building with node 9.x. node-ffi has not yet been updated for node 9.x. tCell is working on a solution for node 9.x, but it is not yet available.

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.