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
- Instruments your app for tracing and provides
- Bugsnag/Rollbar
- Configures your app to report exceptions and provides
Tpt::Rails.report
for handled errors
- Configures your app to report exceptions and provides
- Health check endpoint
- Adds a health check at
/internal/health-check
, including built-in DB and Redis health checks
- Adds a health check at
- Error test endpoint
- Adds an error test at
/internal/error-test
that reports an error and emits a metric
- Adds an error test at
- 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
- Start
docker-compose up
(provides a real Redis instance for tests) - 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