Configuration in Ruby


Sqreen settings can be adjusted according to your needs. This section lists the possible configuration options you have with the Sqreen Ruby agent.

Configuration sources

The Sqreen agent reads its configuration from different places. This is the order of precedence:

  • Environment variables
  • A sqreen.yml file
  • Default configuration options

The sqreen.yml file can be located in:

  • Your application top level directory
  • In a custom place set by SQREEN_CONFIG_FILE environment variable:

export SQREEN_CONFIG_FILE=/custom/path/sqreen.yml

Configuration variables

Find your organization token by going to Account Settings > Tokens in your Sqreen dashboard, or (https://my.sqreen.com/profile/organization/tokens). Your token is prefixed with org_.

To help Sqreen correctly identify the application when you use an organization token, you also need to set a unique application name.

Those information can be provided using the SQREEN_TOKEN and SQREEN_APP_NAME environment variables.

When using the application token, only the SQREEN_TOKEN is required.

Application tokens depreciated

Appplication tokens are dedicated to an application, and organization tokens are available throughout the organization your account belongs to.

While Sqreen will continue to support application tokens for backward compatibility in the short term, they are now depreciated, and we encourage you to convert your applications to use organization tokens as soon as possible.

When using Rails, the application name is conveniently derived from Rails's application class name.

Variable name Role YAML key name Default value Allowed values
SQREEN_TOKEN The Sqreen token. This identifies the agent to Sqreen backend servers token Empty String
SQREEN_APP_NAME The application name as displayed within the Sqreen dashboard app_name Empty (autodetected with Rails) String
SQREEN_CONFIG_FILE Custom location for the YAML based config Empty String
SQREEN_LOG_LOCATION Specify a custom file to write Sqreen logs log_location log/sqreen.log String
SQREEN_LOG_LEVEL Sqreen logging level log_level WARN FATAL ERROR WARN INFO DEBUG
SQREEN_REPORT_PERF Report overhead for each request in the log (WARN level) report_perf false (disabled) Boolean
SQREEN_REPORT_PERF_NR Report overhead for each request to NewRelic as custom transaction attributes report_perf_newrelic 0 (disabled) 0 (disabled), 1 (global overhead), 2 (report duration for each protection category)
SQREEN_IP_HEADER Specify the preferred request header for extracting the client IP address ip_header Empty a header name (case insensitive)
SQREEN_DISABLE Prevent the Sqreen agent from starting. Any value in this environment variable will disable Sqreen. disable false (Sqreen is enabled) Boolean
SQREEN_STRIP_SENSITIVE_DATA Remove sensitive data before sending them to Sqreen strip_sensitive_data true Boolean
SQREEN_STRIP_SENSITIVE_KEYS Comma separated list of keys to strip, refer to the dedicated section below for details strip_sensitive_keys Empty (use default values) (arbitrary)
SQREEN_STRIP_SENSITIVE_REGEX Regular expression used for value stripping, refer to the dedicated section below for details strip_sentitive_regex Empty (use default values) (arbitrary)
HTTP_PROXY, http_proxy HTTP proxy for the agent's reporting connection to Sqreen backend servers - - proxy URI (e.g. http://proxy:port )

YAML indentation

When you edit the config file, indent only with two spaces. If you do not indent correctly, the Sqreen agent throws an error at Startup ("Unable to parse configuration file")

Deploying Sqreen configuration

Configuration file should be deployed on the servers running Sqreen

Multiple Rails environments

The YAML configuration also supports using a different section per Rails environment:

token: mysecrettoken #general configuration

production:
    token:  mysecretproductiontoken # override general configuration

PII scrubbing

Unless strip_sensitive_data is set to false, the Sqreen gem redacts certain data before sending to Sqreen's servers. It redacts the values of key-value pairs listed in strip_sensitive_keys (compared in a case insensitive manner), and redacts any values, including array elements, but not keys, that fully match the strip_sensitive_regex configuration setting.

You can find default PII scrubbing values in PII Scrubbing.

Changing strip_sensitive_keys or strip_sensitive_regex overrides the defaults. So you need to append your extra keys to the list of predefined keys and combine the default regular expression with your new one.