Troubleshoot the Node.js microagent

This is a non-exhaustive list of troubleshooting strategies. If you need help, please email us at support@sqreen.com or contact us through our web chat.

Increase log verbosity

The Sqreen microagent logs messages to a text file. These messages contain warnings about possible abnormal behavior and describe some actions the microagent is executing. Increase the verbosity of these messages to help you troubleshoot issues with the Sqreen microagent.

Use two environment variables to configure Sqreen's log verbosity:

Env variable name Role Default value Options
SQREEN_LOG_LOCATION Specifies a custom file to which the microagent writes logs. the terminal custom file path
SQREEN_LOG_LEVEL Sets the microagent logging level. WARN or CRITICAL INFO, DEBUG

Use INFO level in production environments.

Use DEBUG only for short periods of time due to the amount of data it generates.

Require Sqreen first

Problem: Many issues stem from the same root cause: the Sqreen microagent is not first in your application.

If the Sqreen microagent does not execute first in your application, the microagent cannot instrument the modules/agents that exist before it. Symptoms of this problem include:

  • The database driver is not protected by Sqreen logic.
  • The request context lost; the microagent cannot be determine which HTTP request the code relates to.

Solution: Ensure that the Sqreen microagent executes first in your application. To help you troubleshoot your setup, the Sqreen microagent informs you if it is not the first module your app executes, and lists all the modules required before it. Note that it does not detect and list Node.js core modules.

Deprecated application tokens

Problem: There is a problem with my application token.

Solution: Sqreen microagents used to use application tokens. These tokens were unique to an application. Sqreen has deprecated application tokens.

Sqreen now uses organization tokens. These tokens are available throughout the organization to which your account belongs.

While Sqreen continues to support application tokens for backward compatibility in the short term, we encourage you to convert your applications to use organization tokens.

Not showing protected requests

Problem: Sqreen is not showing any protected requests but my application has traffic.

Solution: Ensure that require('sqreen') executes first in the main module of your application.

Empty DB requests field

Problem: Sqreen does not show anything under the DB requests field.

Solution:

  • The application does not have the Sqreen module as the first required module. Ensure that require('sqreen') executes first in the main module of your application.
  • Sqreen does not support the database. Refer to Node.js microagent compatibility to review supported databases. Please contact us if your database is not supported.

Not logging in

Problem: Sqreen does not log in.

Solution: Run the troubleshooting script. At the root of the project, run the following:

$ node ./node_modules/.bin/sqreen-check-network
If you are using a proxy, run the following:
$ node ./node_modules/.bin/sqreen-check-network -p <proxy_url>
The script tries to reach the Sqreen server to determine if it is accessible.

Sqreen and New Relic

Problem: I'm using Sqreen and New Relic, and some of the Sqreen features appear to be unavailable.

Solution: If the Sqreen microagent is required after the New Relic agent in your app, the Sqreen microagent cannot instrument your app's code properly. Ensure that require('sqreen') executes first in the main module of your application.

Detecting legitimate queries as injections

Problem: Sqreen is detecting legitimate database queries as injections.

Solution: The module parse-server exposes an API enabling a user to write MongoDB queries from an HTTP request. When you enable NoSQL injection protection, Sqreen detects these injections as vulnerabilities. Whitelist the paths calling parse-server, or disable NoSQL injection protection on your application.