TCellAgent

TCell Agent - Instruments Rails

Release Process Checklist

Open a jira with the following checklist (sample: https://jira.tcell.io/browse/RA-98)

[ X ] unit tests pass
[ X ] integration tests pass
[ X ] test-kit tests pass (all variants)
[ X ] check test-kit logs for any unexpected errors
[ X ] performance tests pass (https://github.com/tcellio/load-testing/tree/master/agents)
[ X ] update changelog and version (sample https://github.com/tcellio/rubyagent-tcell/pull/275)

[ X ] manual install verified working (make build, install gem globally: gem install tcell_agent-x.x.x.gem works properly)
[ X ] run tcell_agent test command (might not be needed, since this is run in test-kit for every test-app)

[ X ] Update Master Branch

[ X ] ensure unknown_options accounts for any new keys (check lib/tcell_agent/config/unknown_options.rb file for logic)
[ X ] update support page in wiki with any new support (https://tcellio.atlassian.net/wiki/spaces/EN/pages/54460460/Server+Agent+Support)

Repeat if any bugs are found and patched

[ X ] merge master branch to release branch (this model was followed to make it easy to hotfix released versions)

[ X ] create release in github repo with release notes and appropriate version tag (https://github.com/tcellio/rubyagent-tcell/releases)
[ X ] run make build on release branch (gem unpack tcell_agent-x.x.x.gem and manually inspect .gem file to make sure no files are missing and no extra files are included)
[ X ] upload to rubygems (gem push tcell_agent-x.x.x.gem)
[ X ] confirm upload worked by running a test app that installs latest version from rubygems and smoke test

Common Manual Tests Before Release

Run a Test Kit test app with multiple worker processes and run the suite of tests against it (https://github.com/tcellio/tcell/compare/test-kit/run-multiple-worker-processes?expand=1)

Manually running a test app with multiple worker processes is temporary until this is implemented: https://jira.tcell.io/browse/TCEL-5298

Smoke test a test app. Make sure agent can report appfw, you can post forms, you can login/log out. Test server configurations that you can't test with test-kit. Like multiple worker processes.

Special Things

Config File - For rails applications config files are commonly stored in config/ directory. Rubyagent is configured to look in config/tcell_agent.config by default for its configuration file.

Agent Home Owner - A customer experienced an issue where their web app master process ran as root but each worker process ran as a different user. This caused problems with the tcell/ directory. If the master process created the directory then it was owned by root, so worker processes would raise permission exceptions when they tried to do any logging or write to the cache under the tcell/. config.agent_home_owner was introduced to allow the customer to specify the name of the user that should own tcell/ so that worker process would not get permission exceptions when writing to it. This is no longer necessary with the newest agent version. The newest agent version doesn't do anything in the master process, everything is executed in the workers, so tcell/ should have the correct permissions because it'll always be created by a worker process.

Rails Initializers: It's common for gems to be configured thru Rails initializers: https://guides.rubyonrails.org/v2.3/configuring.html#using-initializers. TCell rubyagent supports this as well. This means that certain rubyagent startup code that relies on configuration needs to run after Rails initializers have run. The rubyagent can be configured entirely thru initializers (as opposed to using tcell_agent.config file and/or ENV vars). Sample config/initializers/tcell.rb file:

if defined?(TCellAgent)
  TCellAgent.configure do |config|
    config.app_id = "---APP_ID---"
    config.api_key = "---API_KEY---"
    config.agent_log_dir = "/tmp/tcelllogs"
    config.agent_home_dir = "/tmp/tcellhome"
    config.tcell_api_url = "https://api.tcell-preview.io/api/v1"
    config.tcell_input_url = "https://input.tcell-preview.io/api/v1"
    config.allow_payloads = true
    # Removed for ruby 2.0
    # config.agent_home_owner = "boris"
    config.enabled = true
    config.logging_options = {"enabled" => true, "level" => "DEBUG"}
    config.host_identifier = "foomyserver"
    config.log_tag = "TCELL_LOGS"
    # Removed for ruby 2.0
    # config.logger can no longer be supported after rubyagent v1.1.4 since logging is now handled by libtcellagent
    # config.logger = Rails.logger
    # or
    # config.logger = ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT))
  end
end

Heroku Deployments - Rails apps are commonly deployed to Heroku. The biggest impact that has on the rubyagent is the agent log file. Heroku doesn't provide access to the filesystem, so the rubyagent needs the ability to log to STDOUT instead of a file. log_tag and logger settings in configuration were introduced to support this.

Log Tag (see above for example log_tag set in config) - Since rubyagent log can be printed to STDOUT along with all the other logging, log_tag is a custom string added to every log line to be able to filter just tcell log lines.

Logger object - Up until rubyagent v1.1.4 you could set a Rails.logger for the rubyagent to use for its logging. With the migration to have libtcellagent handle logging, that use case can no longer be supported. This feature was mainly used to get the rubyagent to log to STDOUT in heroku deployments. So as long as the agent supports some config to allow to log to STDOUT, this won't be missed.

Installation

Download the GEM file and unpack it:

$ curl -O https://s3-us-west-2.amazonaws.com/tcell-agent-download/duvm4dj/tcell_agent-0.2.0.gem

In your rails directory

$ mv tcell_agent-0.2.0.gem vendor/cache/
$ bundle install

Add this line to your application's Gemfile:

gem 'tcell_agent', '0.2.0'

or if you're using the repository directly.

gem "tcell_agent", :path => "<path to your tcell_agent repo>"

And then execute:

$ bundle

Usage

You can download the config file from the Agents section of the application then move it to the config directory

$ cp ~/Downloads/tcell_agent.config config/

Or run the helper command

$ bundle exec tcell_agent setup

Or if running from the repo:

$ bundle exec <path to repo>/rubyagent-tcell/bin/tcell_agent