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 'git@github.com:TeachersPayTeachers/tpt-rails'
rails generate tpt:rails:configuration

Configuration

Running rails generate tpt:rails:configuration 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
  • EventBridge integration
    • Adds the aws and aws eventbridge gems, and the EventBridgePublisher class

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.

EventBridge

Tpt::Rails::EventBridgePublisher is the class used to emit events to EventBridge (in batches). To use:

  1. Add EventBridge to your gemfile:
   gem "aws-sdk-eventbridge", "~> 1.3.0"
  1. Instantiate with
   Tpt::Rails::EventBridgePublisher.new
  1. By default (#new with no arguments) EventBridgePublisher will try to use the following environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, TPT_EVENT_SOURCE, TPT_SHARED_EVENT_BUS_NAME.

Additional configuration can be set as part of the constructor; see event_bridge_publisher.rb implementation for more details.

  1. Create events by instantiating or inheriting from Tpt::Rails::ApplicationEvent. Event types are derived from the text before "Event", so ResourceEvent has the event_type "Resource". Pass in an event or an array of events to EventBridgePublisher#publish and they will be published immediately. Large arrays will be batched (default 10 per batch).

  2. EventBridgePublisher uses Tpt::Rails.statsd as its datadog instance by default. If you want to change that behavior, call Tpt::Rails::EventBridgePublisher.set_metrics with the statsd you want to use inside an initializer, as part of a reloader.to_prepare call:

   Rails.application.reloader.to_prepare do
     Tpt::Rails::EventBridgePublisher.set_metrics(
       # your statsd here
     )
   end

You can also do this when testing by using the default test publisher (see below).

EventBridge Testing

  1. To create a ready-made test publisher, use
   Tpt::Rails::EventBridgeTestHelper.publisher

This method accepts two parameters, batch_size and stub_responses. See implementation docs for more details.

  1. The test publisher overwrites statsd that EventBridgePublisher uses to be a dummy statsd when called.

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