technologic 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb88c721d27998f5b6b611f2c58339ef8484bfa1300267baffea98dc2be2e234
-  data.tar.gz: 7332384dbf2c99b7a17e1ff6a43453f4075ed559212090a57c7ff9cc6fdae9e5
+  metadata.gz: baaef725c4fcecbabe7a4b884cca555d444d1d127da3d359534486ed6704cfe8
+  data.tar.gz: 3eda1c0eb2ffbc45fc6076863f524dcb102c2451b1dbe03cf6823f87e204cbfc
 SHA512:
-  metadata.gz: f91a1fac51ab7ef59ed9477b5f90f25a524cabd788d4cacbd9e48837e7049e17fb000cd5a8b631ba449fa521102a50e928f087861437e4f4a90a307fad95a218
-  data.tar.gz: 127cb27cab07235637a157a4ebe5611516141366a94f657031b95adb01b53d824a3924df27298e32f71d5a54cbb84556a137a0468aac8b41fa1c9d1887ea7f84
+  metadata.gz: 38ec48be6eb419ab8b163c1a668e903783e1e70db56cde77a61c55ad67969f601de5aa402319b2b5d5d2dfb11cac95480b44e162837b2e613fecc2649a8bbdd8
+  data.tar.gz: 1a64a64b011dbad32f913ecda755714d9f2b57b6ec921fb87cb42566a3c62cb3fed788c83283cadb83ae4e7daee0cbb44e206184841ed117423494b31b6bc7df

data/README.md

@@ -5,9 +5,11 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/7e089c2617c530a85b17/maintainability)](https://codeclimate.com/github/Freshly/spicerack/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/7e089c2617c530a85b17/test_coverage)](https://codeclimate.com/github/Freshly/spicerack/test_coverage)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/technologic`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+* [Installation](#installation)
+* [Usage](#usage)
+* [Development](#development)
+* [Contributing](#contributing)
+* [License](#license)
 
 ## Installation
 
@@ -27,7 +29,27 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Simply write the error class, the message as a symbol, and then as a hash anything else you want to see in the logs.
+
+```ruby
+error :ERROR_MESSAGE_HERE, HASH_KEY: INFO_TO_PASS, HASH_KEY2: INFO_TO_PASS, 
+```
+
+All error classes are available: `debug` `info` `warn` `error` `fatal`
+
+Some examples for each:
+
+```ruby
+debug :something_is_not_perfect_here, info_wanted: the_info
+
+info :some_logged_info_i_may_look_at, info_wanted: the_info
+
+warn :its_weird_and_you_wanna_know, info_wanted: the_info
+
+error :email_for_user_does_not_exist, user_id: @user.email
+
+fatal :it_is_going_to_be_a_long_day, need_to_know: info_dump
+```
 
 ## Development
 

data/lib/generators/technologic/initializer/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generate the Technologic configuration initializer.
+
+Example:
+    `rails generate technologic:configuration`
+
+    Generates:
+      Initializer: config/initializers/technologic.rb

data/lib/generators/technologic/initializer/initializer_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Technologic
+  module Generators
+    class InitializerGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb.erb", File.join("config/initializers/technologic.rb")
+      end
+    end
+  end
+end

data/lib/generators/technologic/initializer/templates/initializer.rb.erb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+Rails.application.configure do
+  # When disabled, the default subscribers and loggers are not registered, so events are triggered but not listened for.
+  # config.technologic.enabled = true
+
+  # Technologic uses an event based model to log the events you dispatch inside of your objects.
+  # Logging is therefore only one of the capabilities empowered by Technologic.
+  # Use the Technologic `on_event` subscribers to quickly build out metrics reporting, profiling, etc.
+
+  # Subscribers listen for messages triggered by Technologic's severity methods (debug, info, warn, error, fatal).
+  # Messages are converted into `Technologic::Event` objects and all registered event handlers are triggered.
+  # When disabled, subscribers will not listen for instrumentation messages, so no event handlers will be triggered.
+  # config.technologic.subscribe_to_fatal = true
+  # config.technologic.subscribe_to_error = true
+  # config.technologic.subscribe_to_warn = true
+  # config.technologic.subscribe_to_info = true
+  # config.technologic.subscribe_to_debug = true
+
+  # Loggers register with their affiliated subscribers to listen for and handle events of the specified severity.
+  # When disabled, event handlers are not registered with the subscribers, so no logs will be written.
+  # config.technologic.log_fatal_events = true
+  # config.technologic.log_error_events = true
+  # config.technologic.log_warn_events = true
+  # config.technologic.log_info_events = true
+  # config.technologic.log_debug_events = true
+end
+
+# Technologic is designed to elegantly export into very clean, minimal, and powerful JSON logs and comes packaged with
+# a simple way to convert the default Rails logger to emit JSON logs.
+# Uncomment the lines below to convert the default logger over to JSON logs.
+#
+# JsonLogConverter.convert_rails_logger
+#
+# This class takes a block if you want to customize the payload yourself:
+#
+# JsonLogConverter.convert_rails_logger do |severity, timestamp, msg|
+#   { technologic_is_cool: true, severity: severity[0], timestamp: timestamp.to_i, msg: msg }
+# end
+#
+# By default, the log payload used by the converter is:
+#
+#     { severity:, timestamp:, tags: <if there are any>, message: <for strings>, ...event_data_keys }
+#
+# If you want to manipulate this default payload in your custom formatter, use `#default_json_payload`
+#
+# JsonLogConvert.convert_rails_logger do |severity, timestamp, msg|
+#   default_json_payload(severity, timestamp, msg).merge(technologic_is_cool: true)
+# end
+#
+# *NOTE*: Whatever value you return from the block is logged, so if you return nothing a blank line will be logged!
+# Unless you've changed something about the default Rails logger, it's also a "tagged logger".
+# You can use the `#current_tags` method within your formatter block to get access to these tags.
+#
+# JsonLogConverter.convert_rails_logger do |severity, timestamp, msg|
+#   next if current_tags.include? "silence"
+#   default_json_payload(severity, timestamp, msg)
+# end
+#
+# Finally, the converter provides a Technologic specific convenience method for some optional log parsing.
+# By default, Technologic events are whatever event you log plus the class where the event originated from.
+# This is emitted as one key called event where these values are joined by a period:
+#
+#     { event: "something_bad_happened.Klass" }
+#
+# If you would prefer these two data values to be split in the logs, ex:
+#
+#     { event: "something_bad_happened", class: "Klass" }
+#
+# Then you can use the `#split_event_key_for_payload` method provided with the converter:
+#
+# JsonLogConverter.convert_rails_logger do |severity, timestamp, msg|
+#   split_event_key_for_payload(default_json_payload(severity, timestamp, msg))
+# end

data/lib/json_log_converter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# This plays nicely with Technologic's severity logging methods, writing clean JSON rather than stringified hashes.
+# Call within a `config/initializer` to replace `ActiveSupport::TaggedLogging#call` with a custom JSON log formatter.
+#
+#     JsonLogConverter.convert_rails_logger
+#
+# You can optionally provide a block to the `convert_rails_logger` method to hand-craft the log payload yourself:
+#
+#     JsonLogConverter.convert_rails_logger do |severity, timestamp, msg|
+#       payload = { severity: severity, timestamp: timestamp }
+#       payload[:tags] = current_tags if current_tags.any?
+#       payload.merge(msg.is_a?(Hash) ? msg : { message: msg })
+#     end
+
+module JsonLogConverter
+  def self.convert_rails_logger(&block)
+    define_method(:log_payload_for, &block) if block_given?
+    Rails.logger.formatter.extend self
+  end
+
+  def call(severity, timestamp, _progname, msg)
+    "#{log_payload_for(severity, timestamp, msg).to_json}\n"
+  end
+
+  def default_json_payload(severity, timestamp, msg)
+    payload = { severity: severity, timestamp: timestamp }
+    payload[:tags] = current_tags if current_tags.any?
+    payload.merge(msg.is_a?(Hash) ? msg : { message: msg })
+  end
+
+  def split_event_key_for_payload(payload)
+    return payload unless payload[:event]&.include? "."
+
+    parts = payload[:event].split(".")
+    return payload unless parts.length == 2
+
+    payload[:event] = parts[0]
+    payload[:class] = parts[1]
+    payload
+  end
+
+  def log_payload_for(severity, timestamp, msg)
+    default_json_payload(severity, timestamp, msg)
+  end
+end

data/lib/technologic.rb

@@ -9,6 +9,8 @@ require "active_support/core_ext/string/inflections"
 
 require "short_circu_it"
 
+require "json_log_converter"
+
 require "technologic/version"
 require "technologic/event"
 require "technologic/subscriber/base"

data/lib/technologic/config_options.rb

@@ -15,7 +15,5 @@ module Technologic
     class_attribute :log_warn_events, default: true
     class_attribute :log_info_events, default: true
     class_attribute :log_debug_events, default: true
-
-    class_attribute :include_in_classes, default: %w[ApplicationController]
   end
 end

data/lib/technologic/setup.rb

@@ -8,7 +8,6 @@ module Technologic
 
         setup_subscribers(technologic_config)
         setup_loggers(technologic_config)
-        setup_includes(technologic_config)
       end
 
       private
@@ -28,10 +27,6 @@ module Technologic
         Technologic::InfoSubscriber.on_event { |e| Technologic::Logger.log(:info, e) } if config.log_info_events
         Technologic::DebugSubscriber.on_event { |e| Technologic::Logger.log(:debug, e) } if config.log_debug_events
       end
-
-      def setup_includes(config)
-        config.include_in_classes.each { |class_name| class_name.constantize.include(Technologic) }
-      end
     end
   end
 end

data/lib/technologic/shared_examples.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "shared_examples/a_debug_event_is_logged"
+require_relative "shared_examples/a_fatal_event_is_logged"
+require_relative "shared_examples/a_logged_event_with_severity"
+require_relative "shared_examples/a_surveiled_event"
+require_relative "shared_examples/a_warn_event_is_logged"
+require_relative "shared_examples/an_error_event_is_logged"
+require_relative "shared_examples/an_info_event_is_logged"
+require_relative "shared_examples/an_instrumented_exception_with_severity"
+require_relative "shared_examples/an_instrumented_error_exception"
+require_relative "shared_examples/an_instrumented_fatal_exception"

data/lib/technologic/shared_examples/a_debug_event_is_logged.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#debug`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         debug :thing_being_done, user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       let(:instance) { described_class.new(user) }
+#       let(:user) { double }
+#
+#       before { instance.do_a_thing }
+#
+#       it_behaves_like "a debug event is logged", :thing_being_done do
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "a debug event is logged" do |event, for_class = described_class|
+  include_examples "a logged event with severity", event, :debug, for_class
+end

data/lib/technologic/shared_examples/a_fatal_event_is_logged.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#fatal`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         fatal :thing_being_done, user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       let(:instance) { described_class.new(user) }
+#       let(:user) { double }
+#
+#       before { instance.do_a_thing }
+#
+#       it_behaves_like "a fatal event is logged", :thing_being_done do
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "a fatal event is logged" do |event, for_class = described_class|
+  include_examples "a logged event with severity", event, :fatal, for_class
+end

data/lib/technologic/shared_examples/a_logged_event_with_severity.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of named severity log handlers (used to DRY out other shared examples)
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         info :thing_being_done, user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       let(:instance) { described_class.new(user) }
+#       let(:user) { double }
+#
+#       before { instance.do_a_thing }
+#
+#       it_behaves_like "a logged event with severity", :thing_being_done, :info do
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "a logged event with severity" do |event, severity, for_class = described_class|
+  include_examples "an instrumented event", "#{event}.#{for_class}.#{severity}"
+end

data/lib/technologic/shared_examples/a_surveiled_event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#surveil`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         surveil(:doing_a_thing, user: @user) { :a_thing_is_done }
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       let(:instance) { described_class.new(user) }
+#       let(:user) { double }
+#
+#       before { instance.do_a_thing }
+#
+#       it_behaves_like "a surveiled event", :doing_a_thing do
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "a surveiled event" do |expected_event|
+  subject { ActiveSupport::Notifications }
+
+  let(:expected_class) { described_class }
+  let(:expected_args_start) { [ "#{expected_event}_started.#{expected_class}.info", expected_data ] }
+  let(:expected_args_finished) { [ "#{expected_event}_finished.#{expected_class}.info", {} ] }
+  let(:expected_data) do
+    {}
+  end
+
+  it { is_expected.to have_received(:instrument).with(*expected_args_start) }
+  it { is_expected.to have_received(:instrument).with(*expected_args_finished) }
+end

data/lib/technologic/shared_examples/a_warn_event_is_logged.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#warn`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         warn :thing_being_done, user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       let(:instance) { described_class.new(user) }
+#       let(:user) { double }
+#
+#       before { instance.do_a_thing }
+#
+#       it_behaves_like "a warn event is logged", :thing_being_done do
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "a warn event is logged" do |event, for_class = described_class|
+  include_examples "a logged event with severity", event, :warn, for_class
+end

data/lib/technologic/shared_examples/an_error_event_is_logged.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#error`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         error :thing_being_done, user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       let(:instance) { described_class.new(user) }
+#       let(:user) { double }
+#
+#       before { instance.do_a_thing }
+#
+#       it_behaves_like "an error event is logged", :thing_being_done do
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "an error event is logged" do |event, for_class = described_class|
+  include_examples "a logged event with severity", event, :error, for_class
+end

data/lib/technologic/shared_examples/an_info_event_is_logged.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#info`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         info :thing_being_done, user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       let(:instance) { described_class.new(user) }
+#       let(:user) { double }
+#
+#       before { instance.do_a_thing }
+#
+#       it_behaves_like "an info event is logged", :thing_being_done do
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "an info event is logged" do |event, for_class = described_class|
+  include_examples "a logged event with severity", event, :info, for_class
+end

data/lib/technologic/shared_examples/an_instrumented_error_exception.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#error!`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         error! RuntimeError, "Something bad always happens when you do a thing!", user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       include_examples "an instrumented error exception", RuntimeError do
+#         let(:instance) { described_class.new(user) }
+#         let(:user) { double }
+#         let(:example_method) { instance.do_a_thing }
+#         let(:expected_message) { "Something bad always happens when you do a thing!" }
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "an instrumented error exception" do |error_class|
+  include_examples "an instrumented exception with severity", error_class, :error!
+end

data/lib/technologic/shared_examples/an_instrumented_exception_with_severity.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of exception raising severity loggers (used to DRY out other shared examples)
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         error! RuntimeError, "Something bad always happens when you do a thing!", user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       include_examples "an instrumented exception with severity", RuntimeError, :error! do
+#         let(:instance) { described_class.new(user) }
+#         let(:user) { double }
+#         let(:example_method) { instance.do_a_thing }
+#         let(:expected_message) { "Something bad always happens when you do a thing!" }
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "an instrumented exception with severity" do |error_class, severity|
+  before { allow(instance).to receive(severity).and_call_original }
+
+  let(:expected_message) { nil }
+  let(:expected_data) do
+    {}
+  end
+  let(:expected_arguments) do
+    [ error_class, expected_message ].tap { |arr| arr << expected_data unless expected_data.empty? }.compact
+  end
+
+  it "raises and logs" do
+    expect { example_method }.to raise_error error_class, expected_message
+    expect(instance).to have_received(severity).with(*expected_arguments)
+  end
+end

data/lib/technologic/shared_examples/an_instrumented_fatal_exception.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# RSpec example that tests usage of `#fatal!`
+#
+#     class Klass
+#       include Technologic
+#
+#       def initialize(user)
+#         @user = user
+#       end
+#
+#       def do_a_thing
+#         fatal! RuntimeError, "Something terrible always happens when you do a thing!", user: @user
+#       end
+#     end
+#
+#     RSpec.describe Klass do
+#       include_examples "an instrumented fatal exception", RuntimeError do
+#         let(:instance) { described_class.new(user) }
+#         let(:user) { double }
+#         let(:example_method) { instance.do_a_thing }
+#         let(:expected_message) { "Something terrible always happens when you do a thing!" }
+#         let(:expected_data) do
+#           { user: user }
+#         end
+#       end
+#     end
+
+RSpec.shared_examples_for "an instrumented fatal exception" do |error_class|
+  include_examples "an instrumented exception with severity", error_class, :fatal!
+end

data/lib/technologic/spec_helper.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "shared_examples"

data/lib/technologic/version.rb

@@ -2,5 +2,5 @@
 
 module Technologic
   # This constant is managed by spicerack
-  VERSION = "0.6.3"
+  VERSION = "0.6.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: technologic
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.6.4
 platform: ruby
 authors:
 - Eric Garside
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-29 00:00:00.000000000 Z
+date: 2019-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.3
+        version: 0.6.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.3
+        version: 0.6.4
 description: An opinionated philosophy on logging for Ruby on Rails applications.
 email:
 - garside@gmail.com
@@ -61,6 +61,10 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/technologic/initializer/USAGE
+- lib/generators/technologic/initializer/initializer_generator.rb
+- lib/generators/technologic/initializer/templates/initializer.rb.erb
+- lib/json_log_converter.rb
 - lib/technologic.rb
 - lib/technologic/config_options.rb
 - lib/technologic/debug_subscriber.rb
@@ -71,6 +75,18 @@ files:
 - lib/technologic/logger.rb
 - lib/technologic/railtie.rb
 - lib/technologic/setup.rb
+- lib/technologic/shared_examples.rb
+- lib/technologic/shared_examples/a_debug_event_is_logged.rb
+- lib/technologic/shared_examples/a_fatal_event_is_logged.rb
+- lib/technologic/shared_examples/a_logged_event_with_severity.rb
+- lib/technologic/shared_examples/a_surveiled_event.rb
+- lib/technologic/shared_examples/a_warn_event_is_logged.rb
+- lib/technologic/shared_examples/an_error_event_is_logged.rb
+- lib/technologic/shared_examples/an_info_event_is_logged.rb
+- lib/technologic/shared_examples/an_instrumented_error_exception.rb
+- lib/technologic/shared_examples/an_instrumented_exception_with_severity.rb
+- lib/technologic/shared_examples/an_instrumented_fatal_exception.rb
+- lib/technologic/spec_helper.rb
 - lib/technologic/subscriber/base.rb
 - lib/technologic/subscriber/core.rb
 - lib/technologic/subscriber/event_handling.rb