Tpt::Rails

This library helps integrate Rails projects into TpT infrastructure (e.g. Datadog, Bugsnag, etc).

Usage

Adding to your app

NOTE: The TpT Rails Template will automatically do the following for you.

bundle add tpt-rails --git '[email protected]:TeachersPayTeachers/tpt-rails'
rails generate tpt:rails:configuration

Configuration

Running rails generate tpt_rails:configure will generate config/initializers/tpt_rails.rb. You can configure this gem and enable optional features in that file.

See the documentation in lib/tpt/rails.rb.

For Kubernetes configuration:

rails generate tpt:rails:kubernetes

For CI/CD configuration:

rails generate tpt:rails:continuous_integration

Overview

This gem provides the following features:

  • Datadog
    • Instruments your app for tracing and provides Tpt::Rails.statsd for custom metrics
  • Bugsnag/Rollbar
    • Configures your app to report exceptions and provides Tpt::Rails.report for handled errors
  • Health check endpoint
    • Adds a health check at /internal/health-check, including built-in DB and Redis health checks
  • Error test endpoint
    • Adds an error test at /internal/error-test that reports an error and emits a metric
  • Kubernetes/Helm configuration
  • CI/CD configuration

See below for more details.

Datadog

If you configure datadog_trace_url then your project will be automatically instrumented.

If you configure datadog_statsd_url then you can also generate custom metrics:

Tpt::Rails.statsd.increment('foo', tags: ['a:b', 'c:d'])

See the documentation in lib/tpt/rails.rb.

Error reporting (e.g. Bugsnag/Rollbar)

If you configure rollbar_access_token & rollbar_enabled, or bugsnag_api_key then your project will be automatically configured to report unhandled exceptions.

To report handled exceptions:

rescue => e
  Tpt::Rails.report(e)

See the documentation in lib/tpt/rails.rb.

Health check endpoint

Tpt::Rails provides the following endpoint:

/internal/health-check

Two checks are added automatically:

  • An ActiveRecord database check is performed if ActiveRecord is used in the app.
  • A Redis check is performed if Redis is used in the app.

You may add more health checks as follows:

config.health_check(:foo) { 1 == 1 }

See the documentation for Tpt::Rails::Config#health_check in lib/tpt/rails/config.rb for more details.

Error test endpoint

Tpt::Rails provides the following endpoint:

/internal/error-test

This endpoint reports an error via Tpt::Rails.report and emits a metric to Datadog.

Puma instrumentation

Add the following to config/puma.rb to have Puma metrics sent to Datadog:

before_fork do
  Tpt::Rails::PumaStatsCollector.run(metrics_client: Tpt::Rails.statsd)
end

Note: this currently only collects metrics when running Puma in clustered mode (i.e. w/ more than one worker)

Developing this Gem

Running tests

  1. Start docker-compose up (provides a real Redis instance for tests)
  2. Run bin/test

Using your local version of this gem in a local app

Change your Gemfile to:

gem 'tpt-rails', path: '/your/local/path/to/tpt/rails'

Publishing a new version of this gem

First ensure you have permissions to publish to rubygems.org.

Once you've merged, check out the master branch and execute:

bundle exec gem bump --push --tag --version patch # patch/minor/major/X.X.X
bundle exec gem release