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)/

Agent fails to visibly start

Problem: There is no log file nor visible output of the microagent attempting to boot.

Solution: The microagent may be unable to handle some specific combinations of Ruby web servers and startup commands. If a specific web server or command fails, try another one. Make sure to prefix commands with bundle exec (optional for rails commands). Commands known to work include rails server, puma, unicorn, unicorn_rails, thin start, passenger start, rainbows. Commands known not to work or only work partially include rackup, and rails server when combined with the convenience unicorn-rails gem.

Agent notifications contains request error messages

Problem: Error in request to Response code for /ping is 502 or similar message appears in Agent notifications.

Solution: A proxy or firewall might block the mentioned hostname. If so, you might want to whitelist it for HTTPS access. It might also be a transient network issue. If the issue persist, check if you can reliably reach the mentioned hostname over HTTPS from the location where your apps run. You can also check our service status page for any known disruption.