Ruby

Supported Technologies

Confirm that the tCell agent supports your Ruby configuration, as shown below:

VersionApp ServersWeb FrameworksOSAuthentication Frameworks
2.x, 3.xPuma 3.11, 4.x, 5.x
Unicorn 5.x, 6.x
Passenger 6.x		Rails 5.x, 6.x**Ubuntu 14+
Debian 8+
Alpine 3.7.1+		Devise 3.x, 4.x*
Authlogic 3.5.x, 4.x, 5.x, 6.x

Ruby Support Legend

* - In Devise 4.7+, Session Hijacking is not available.
** - Rails appfirewall events and certain account takeover features display an ID (integer) for the user_id instead of the username/email. You must manually query the application's database to get those values. For example, if ID=1 and you want the corresponding username in the database (for example, 'User'):
> rails console
$ User.find(1) # Depends on the model, but 'User' is most common.

Prerequisites

To download the agent and the config file:

  1. Click on "tCell Admin" in top nav bar.
  2. Click "Download Agent".
  3. Select "Ruby" agent.
  4. Select "Create New API Key" (default).
  5. Click "Download Config File" to download the agent's config file (which is pre-populated with the application and API key information).

Installation

  1. Add the following to your Gemfile: 
     
    1
    gem 'tcell_agent'
  2. Run bundle install:
    bundle install
    1
    bundle install
  3. Add tcell_agent.config configuration file to the ./config directory of your project. When you start up your server, tCell will be running. You will see logs created in the ./tcell directory of your project.

Initializer

While configuring the application via the tcell_agent.config static configuration file works for most deployments, sometimes one needs to dynamically configure the application. The Ruby agent supports this via exposing a Rails Initializer proc, configure.

The configure Proc is part of the TCellAgent module, and it can be used to configure the values in Server Agent Options. If the value uses the "#{...} syntax, then as other places, it will be dynamically interpreted as code.

Note

The one exception to the configuration value being the same in the initializer is that the "log_dir" configuration value is actually called "agent_log_dir" in the initializer.

The following is an example of configuring the agent dynamically via an Initializer:

Example of configuring an agent dynamically with an Initializer
1
if defined?(TCellAgent)
2
  TCellAgent.configure do |config|
3
     config.app_id = "--APPID VALUE--"
4
     config.api_key = "--APIKEY VALUE--"
5
     config.agent_log_dir =  "#{Rails.root.join('log').to_s}"
6
     config.logging_options = {"enabled" => true, "level" => "DEBUG"}
7
  end
8
end

In the example above, the log dir is dynamically calculated as subdirectory "log" from the application root.

Update the Agent

To update the Ruby agent to the newest version, run:

tCell agent update
1
bundle update tcell_agent

Bundler automatically updates the agent to the newest release on Rubygems.org.

Verification

To verify that data are being sent to tCell, go to your tCell console and ensure that the number of app server agents listed for the application you just created is more than 0.

Troubleshooting

You can customize the log level in the tcell_agent.config file by adding a block such as the following:

agent config snippet
1
json
2
"logging_options": {
3
    "enabled": true,
4
    "level": "INFO"
5
}

See tcell_agent.config.template for an example.

Valid log levels are:

  • ERROR
  • WARN
  • INFO (default)
  • DEBUG
  • TRACE

The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the higher log levels are also enabled. For example, if you enable WARN, then ERROR is also enabled.

When a log file becomes full, logging continues in a new log file. See Log Rolling for more information.