l2meter 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b8cfc00c1a6cbda74012122b4e767ae10e8721d
-  data.tar.gz: 6f9e05a2828f438d5a7105bbca3cd78ce4b78fc9
+  metadata.gz: 865b41102fd7ebcd25b127d1e1bdd4d3a777fa05
+  data.tar.gz: cfd0071e73ec174fda966428c1f9421f8db1758f
 SHA512:
-  metadata.gz: b067f592722b372bfd78ff272a72fa50adb5adf73a169db08d5084c98888e51d803f707dd73511f38ddc1c2f6e44997376d9b920719cd13c666ab3ce42a31762
-  data.tar.gz: 222b0436a4c08bc6cd7f5dbfd58cb2ddb64f7ddca2b60d7f45eecfc8e8f3994ec6cffdb91bc4fee49d6096843f2efe7ab0ca5e60f703ac82a540e99f631ae962
+  metadata.gz: afebdeaec22a78f58b14b66156e0804a961c34f84b0cced488c0185d90acba204d9921bd904522a5a58720bc29ea6207432afd5ead81b3f758e20e609a083383
+  data.tar.gz: 1eb3117c0347549685dd6cb4b0ac4b85bf2d02656a533b928509c88467c6e9f8bb72ea736ec5d34ef09ef5a37d1eabafd3b7f21e3a5f77f9af63f4945877afd1

data/README.md

@@ -1,35 +1,185 @@
 # L2meter
+[![Gem Version](https://img.shields.io/gem/v/l2meter.svg)](https://rubygems.org/gems/l2meter)
+[![Build Status](https://img.shields.io/travis/heroku/l2meter.svg)](http://travis-ci.org/heroku/l2meter)
+[![Code Climate](https://img.shields.io/codeclimate/github/heroku/l2meter.svg)](https://codeclimate.com/github/heroku/l2meter)
 
-L2meter is a little gem that helps you build loggers that outputs things in l2met format.
+L2meter is a little gem that helps you build loggers that outputs things in
+l2met-friendly format.
 
-### Usage
+### Basics
+
+A new logger might be created like so:
+
+```ruby
+metrics = L2meter.build
+```
+
+If you plan to use it globally across different components of your app,consider
+making it constant.
+
+The base `log` method accepts two type of things: bare values and key-value
+pairs in form of hashes.
 
 ```ruby
-Metrics = L2meter.build do |config|
-  # sort output tokens, false by default
-  config.sort = true
+metrics.log "Hello world"                 # => hello-world
+metrics.log :db_query, result: :success   # => db-query result=success
+```
+
+It can also take a block. In this case the message will be emitted twice, once
+at the start of the execution and another at the end. The end result might look
+like so:
 
-  # default context
-  config.context = { name: "my-app-name" }
+```ruby
+metrics.log :doing_work do            # => doing-work at=start
+  do_some_work                        #
+  metrics.log :work_done              # => work-done
+end                                   # => doing-work at=finish elapsed=1.2345s
+```
 
-  # ... or dynamic context
-  config.context do
-    { random_thing: SecureRandom.uuid }
+In case the exception is raised inside the block, l2meter will report is like
+so:
+
+```ruby
+metrics.log :doing_work do  # => doing-work
+  raise ArgumentError, \    #
+    "something is wrong"    #
+end                         # => doing-work at=exception exception=ArgumentError message="something is wrong" elapsed=1.2345s
+```
+
+## Context
+
+L2meter allows setting context for a block. It might work something like this:
+
+```ruby
+def do_work_with_retries
+  attempt = 1
+  begin
+    metrics.context attempt: attempt do
+      do_some_work            # => doing-work attempt=1
+                              # => doing-work attempt=2
+                              # => doing-work attempt=3
+    end
+  rescue => error
+    attempt += 1
+    retry
   end
+end
+```
 
-  # $stdout by default
-  config.output = StringIO.new
+L2meter supports dynamic contexts as well. You can pass a proc instead of raw
+value in porder to use it.
+
+The same example as above could be written like ths instead:
+
+```ruby
+def do_work_with_retries
+  attempt = 1
+  metrics.context ->{{ attempt: attempt }} do
+    begin
+      do_some_work
+    rescue => error
+      attempt +=1
+      retry
+    end
+  end
 end
+```
+
+## Other
+
+Some other l2met-specific methods are supported.
+
+```ruby
+metrics.count :user_registered             # => count#user-registered=1
+metrics.count :registered_users, 10        # => count#registered-users=10
 
-Metrics.log "Hello world"                 # => hello-world
+metrics.measure :connection_count, 20,     # => measure#connection-count=235
+metrics.measure :db_query, 235, unit: :ms, # => measure#db-query.ms=235
+
+metrics.sample :connection_count, 20,      # => sample#connection-count=235
+metrics.sample :db_query, 235, unit: :ms,  # => sample#db-query.ms=235
+
+metrics.unique :user, "bob@example.com"    # => unique#user=bob@example.com
+```
+
+### Configuration
+
+L2meter supports configurtion. Here's how you cna configure things:
+
+```ruby
+metrics = L2meter.build do |config|
+  # configuration happen here
+end
+```
 
-Metrics.log :foo, :bar, fizz: :buzz       # => foo bar fizz=buzz
+These are available configuration:
 
-Metrics.log :doing_work do                # => doing-work at=start
-  do_some_work                            #
-end                                       # => doing-work at=finish elapsed=3.1234s
+#### Global context
 
-Metrics.log :deez_nutz do                 # => deez-nutz at=start
-  raise ArgumentError, "error here"       #
-end                                       # => deez-nutz at=exception exception=ArgumentError message="error here" elapsed=1.2345s
+Global context works similary to context method, but globally:
+
+```ruby
+config.context = { app_name: "my-app-name" }
+
+# ...
+
+metrics.log foo: :bar # => app-name=my-app-name foo-bar
+```
+
+Dynamic context is also supported:
+
+```ruby
+context.context do
+  { request_id: CurrentContext.request_id }
+end
+```
+
+#### Sorting
+
+By default l2meter doesn't sort tokens before output, putting them in the order
+they're passed. But you can make it sorted like so:
+
+```ruby
+config.sort = true
+
+# ...
+
+metrics.log :c, :b, :a  # => a b c
+```
+
+#### Source
+
+Source is a special parameter that'll be appended to all emitted messages.
+
+```ruby
+config.source = "production"
+
+# ...
+
+metrics.log foo: :bar # => source=production foo=bar
+```
+
+## Silence
+
+There's a way to temporary silence the log emitter. This might be userful for
+tests for example.
+
+```ruby
+metrics.silence do
+  # logger is completely silenced
+  metrics.log "hello world" # nothing is emitted here
+end
+
+# works normally again
+metrics.log :foo            # => foo
+```
+
+The typical setup for RSpec might look like this:
+
+```ruby
+RSpec.configure do |config|
+  config.around :each do |example|
+    Metrics.silence &example
+  end
+end
 ```

data/lib/l2meter/configuration.rb

@@ -1,6 +1,12 @@
 module L2meter
   class Configuration
     attr_writer :output
+    attr_accessor :source
+    attr_reader :contexts
+
+    def initialize
+      @contexts = []
+    end
 
     def output
       @output ||= $stdout
@@ -8,7 +14,7 @@ module L2meter
 
     def key_formatter
       @key_formatter ||= ->(key) do
-        key.to_s.strip.downcase.gsub(/[^-a-z\d]+/, ?-)
+        key.to_s.strip.downcase.gsub(/[^-a-z\d.#]+/, ?-)
       end
     end
 
@@ -36,16 +42,11 @@ module L2meter
     end
 
     def context(&block)
-      @context_block = block
-    end
-
-    def context=(value)
-      @static_context = value
+      @contexts = [block]
     end
 
-    def get_context
-      return @static_context if @static_context
-      @context_block ? @context_block.call.to_h : {}
+    def context=(block_or_value)
+      @contexts = [block_or_value]
     end
   end
 end

data/lib/l2meter/emitter.rb

@@ -6,10 +6,12 @@ module L2meter
       @configuration = configuration
     end
 
-    def log(*args, **params)
+    def log(*args)
+      params = Hash === args.last ? args.pop : {}
       args = args.map { |key| [ key, true ] }.to_h
       params = args.merge(params)
-      params = context.merge(params)
+      params = current_context.merge(params)
+      params = merge_source(params)
 
       if block_given?
         wrap params, &Proc.new
@@ -26,23 +28,75 @@ module L2meter
       configuration.output = output
     end
 
+    def measure(metric, value, unit: nil)
+      metric = [metric, unit].compact * ?.
+      log_with_prefix :measure, metric, value
+    end
+
+    def sample(metric, value, unit: nil)
+      metric = [metric, unit].compact * ?.
+      log_with_prefix :sample, metric, value
+    end
+
+    def count(metric, value=1)
+      log_with_prefix :count, metric, value
+    end
+
+    def unique(metric, value)
+      log_with_prefix :unique, metric, value
+    end
+
+    def context(hash_or_proc)
+      configuration_contexts.push hash_or_proc
+      yield
+    ensure
+      configuration_contexts.pop
+    end
+
     private
 
-    def context
-      configuration.get_context
+    def configuration_contexts
+      configuration.contexts
+    end
+
+    def merge_source(params)
+      source = configuration.source
+      source ? { source: source }.merge(params) : params
+    end
+
+    def current_context
+      configuration_contexts.inject({}) do |result, c|
+        current = c.respond_to?(:call) ? c.call.to_h : c.clone
+        result.merge(current)
+      end
+    end
+
+    def format_value(value)
+      configuration.value_formatter.call(value)
+    end
+
+    def format_key(key)
+      configuration.key_formatter.call(key)
+    end
+
+    def format_keys(params)
+      params.inject({}) do |normalized, (key, value)|
+        normalized.tap { |n| n[format_key(key)] = value }
+      end
     end
 
     def write(params)
-      tokens = params.map do |key, value|
-        key = configuration.key_formatter.call(key)
-        next key if value == true
-        value = configuration.value_formatter.call(value)
-        [ key, value ] * ?=
+      tokens = format_keys(params).map do |key, value|
+        value == true ? key : [ key, format_value(value) ] * ?=
       end
 
       tokens.sort! if configuration.sort?
 
-      configuration.output.puts tokens.join(" ")
+      configuration.output.print tokens.join(" ") + "\n"
+    end
+
+    def log_with_prefix(prefix, key, value)
+      log Hash["#{prefix}##{key}", value]
     end
 
     def wrap(params)

data/lib/l2meter/version.rb

@@ -1,3 +1,3 @@
 module L2meter
-  VERSION = "0.0.2".freeze
+  VERSION = "0.0.3".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: l2meter
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Pavel Pravosud
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-10 00:00:00.000000000 Z
+date: 2015-09-15 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: