timber 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1a526175aa41bf2a0f6124b8081fa68dff14d79f
-  data.tar.gz: 85e34c100200bc0c61c576126cf1980d0ac576ca
+  metadata.gz: b8edaf795dfbf8e705fb737cdb7f43ce3821ef2f
+  data.tar.gz: e2d21bde5b38fe63b346070cf0e5ac4f86e158ed
 SHA512:
-  metadata.gz: bbf7e0964fb175ced6f826ff852079373c138f97ee72f1cc8ae367c43c9d11bdd26d318ec365a801fd3657d5cd7d832cae8f6c836e09f93f16ab3f27665f5ee2
-  data.tar.gz: f001a84ee2a8d2df95dd339ca467d884b15e75a26b57fc3bce66ccd3b4234254025b2cf4fddb12c447768b483b869a3cc5d7fa99f2d823cf5d183d2ff54858de
+  metadata.gz: 162e70c46240ca58184950aa7165ff146f2f7b7e78c7e012a694b3aa97b968112870327a8bba978e503ab8a418b86989e8fdecacdf61c6dcefb4204d239322b3
+  data.tar.gz: fdbbff594c9caf2a773db228648f8384c5e345b120d90878ea25289dab529955ce762af955fd0a73de9d00c5fabc22085ef6733ed2a41d3cef0643ae60d14c41

data/README.md

@@ -55,6 +55,7 @@ blog post.
 5. **Long term retention.** Timber is designed on modern big-data principles. As a result, we can
    offer 6+ months of retention at prices cheaper than alternatives offering <1 month.
    This allows you to unlock your logs for purposes beyond debugging.
+
 ---
 
 </p></details>
@@ -63,8 +64,9 @@ blog post.
 
 1. Captures and structures your framework and 3rd party logs. (see next question)
 2. Adds useful context to every log line. (see next question)
-3. Provides a [framework for logging custom structured events](#what-about-custom-events).
-4. Offers transport strategies to [send your logs](#send-your-logs) to the Timber service.
+3. Allows you to easily add tags and timings to log. (see [Usage](#usage))
+4. Provides a framework for logging custom structured events. (see [Usage](#usage))
+5. Offers transport strategies to [send your logs](#send-your-logs) to the Timber service.
 
 ---
 
@@ -122,7 +124,7 @@ logger.info("My log message")
 # My log message @metadata {"level": "info", "context": {...}}
 ```
 
-Timber will never deviate from the public `::Logger` interface in *any* way.
+Timber will *never* deviate from the public `::Logger` interface in *any* way.
 
 ---
 
@@ -130,7 +132,7 @@ Timber will never deviate from the public `::Logger` interface in *any* way.
 
 <details><summary><strong>Tagging logs</strong></summary><p>
 
-Need a quick and easy way to identify a log? Use tags!:
+Need a quick way to identify logs? Use tags!:
 
 ```ruby
 logger.info(message: "My log message", tag: "tag")
@@ -156,10 +158,41 @@ end
 # My log message @metadata {"level": "info", "tags": ["tag"], "context": {...}}
 ```
 
+* In the Timber console use the query: `tags:tag`.
+
+---
+
 </p></details>
 
+<details><summary><strong>Timings, Durations, & Metrics</strong></summary><p>
+
+Timings allow you to easily capture one-off timings in your code; a simple
+way to benchmark code execution:
+
+```ruby
+start = Time.now
+# ...my code to time...
+time_ms = (Time.now - start) * 1000
+logger.info(message: "Task complete", tag: "my_task", time_ms: time_ms)
+
+# My log message @metadata {"level": "info", tags: ["my_task"], "time_ms": 54.2132, "context": {...}}
+```
+
+* In the Timber console use the query: `tags:my_task time_ms>500`
+* The Timber console will also display this value inline with your logs. No need to include it
+  in the log message, but you certainly can if you'd prefer.
+
+---
+
+</p></details>
+
+
 <details><summary><strong>Custom events</strong></summary><p>
 
+Custom events can be used to structure information about events that are central
+to your line of business like receiving credit card payments, saving a draft of a post,
+or changing a user's password. You have 2 options to do this:
+
 1. Log a structured Hash (simplest)
 
   ```ruby
@@ -168,7 +201,8 @@ end
   # Payment rejected @metadata {"level": "warn", "event": {"payment_rejected": {"customer_id": "abcd1234", "amount": 100, "reason": "Card expired"}}, "context": {...}}
   ```
 
-  * The hash can *only* have a `:message` and "event type" key, where `:payment_rejected` is the event type in the above example.
+  * The hash can *only* have 2 keys: `:message` and "event type" key; `:payment_rejected` in this example.
+  * Timber will keyspace your event data by the event type key passed.
 
 2. Log a Struct (recommended)
 
@@ -185,7 +219,7 @@ end
   # Payment rejected @metadata {"level": "warn", "event": {"payment_rejected": {"customer_id": "abcd1234", "amount": 100, "reason": "Card expired"}}, "context": {...}}
   ```
 
-* `:type` is how Timber classifies the event, it creates a namespace for the data you send.
+* In the Timber console use queries like: `payment_rejected.customer_id:xiaus1934` or `payment_rejected.amount>100`
 * For more advanced examples see [`Timber::Logger`](lib/timber.logger.rb).
 * Also, notice there is no mention of Timber in the above code. Just plain old logging.
 
@@ -261,7 +295,7 @@ gem 'timber'
 
 ## Setup
 
-<details><summary><strong>Rails >= 3.0</strong></summary><p>
+<details><summary><strong>Rails (all versions, including edge)</strong></summary><p>
 
 *Replace* any existing `config.logger=` calls in `config/environments/production.rb` with:
 

data/lib/timber/log_entry.rb

@@ -3,9 +3,9 @@ module Timber
   # `Logger` and the log device that you set it up with.
   class LogEntry #:nodoc:
     DT_PRECISION = 6.freeze
-    SCHEMA = "https://raw.githubusercontent.com/timberio/log-event-json-schema/1.2.3/schema.json".freeze
+    SCHEMA = "https://raw.githubusercontent.com/timberio/log-event-json-schema/1.2.4/schema.json".freeze
 
-    attr_reader :context_snapshot, :event, :level, :message, :progname, :tags, :time
+    attr_reader :context_snapshot, :event, :level, :message, :progname, :tags, :time, :time_ms
 
     # Creates a log entry suitable to be sent to the Timber API.
     # @param severity [Integer] the log level / severity
@@ -17,12 +17,13 @@ module Timber
     # @param event [Timber.Event] structured data representing the log line event. This should be
     #   an instance of `Timber.Event`.
     # @return [LogEntry] the resulting LogEntry object
-    def initialize(level, time, progname, message, context_snapshot, event, tags)
+    def initialize(level, time, progname, message, context_snapshot, event, options = {})
       @level = level
       @time = time.utc
       @progname = progname
       @message = message
-      @tags = tags
+      @tags = options[:tags]
+      @time_ms = options[:time_ms]
 
       context_snapshot = {} if context_snapshot.nil?
       system_context = Contexts::System.new(pid: Process.pid)
@@ -34,7 +35,8 @@ module Timber
 
     def as_json(options = {})
       options ||= {}
-      hash = {:level => level, :dt => formatted_dt, :message => message, :tags => tags}
+      hash = {:level => level, :dt => formatted_dt, :message => message, :tags => tags,
+        :time_ms => time_ms}
 
       if !event.nil?
         hash[:event] = event

data/lib/timber/logger.rb

@@ -76,15 +76,24 @@ module Timber
         def build_log_entry(severity, time, progname, msg)
           level = SEVERITY_MAP.fetch(severity)
           context_snapshot = CurrentContext.instance.snapshot
+
           tags = extract_active_support_tagged_logging_tags
-          tags += [msg.delete(:tag)] if msg.is_a?(Hash) && msg.key?(:tag)
-          tags += msg.delete(:tags) if msg.is_a?(Hash) && msg.key?(:tags)
+          time_ms = nil
+          if msg.is_a?(Hash)
+            tags << msg.delete(:tag) if msg.key?(:tag)
+            tags += msg.delete(:tags) if msg.key?(:tags)
+            tags.uniq!
+            time_ms = msg.delete(:time_ms) if msg.key?(:time_ms)
+
+            msg = msg[:message] if msg.length == 1
+          end
+
           event = Events.build(msg)
 
           if event
-            LogEntry.new(level, time, progname, event.message, context_snapshot, event, tags)
+            LogEntry.new(level, time, progname, event.message, context_snapshot, event, tags: tags, time_ms: time_ms)
           else
-            LogEntry.new(level, time, progname, msg, context_snapshot, nil, tags)
+            LogEntry.new(level, time, progname, msg, context_snapshot, nil, tags: tags, time_ms: time_ms)
           end
         end
 
@@ -104,10 +113,10 @@ module Timber
     #
     # Example message:
     #
-    #   My log message @timber.io {"level":"info","dt":"2016-09-01T07:00:00.000000-05:00"}
+    #   My log message @metadata {"level":"info","dt":"2016-09-01T07:00:00.000000-05:00"}
     #
     class HybridFormatter < Formatter
-      METADATA_CALLOUT = "@timber.io".freeze
+      METADATA_CALLOUT = "@metadata".freeze
 
       def call(severity, time, progname, msg)
         log_entry = build_log_entry(severity, time, progname, msg)

data/lib/timber/version.rb

@@ -1,3 +1,3 @@
 module Timber
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 end

data/spec/timber/log_devices/http_spec.rb

@@ -58,9 +58,9 @@ describe Timber::LogDevices::HTTP do
 
     it "should add a request to the queue" do
       http = described_class.new("MYKEY", threads: false)
-      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 1", nil, nil, [])
+      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 1", nil, nil)
       http.write(log_entry)
-      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 2", nil, nil, [])
+      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 2", nil, nil)
       http.write(log_entry)
       http.send(:flush)
       request_queue = http.instance_variable_get(:@request_queue)
@@ -109,9 +109,9 @@ describe Timber::LogDevices::HTTP do
         to_return(:status => 200, :body => "", :headers => {})
 
       http = described_class.new("MYKEY", flush_interval: 0.1)
-      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 1", nil, nil, [])
+      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 1", nil, nil)
       http.write(log_entry)
-      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 2", nil, nil, [])
+      log_entry = Timber::LogEntry.new("INFO", time, nil, "test log message 2", nil, nil)
       http.write(log_entry)
       sleep 0.3
 

data/spec/timber/log_entry_spec.rb

@@ -7,7 +7,7 @@ describe Timber::LogEntry, :rails_23 => true do
     it "should encode properly with an event and context" do
       event = Timber::Events::Custom.new(type: :event_type, message: "event_message", data: {a: 1})
       context = {custom: Timber::Contexts::Custom.new(type: :context_type, data: {b: 1})}
-      log_entry = described_class.new("INFO", time, nil, "log message", context, event, [])
+      log_entry = described_class.new("INFO", time, nil, "log message", context, event)
       msgpack = log_entry.to_msgpack
       expect(msgpack).to start_with("\x86\xA5level\xA4INFO\xA2dt\xBB2016-09-01T12:00:00.000000Z".force_encoding("ASCII-8BIT"))
     end

data/spec/timber/logger_spec.rb

@@ -15,7 +15,7 @@ describe Timber::Logger, :rails_23 => true do
 
       it "should accept strings" do
         logger.info("this is a test")
-        expect(io.string).to start_with("this is a test @timber.io {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\"")
+        expect(io.string).to start_with("this is a test @metadata {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\"")
       end
 
       context "with a context" do
@@ -37,7 +37,7 @@ describe Timber::Logger, :rails_23 => true do
         it "should snapshot and include the context" do
           expect(Timber::CurrentContext.instance).to receive(:snapshot).and_call_original
           logger.info("this is a test")
-          expect(io.string).to start_with("this is a test @timber.io {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\"")
+          expect(io.string).to start_with("this is a test @metadata {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\"")
           expect(io.string).to include("\"http\":{\"method\":\"POST\",\"path\":\"/checkout\",\"remote_addr\":\"123.456.789.10\",\"request_id\":\"abcd1234\"}")
         end
       end
@@ -46,28 +46,43 @@ describe Timber::Logger, :rails_23 => true do
         message = {message: "payment rejected", payment_rejected: {customer_id: "abcde1234", amount: 100}}
         expect(Timber::Events).to receive(:build).with(message).and_call_original
         logger.info(message)
-        expect(io.string).to start_with("payment rejected @timber.io {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\",")
+        expect(io.string).to start_with("payment rejected @metadata {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\",")
         expect(io.string).to include("\"event\":{\"server_side_app\":{\"custom\":{\"payment_rejected\":{\"customer_id\":\"abcde1234\",\"amount\":100}}}}")
       end
 
       it "should log properly when an event is passed" do
         message = Timber::Events::SQLQuery.new(sql: "select * from users", time_ms: 56, message: "select * from users")
         logger.info(message)
-        expect(io.string).to start_with("select * from users @timber.io {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\",")
+        expect(io.string).to start_with("select * from users @metadata {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\",")
         expect(io.string).to include("\"event\":{\"server_side_app\":{\"sql_query\":{\"sql\":\"select * from users\",\"time_ms\":56.0}}}")
       end
 
+      it "should allow :time_ms" do
+        logger.info(message: "event complete", time_ms: 54.5)
+        expect(io.string).to include("\"time_ms\":54.5")
+      end
+
+      it "should allow :tag" do
+        logger.info(message: "event complete", tag: "tag1")
+        expect(io.string).to include("\"tags\":[\"tag1\"]")
+      end
+
+      it "should allow :tags" do
+        logger.info(message: "event complete", tags: ["tag1", "tag2"])
+        expect(io.string).to include("\"tags\":[\"tag1\",\"tag2\"]")
+      end
+
       it "should allow functions" do
         logger.info do
           {message: "payment rejected", payment_rejected: {customer_id: "abcde1234", amount: 100}}
         end
-        expect(io.string).to start_with("payment rejected @timber.io {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\",")
+        expect(io.string).to start_with("payment rejected @metadata {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\",")
         expect(io.string).to include("\"event\":{\"server_side_app\":{\"custom\":{\"payment_rejected\":{\"customer_id\":\"abcde1234\",\"amount\":100}}}}")
       end
 
       it "should escape new lines" do
         logger.info "first\nsecond"
-        expect(io.string).to start_with("first\\nsecond @timber.io")
+        expect(io.string).to start_with("first\\nsecond @metadata")
       end
     end
 

data/spec/timber/probes/action_controller_log_subscriber_spec.rb

@@ -57,9 +57,9 @@ describe Timber::Probes::ActionControllerLogSubscriber do
             dispatch_rails_request("/log_subscriber")
             lines = io.string.split("\n")
             expect(lines.length).to eq(2)
-            expect(lines[0]).to start_with('Processing by LogSubscriberController#index as HTML @timber.io {"level":"info","dt":"2016-09-01T12:00:00.000000Z"')
+            expect(lines[0]).to start_with('Processing by LogSubscriberController#index as HTML @metadata {"level":"info","dt":"2016-09-01T12:00:00.000000Z"')
             expect(lines[0]).to include('"event":{"server_side_app":{"controller_call":{"controller":"LogSubscriberController","action":"index"}}}')
-            expect(lines[1]).to start_with('Completed 200 OK in 0.0ms (Views: 1.0ms) @timber.io {"level":"info","dt":"2016-09-01T12:00:00.000000Z"')
+            expect(lines[1]).to start_with('Completed 200 OK in 0.0ms (Views: 1.0ms) @metadata {"level":"info","dt":"2016-09-01T12:00:00.000000Z"')
             expect(lines[1]).to include('"event":{"server_side_app":{"http_server_response":{"status":200,"time_ms":0.0}}}')
           end
         end

data/spec/timber/probes/action_dispatch_debug_exceptions_spec.rb

@@ -38,7 +38,7 @@ describe Timber::Probes::ActionDispatchDebugExceptions do
         dispatch_rails_request("/exception")
         # Because constantly updating the line numbers sucks :/
         expect(io.string).to include("RuntimeError (boom):\\n\\n")
-        expect(io.string).to include("@timber.io")
+        expect(io.string).to include("@metadata")
         expect(io.string).to include("\"event\":{\"server_side_app\":{\"exception\":{\"name\":\"RuntimeError\",\"message\":\"boom\",\"backtrace\":[\"")
       end
 

data/spec/timber/probes/action_view_log_subscriber_spec.rb

@@ -51,7 +51,7 @@ describe Timber::Probes::ActionViewLogSubscriber do
           it "should log the controller call event" do
             allow_any_instance_of(Timber::Probes::ActionViewLogSubscriber::LogSubscriber).to receive(:logger).and_return(logger)
             dispatch_rails_request("/action_view_log_subscriber")
-            expect(io.string).to start_with("  Rendered spec/support/rails/templates/template.html (0.0ms) @timber.io {\"level\":\"info\"")
+            expect(io.string).to start_with("  Rendered spec/support/rails/templates/template.html (0.0ms) @metadata {\"level\":\"info\"")
             expect(io.string).to include("\"event\":{\"server_side_app\":{\"template_render\":{\"name\":\"spec/support/rails/templates/template.html\",\"time_ms\":0.0}}},")
           end
         end

data/spec/timber/probes/active_record_log_subscriber_spec.rb

@@ -36,12 +36,12 @@ describe Timber::Probes::ActiveRecordLogSubscriber do
 
           it "should log the sql query" do
             User.order("users.id DESC").all.collect # collect kicks the sql because it is lazily executed
-            message = "  \e[1m\e[36mUser Load (0.0ms)\e[0m  \e[1m\e[34mSELECT \"users\".* FROM \"users\" ORDER BY users.id DESC\e[0m @timber.io {\"level\":\"debug\",\"dt\":\"2016-09-01T12:00:00.000000Z\",\"event\":{\"sql_query\":{\"sql\":\"SELECT \\\"users\\\".* FROM \\\"users\\\" ORDER BY users.id DESC\",\"time_ms\":0.0}}}\n"
+            message = "  \e[1m\e[36mUser Load (0.0ms)\e[0m  \e[1m\e[34mSELECT \"users\".* FROM \"users\" ORDER BY users.id DESC\e[0m @metadata {\"level\":\"debug\",\"dt\":\"2016-09-01T12:00:00.000000Z\",\"event\":{\"sql_query\":{\"sql\":\"SELECT \\\"users\\\".* FROM \\\"users\\\" ORDER BY users.id DESC\",\"time_ms\":0.0}}}\n"
             # Rails 4.X adds random spaces :/
             string = io.string.gsub("   ORDER BY", " ORDER BY")
             string = string.gsub("  ORDER BY", " ORDER BY")
             expect(string).to include("users.id DESC")
-            expect(string).to include("@timber.io")
+            expect(string).to include("@metadata")
             expect(string).to include("\"level\":\"debug\"")
             expect(string).to include("\"sql\":")
           end

data/spec/timber/probes/rails_rack_logger_spec.rb

@@ -38,7 +38,7 @@ describe Timber::Probes::RailsRackLogger do
         allow(::Rails).to receive(:logger).and_return(logger) # Rails 3.2.X
         allow_any_instance_of(::Rails::Rack::Logger).to receive(:logger).and_return(logger)
         dispatch_rails_request("/rails_rack_logger")
-        expect(io.string).to start_with("Started GET \"/rails_rack_logger\" for 123.456.789.10 @timber.io {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\"")
+        expect(io.string).to start_with("Started GET \"/rails_rack_logger\" for 123.456.789.10 @metadata {\"level\":\"info\",\"dt\":\"2016-09-01T12:00:00.000000Z\"")
         expect(io.string).to include("\"event\":{\"server_side_app\":{\"http_request\":{\"host\":\"example.org\",\"method\":\"GET\",\"path\":\"/rails_rack_logger\",\"port\":80,\"headers\":{\"remote_addr\":\"123.456.789.10\",\"request_id\":\"unique-request-id-1234\"}}}")
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timber
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Timber Technologies, Inc.