Install the Ruby microagent

  1. Review Ruby microagent compatibility to confirm that the Sqreen Microagent for Ruby is compatible with your application.
  2. Sign up to create your Sqreen account.
  3. Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token.
  4. In your application root directory, add the microagent gem to your Gemfile.
    echo "gem 'sqreen', '>= 1.22'" >> Gemfile
  5. From Terminal, install the gem in your application root directory, and set the Sqreen token and application name. When using Rails, the application name derives from Rails's application class name.
    # Install the Sqreen gem from your application directory
    bundle install
    # Set the Sqreen token and the application name
    cat > config/sqreen.yml <<EOF
    token: "SQREEN_TOKEN"

The Sqreen Microagent for Ruby is also available in the RubyGems repository.

Install in multiple environments

Typically, you install the Sqreen microagent in your production environment, but you can install it in multiple environments. Use a unique name describing the application and different token for each environment such as production, staging, and development.

  1. From the Sqreen Dashboard, navigate to Account Settings > Environments & Tokens to fetch a token associated to an existing environment or add a new one.
  2. When creating a new environment, Sqreen automatically creates a new token and associates it with it. Take note of the new token.
  3. Set up your application name and SQREEN_TOKEN in the Sqreen microagent configuration file.
# Set the Sqreen token and the app name, including the environment
cat > config/sqreen.yml <<EOF
app_name: "foobar"

Install using Bundler with a Sinatra app

  1. Follow the steps above to install the microagent.
  2. In the application code, where Sinatra is required, require the Sqreen gem in your application code after Sinatra.
    require 'sinatra'
    require 'sqreen'

Install without C++11 compiler

Some environments lack a C++11-compliant compiler (GCC >= 6 or clang >= 8) or a recent-enough linker (GNU ld > 2.3) which can complicate an installation. The following describe two situations that lack a C++-compliant compiler, and how to mitigate them.

  • Stripped down Docker containers: Install g++ or clang before running bundle install or gem install. You can remove the C++ compiler afterward, but you must keep the C++ runtime library (usually libstdc++). To do so on Debian and Ubuntu-based systems: apt install build-essential. On Alpine-based systems: apk add build-base.

  • Old operating system distributions, such as Debian 8, Ubuntu Precise Pangolin, or Alpine 3.8: install a new compiler from separate package repositories, or use a more recent baseline distribution.


To uninstall the Ruby microagent, remove the sqreen gem from your Gemfile.