tpt-rails 1.6.2 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a7e431aaf9c9d3546eb414ab15564aba43048d9a3b64104671a1dd589bdc61f
-  data.tar.gz: 4ecdc856396d0d987e8e847694534b620b5140a442714f5f6e7e236f2625f869
+  metadata.gz: a17270ceace03741bb34bcac74250dd4f1b60a478a7870dde68896624bb892ca
+  data.tar.gz: ee980279b3354726a5a5050560fad3e8c5ef9324409acbf011890a8300f66bd8
 SHA512:
-  metadata.gz: 71faac471d35a3e67356427581afdac4f44fcb66c5840b9a8d06571b15e4e47672e36c252352787be31bd5da35e53d69eff3901c79a6c5685abaa49b0c575057
-  data.tar.gz: 68670905648c6cb7456768e0805e04b4c904cd808ada80db3961a73ad35e961f0c51ed597c06b25d2b307fca91822b33998caead07b9b7bf998837d01a65f933
+  metadata.gz: aa83fa139ee86f016380076133d29d2d2406d4aea9da733dd4842bd617a8c16a0418618252c87f10f5e099161bbb249bbc64955fdea15e1d8901bb26c6e6f045
+  data.tar.gz: b3b46f7c49c6d7675a84fafa0088e03b0edea729e7d3b604b568c4f9e45108cd853f43fffc1cf32d51c7c17d5f30be224eed2ac7c83c20fb7a77908088c7e982

data/README.md

@@ -16,7 +16,7 @@ rails generate tpt:rails:configuration
 
 ### Configuration
 
-Running `rails generate tpt_rails:configure` will generate `config/initializers/tpt_rails.rb`. You
+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](lib/tpt/rails.rb).
@@ -74,25 +74,47 @@ See the documentation in [lib/tpt/rails.rb](lib/tpt/rails.rb).
    gem "aws-sdk-eventbridge", "~> 1.3.0"
    ```
 
-2. In an initializer, pass in the `Datadog::Statsd` object you're using to the class method ::set_metrics.
-   (Failure to do so will result in an error.) When testing, you can pass in a local Statsd, eg:
+2. Instantiate with
 
    ```ruby
-   Tpt::Rails::EventBridgePublisher.set_metrics(
-      Datadog::Statsd.new('localhost', 8125)
-   )
+   Tpt::Rails::EventBridgePublisher.new
    ```
 
 3. 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](https://github.com/TeachersPayTeachers/tpt-rails/blob/ad768d3bac0c8bd28e60a48a89aed36f01c4e17b/app/models/tpt/rails/event_bridge_publisher.rb) for more details.
+   [see event_bridge_publisher.rb implementation](https://github.com/TeachersPayTeachers/tpt-rails/blob/master/app/models/tpt/rails/event_bridge_publisher.rb) for more details.
 
 4. 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).
 
+5. 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:
+
+   ```ruby
+   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
+
+   ```ruby
+   Tpt::Rails::EventBridgeTestHelper.publisher
+   ```
+
+   This method accepts two parameters, batch_size and stub_responses. [See implementation docs](https://github.com/TeachersPayTeachers/tpt-rails/blob/master/app/helpers/tpt/rails/event_bridge_test_helper.rb) for more details.
+
+2. 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

data/app/helpers/tpt/rails/event_bridge_test_helper.rb

@@ -0,0 +1,27 @@
+module Tpt::Rails
+  module EventBridgeTestHelper
+    ###
+    # @description: Instantiates an EventBridgePublisher ready for testing. AWS and DataDog info is faked. Note that this sets the
+    #               metrics object for the class to be a stub. The AWS EventBridge gem will never actually be called as the gem's
+    #               #put_events method is replaced with a stub.
+    # @param {batch_size}: The number of events to send per batch.
+    # @param {stub_responses}: Responses to stub, eg. { put_events: { failed_entry_count: 0, entries: [{ event_id: "1" }, { event_id: "2" }] } }
+    # @return {EventBridgePublisher}: The EventBridgePublisher object.
+    ###
+    def self.publisher(batch_size: 10, stub_responses: {})
+      Tpt::Rails::EventBridgePublisher.set_metrics(
+        Datadog::Statsd.new('localhost', 8125)
+      )
+
+      Tpt::Rails::EventBridgePublisher.new(
+        event_source: ENV.fetch('TPT_EVENT_SOURCE', 'test-source'),
+        batch_size: batch_size,
+        client_options: {
+          access_key_id: '1234',
+          secret_access_key: 'abcd',
+          stub_responses: stub_responses
+        }
+      )
+    end
+  end
+end

data/app/models/tpt/rails/event_bridge_publisher.rb

@@ -3,6 +3,7 @@ module Tpt::Rails
     class NoEntriesInResponseData < StandardError; end
 
     attr_accessor :batch_size
+    attr_reader :client
 
     def initialize(
       event_bus_name: default_event_bus_name,
@@ -32,7 +33,7 @@ module Tpt::Rails
 
     private
 
-    attr_reader :client, :event_bus_name, :event_source
+    attr_reader :event_bus_name, :event_source
 
     def publish_batch(events)
       metrics.time('tpt.event_bridge.publish_batch') do
@@ -137,8 +138,9 @@ module Tpt::Rails
     end
 
     def metrics
-      raise "metrics object not set; use EventBridgePublisher#set_metrics" unless @@statsd
+      @@statsd ||= Tpt::Rails.statsd
 
+      raise "metrics object not set and no default found; use EventBridgePublisher#set_metrics" unless @@statsd
       @@statsd
     end
   end

data/lib/generators/tpt/rails/configuration/templates/config/initializers/tpt_rails.rb

@@ -11,4 +11,34 @@ Tpt::Rails.configure do |config|
 
   config.datadog_statsd_url = ENV["DOGSTATSD_URL"].presence
   config.datadog_trace_url = ENV["DATADOG_TRACE_URL"].presence
+
+  # Setup for Statsd
+  #
+  # Either by setting a statsd url (a nil url will create a dummy statsd object):
+  # config.datadog_statsd_url = "statsd://localhost:1234"
+  #
+  # Or by setting a custom statsd setup lambda (which should return a statsd object):
+  # config.datadog_statsd_setup = -> {
+  #   Tpt::Rails::DatadogFactory.make(
+  #     statsd_url: "statsd://localhost:3000",
+  #   )
+  # }
+  #
+  # See documentation in tpt-rails for all the options available on the make method
+
+  # Setup for Tracing
+  #
+  # To disable tracing (you should disable tracing in most environments):
+  # config.datadog_disable_trace = true
+  #
+  # To use default tracing options and just set url:
+  # config.datadog_trace_url =  "datadog://localhost:1234"
+  #
+  # Or for full customization:
+  # Tpt::Rails::DatadogFactory.configure_tracing(
+  #  trace_url: "datadog://localhost:1234",
+  #  environment: "my_env",
+  #  trace_tags: ["mytag1:hello", "mytag2:goodbye"],
+  #  trace_debug: true
+  # )
 end

data/lib/tpt/rails/config.rb

@@ -1,8 +1,14 @@
-require 'tpt/rails/internal/datadog'
+require 'tpt/rails/datadog_factory'
 require 'tpt/rails/internal/error_reporter'
 require 'tpt/rails/internal/health_checks'
 
 class Tpt::Rails::Config
+  class MustBeCallableError < StandardError
+    def initialize(msg)
+      super(msg)
+    end
+  end
+
   #
   # You can set the following configs in your `Tpt::Rails.configure do |config|` block:
   #
@@ -13,16 +19,22 @@ class Tpt::Rails::Config
   attr_accessor :app_name
   # A project-specific api key from Bugsnag
   attr_accessor :bugsnag_api_key
-  # Set this in the form of: statsd://[host]:[port]'
+  # Set this in the form of: statsd://[host]:[port]
   attr_accessor :datadog_statsd_url
-  # Set this in the form of: datadog://[host]:[port]'
+  # Set this in the form of: datadog://[host]:[port]
   attr_accessor :datadog_trace_url
+  # Set to true to disable tracing
+  attr_accessor :datadog_disable_trace
   # Set this in the form of: redis://:[password]@[hostname]:[port]/[db]
   attr_accessor :redis_url
   # A project-specific access token from rollbar
   attr_accessor :rollbar_access_token
   # Allow enabling/disabling Rollbar. Defaults to false.
   attr_accessor :rollbar_enabled
+  # Allows running a custom lambda to setup datadog statsd in configuration
+  attr_accessor :datadog_statsd_setup
+  # Allows running a custom lambda to setup datadog tracing in configuration
+  attr_accessor :datadog_trace_setup
 
   # Add a health check to the endpoint provided at `/internal/health-check` by
   # Tpt::Rails::HealthChecksController.
@@ -56,10 +68,37 @@ class Tpt::Rails::Config
       Redis.current = Redis.new(url: redis_url, driver: :hiredis)
     end
 
-    @datadog = Tpt::Rails::Internal::Datadog.new(
-      statsd_url: datadog_statsd_url,
-      trace_url: datadog_trace_url,
-    )
+    if !datadog_statsd_setup.nil?
+      if datadog_statsd_setup.respond_to?(:call)
+        @statsd = datadog_statsd_setup.call
+        datadog_statsd_setup = nil
+
+        unless @statsd.class == Datadog::Statsd
+          raise "datadog_statsd_setup MUST return a #{Datadog::Statsd.to_s} object! Instead, returned a #{@statsd.class}"
+        end
+      else
+        msg = "datadog_statsd_setup must be nil or callable. You should provide a lambda that returns a statsd object, probably from calling Tpt::Rails::DatadogFactory.make"
+        raise(MustBeCallableError.new(msg))
+      end
+    else
+      @statsd = Tpt::Rails::DatadogFactory.make(
+        statsd_url: datadog_statsd_url,
+      )
+    end
+
+    if datadog_disable_trace
+      Tpt::Rails::DatadogFactory.disable_tracing
+    elsif !datadog_trace_setup.nil?
+      if datadog_trace_setup.respond_to?(:call)
+        datadog_trace_setup.call
+        datadog_trace_setup = nil
+      else
+        msg = "datadog_trace_setup must be nil or callable. You should provide a lambda which calls Tpt::Rails::DatadogFactory.configure_tracing"
+        raise(MustBeCallableError.new(msg))
+      end
+    elsif datadog_trace_url
+      Tpt::Rails::DatadogFactory.configure_tracing(trace_url: datadog_trace_url)
+    end
 
     @health_checks.setup
 
@@ -71,7 +110,7 @@ class Tpt::Rails::Config
   end
 
   def statsd # :nodoc:
-    @datadog.statsd
+    @statsd
   end
 
   def report(error) # :nodoc:

data/lib/tpt/rails/datadog_factory.rb

@@ -0,0 +1,116 @@
+#
+# Configures Datadog metrics and tracing
+#
+
+require 'datadog/statsd'
+require 'ddtrace'
+
+class Tpt::Rails::DatadogFactory
+  class DatadogFactoryNotConfigured < StandardError
+    def initialize(msg)
+      super(msg)
+    end
+  end
+
+  DEFAULT_STATSD_PORT = 8125
+  DEFAULT_TRACE_PORT = 8126
+
+  private_class_method :new
+
+  class << self
+    ###
+      # @description: Instantiates a datadog statsd instance. Note: has side effects, as it configures tracing.
+      # @param {statsd_url}: The url to sends stats to; if nil, a dummy url is used. Form: statsd://[host]:[port]
+      # @param {environment}: Wrapped in "env:#{environment}" and added to tags; if nil, Tpt::Rails.app_env is used;
+      #                       If using eg. reporting env this is where you put it
+      # @param {statsd_tags}: Set your own tags. If nil, default tags are used.
+      #                       If missing, no env tag is supplied, a default (optionally using environment param) is pushed into it.
+      #                       tpt-rails version is always pushed into it.
+      # @return {Datadog::Statsd}
+      ###
+    def make(statsd_url: nil, environment: nil, statsd_tags: nil)
+      if !Tpt::Rails::configured?
+        msg = "Tpt::Rails is not configured. Either run make after configuration, or set a lamda for config.datadog_statsd_setup which will defer setup."
+        raise(DatadogFactoryNotConfigured.new(msg))
+      end
+
+      statsd_tags = Array.wrap(statsd_tags)
+
+      # Fall back to a dummy client so callers don't have to worry about null checking the client
+      url = statsd_url || 'statsd://localhost'
+      uri = URI.parse(url)
+
+      tags = statsd_tags.nil? ? [] : statsd_tags
+      tags << "env:#{to_env(environment)}" unless tags.map { |t| t.split(':')[0] }.include?("env")
+      tags << "tpt-rails_release_version:#{Tpt::Rails.release_version}" if Tpt::Rails.release_version
+
+      ::Datadog::Statsd.new(
+        uri.host,
+        uri.port || DEFAULT_STATSD_PORT,
+        namespace: Tpt::Rails.app_name,
+        tags: tags,
+      )
+    end
+
+    def make_dummy
+      make
+    end
+
+    # @description: Configure tracing. Just passing trace_url: is enough for a basic config.
+    # @param {trace_url}: The url to send traces to; if nil, tracing is disabled. Form: datadog://[host]:[port]
+    # @param {trace_tags}: Set your own trace tags. If missing, default tags are used (optionally using environment param).
+    # @param {trace_debug}: boolean; passed to c.tracer enabled
+    # @param {&block}: Pass to set custom configuration for tracing as part of a .configure call.
+    #                  Accepts one parameter that is the configuration object.
+    def configure_tracing(trace_url: nil, environment:nil, trace_tags: nil, trace_debug: false)
+      if !Tpt::Rails::configured?
+        msg = "Tpt::Rails is not configured. Either run configure_tracing after configuration, or set a lamda for config.datadog_trace_setup which will defer setup."
+        raise(DatadogFactoryNotConfigured.new(msg))
+      end
+
+      uri = URI.parse(trace_url)
+      tags = { 'env' => to_env(environment) }
+      tags["tpt_release_version"] = Tpt::Rails.release_version if Tpt::Rails.release_version
+
+      ::Datadog.configure do |c|
+        # This will activate auto-instrumentation for Rails
+        c.use :rails, {
+          analytics_enabled: true,
+          service_name: Tpt::Rails.app_name,
+        }
+
+        c.tracer(
+          enabled: true,
+          debug: trace_debug,
+          hostname: uri.host,
+          port: uri.port || DEFAULT_TRACE_PORT,
+          tags: tags,
+        )
+
+        c.logger.level = ::Logger::WARN
+
+        yield(c) if block_given?
+      end
+
+      ::Datadog::Pipeline.before_flush(
+        ::Datadog::Pipeline::SpanFilter.new { |span|
+          span.resource =~ /TptRails::HealthChecksController/
+        },
+      )
+    end
+
+    def disable_tracing
+      ::Datadog.configure { |c| c.tracer(enabled: false) }
+    end
+
+    private
+
+    def to_env(environment)
+      if environment.nil?
+        Tpt::Rails.app_env
+      else
+        environment
+      end
+    end
+  end
+end

data/lib/tpt/rails/version.rb

@@ -1,6 +1,6 @@
 module Tpt
   module Rails
     # Do not change this manually. Our tooling will do it automatically.
-    VERSION = '1.6.2'
+    VERSION = '1.7.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tpt-rails
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.1
 platform: ruby
 authors:
 - TpT
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-05 00:00:00.000000000 Z
+date: 2022-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -114,6 +114,7 @@ files:
 - app/controllers/tpt/rails/error_tests_controller.rb
 - app/controllers/tpt/rails/health_checks_controller.rb
 - app/helpers/tpt/rails/application_helper.rb
+- app/helpers/tpt/rails/event_bridge_test_helper.rb
 - app/jobs/tpt/rails/application_job.rb
 - app/mailers/tpt/rails/application_mailer.rb
 - app/models/tpt/rails/application_event.rb
@@ -147,9 +148,9 @@ files:
 - lib/generators/tpt/rails/postman/postman.yaml.tt
 - lib/tpt/rails.rb
 - lib/tpt/rails/config.rb
+- lib/tpt/rails/datadog_factory.rb
 - lib/tpt/rails/engine.rb
 - lib/tpt/rails/internal.rb
-- lib/tpt/rails/internal/datadog.rb
 - lib/tpt/rails/internal/error_reporter.rb
 - lib/tpt/rails/internal/health_checks.rb
 - lib/tpt/rails/puma_stats_collector.rb

data/lib/tpt/rails/internal/datadog.rb

@@ -1,71 +0,0 @@
-#
-# Configures Datadog metrics and tracing, based on Tpt::Rails.config
-#
-
-require 'datadog/statsd'
-require 'ddtrace'
-
-class Tpt::Rails::Internal::Datadog # :nodoc:
-  DEFAULT_STATSD_PORT = 8125
-  DEFAULT_TRACE_PORT = 8126
-
-  attr_reader :statsd
-
-  def initialize(statsd_url: nil, trace_url: nil)
-    @statsd_url = statsd_url
-    @trace_url = trace_url
-
-    @statsd = create_statsd
-
-    if @trace_url
-      configure_tracing
-    end
-  end
-
-  private
-
-  def create_statsd
-    # Fall back to a dummy client so callers don't have to worry about null checking the client
-    url = @statsd_url || 'statsd://localhost'
-    uri = URI.parse(url)
-
-    tags = ["env:#{Tpt::Rails.app_env}"]
-    tags << ["tpt_release_version:#{Tpt::Rails.release_version}"] if Tpt::Rails.release_version
-
-    ::Datadog::Statsd.new(
-      uri.host,
-      uri.port || DEFAULT_STATSD_PORT,
-      namespace: Tpt::Rails.app_name,
-      tags: tags,
-    )
-  end
-
-  def configure_tracing
-    uri = URI.parse(@trace_url)
-    tags = { 'env' => Tpt::Rails.app_env }
-    tags["tpt_release_version"] = Tpt::Rails.release_version if Tpt::Rails.release_version
-
-    ::Datadog.configure do |c|
-      # This will activate auto-instrumentation for Rails
-      c.use :rails, {
-        analytics_enabled: true,
-        service_name: Tpt::Rails.app_name,
-      }
-
-      c.tracer(
-        enabled: true,
-        hostname: uri.host,
-        port: uri.port || DEFAULT_TRACE_PORT,
-        tags: tags,
-      )
-
-      c.logger.level = ::Logger::WARN
-    end
-
-    ::Datadog::Pipeline.before_flush(
-      ::Datadog::Pipeline::SpanFilter.new { |span|
-        span.resource =~ /TptRails::HealthChecksController/
-      },
-    )
-  end
-end