Troubleshoot the Ruby microagent

This is a non-exhaustive list of troubleshooting strategies. If you need help, please email us at 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.

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.

Failed to build gem native extension

Problem: When installing the microagent on , it fails with the error: ERROR: Failed to build gem native extension. The most common cause of this is that Alpine does not include the build system packages by default.

Solution: Install the build system packages using apk add build-base.

Unable to parse configuration file

Problem: The Sqreen microagent throws an error at startup: Unable to parse configuration file.

Solution: In the sqreen.yaml configuration file, the configurations have been input without correct indentation. Be sure to indent with two spaces.

Alpine Linux and Solaris incompatibilities

Problem: Alpine Linux and Solaris are currently not compatible with libv8 7.3 but only with libv8 6.8.

Solution: We recommend that you apply a version constraint in your Gemfile to use the matching sq_mini_racer version:

gem 'sq_mini_racer', '< 0.2.5' if RUBY_PLATFORM =~ /(?:linux-musl|solaris)/