honeycomb-beeline 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32263488f94bb0aa40611cb4706d001d62885b4de58f86ecd3ce8ccc0416cbc3
-  data.tar.gz: 53b773d27af7256c876009a824b8855418d80faa460815a5a3c54febe8ac6514
+  metadata.gz: e21add8b0fa6f602b348665ff15ef2d0c254323da4a7032d5b87affc31b39c4a
+  data.tar.gz: 265cafe498fcaa56d66d9014bccce32df4cbac1aad2ed855f506fdad44dc2640
 SHA512:
-  metadata.gz: 2bbb53742e2b9ccd2392893a260ce17d74e27eb46d9e20a9f56e60a0fca910cd5007734880a36d825f33ad188917a02dbb3d7dbf754e9950abfa04fb6a07b67e
-  data.tar.gz: 635c9e858d1393f4cd61ecbe375faeb60fc5b6bcdf8727fea662b10562371334a607e2ec757bc96cc9ec157c2f73bf828a586547de7091c0f5c47a8f0d685c4d
+  metadata.gz: db0566fdbb0d953efe40d1daf0eb86f8d4e0670afc4a5db4e63ee8ff6c67233d34aee5a0f6bd837810d686537b1310b3dfa9b1aec9dd5361c7cb92b0a8cdb7da
+  data.tar.gz: 59789661ec027435c01a45ee1aa79c9ff31ea8649a52b10cfc75da665076cb9ab0618b6ac92dd1632251ef0f27bea6ff4b3cd0571fe87233ee3871e30b4e45fe

data/README.md

@@ -1,11 +1,15 @@
 # Honeycomb Beeline for Ruby
 
-The Honeycomb Beeline for Ruby is the fastest path to observability for your
-Ruby apps. It understands the common packages you use and automatically
-instruments them to send useful events to Honeycomb.
+[![Build Status](https://travis-ci.org/honeycombio/beeline-ruby.svg?branch=master)](https://travis-ci.org/honeycombio/beeline-ruby)
+[![Gem Version](https://badge.fury.io/rb/honeycomb-beeline.svg)](https://badge.fury.io/rb/honeycomb-beeline)
 
-Sign up for a [Honeycomb trial](https://ui.honeycomb.io/signup) to obtain a
-writekey before starting.
+The Honeycomb Beeline for Ruby is an easy way to instrument your Ruby web
+application for observability. It understands the common packages you use and
+automatically instruments them to send useful events to
+[Honeycomb](https://www.honeycomb.io).
+
+Requires Ruby 2.2 or later. Sign up for a [Honeycomb
+trial](https://ui.honeycomb.io/signup) to obtain an API key before starting.
 
 ## Installation
 
@@ -18,19 +22,19 @@ Now run `bundle install` to install the gem.
 
 ## Setup
 
-In your app's startup script - e.g. for a Rack app "config.ru" is a good
-place - add the following code:
+In your app's startup script - e.g. config.ru or app.rb - add the following
+code:
 
 ```ruby
 require 'honeycomb-beeline'
 
-Honeycomb.init
+Honeycomb.init # pulls configuration from the environment - see below
 ```
 
 ## Configuration
 
-You'll need to configure your Honeycomb writekey so that your app can
-identify itself to Honeycomb. You can find your writekey on [your Account
+You'll need to configure your Honeycomb API key so that your app can
+identify itself to Honeycomb. You can find your API key on [your Account
 page](https://ui.honeycomb.io/account).
 
 You'll also need to configure the name of a dataset in your Honeycomb account to
@@ -41,7 +45,7 @@ passing arguments to `Honeycomb.init`:
 
 ### Configuration via environment variables
 
- * `HONEYCOMB_WRITEKEY` - specifies the writekey
+ * `HONEYCOMB_WRITEKEY` - specifies the API key (aka "write key")
  * `HONEYCOMB_DATASET` - specifies the dataset
  * `HONEYCOMB_SERVICE` - specifies the name of your app (defaults to the dataset
    name)
@@ -49,11 +53,17 @@ passing arguments to `Honeycomb.init`:
 ### Configuration via code
 
 ```ruby
-Honeycomb.init(writekey: '<MY HONEYCOMB WRITEKEY>', dataset: 'my-app')
+Honeycomb.init(
+  writekey: '<MY HONEYCOMB API KEY>',
+  dataset: 'my-app',
+  service_name: 'my-app'
+)
 ```
 
-Note that you should not check your Honeycomb writekey into version control, as
-it is sensitive and allows sending data to your Honeycomb account.
+Note that Honeycomb API keys have the ability to create and delete data, and
+should be managed in the same way as your other application secrets. For example
+you might prefer to configure production API keys via environment variables,
+rather than checking them into version control.
 
 ## Example questions
 
@@ -159,7 +169,8 @@ the listed packages:
    aren't seeing any events for processing web requests, you can install the
    [middleware](https://www.rubydoc.info/gems/rack-honeycomb) manually: e.g.
    `use Rack::Honeycomb::Middleware`.
- * Rails apps are not supported currently; instead, use our [Rails
+ * Rails apps should work after installing the middleware as above, but are
+   currently better supported by our dedicated [Rails
    integration](https://github.com/honeycombio/honeycomb-rails).
  * Alternative concurrency models such as EventMachine or Celluloid are not
    currently supported.
@@ -197,18 +208,17 @@ detail about what it's doing, you can pass a logger object (compliant with the
 ```ruby
 require 'logger'
 logger = Logger.new($stderr)
-logger.level = :info           # determine how much detail you want to see
+logger.level = Logger::INFO           # determine how much detail you want to see
 Honeycomb.init(logger: logger)
 ```
 
-A level of `:debug` will show you detail about each library being instrumented,
-whereas a level of `:info` will just print a few progress messages.
+A level of `Logger::DEBUG` will show you detail about each library being instrumented,
+whereas a level of `Logger::INFO` will just print a few progress messages.
 
 ### Get in touch
 
 This beeline is still young, so please reach out to
 [support@honeycomb.io](mailto:support@honeycomb.io) or ping us with the chat
-bubble on [our website](https://www.honeycomb.io){target=_blank} for assistance.
-We also welcome [bug
-reports](https://github.com/honeycombio/beeline-ruby/issues) and
+bubble on [our website](https://www.honeycomb.io) for assistance.  We also
+welcome [bug reports](https://github.com/honeycombio/beeline-ruby/issues) and
 [contributions](https://github.com/honeycombio/beeline-ruby/blob/master/CONTRIBUTING.md).

data/lib/honeycomb-beeline.rb

@@ -2,6 +2,12 @@
 
 require 'libhoney'
 
+# Namespace for the Honeycomb Beeline.
+#
+# Call {.init} to initialize the Honeycomb Beeline at app startup.
+module Honeycomb
+end
+
 require 'honeycomb/client'
 require 'honeycomb/instrumentations'
 require 'honeycomb/span'

data/lib/honeycomb/beeline/version.rb

@@ -1,6 +1,6 @@
 module Honeycomb
   module Beeline
     GEM_NAME = 'honeycomb-beeline'
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

data/lib/honeycomb/client.rb

@@ -10,8 +10,45 @@ module Honeycomb
 
   class << self
     attr_reader :client
+    attr_reader :logger
     attr_reader :service_name
 
+    # Initialize the Honeycomb Beeline. You should call this only once, as
+    # early as possible in your app's startup process, to automatically
+    # instrument your app and prepare to send events.
+    #
+    # @example Providing config in code
+    #     Honeycomb.init(
+    #       writekey: '0123face4567cafe8901beef2345feed',
+    #       dataset: 'myapp-development',
+    #       service_name: 'myapp'
+    #     )
+    # @example Providing config via environment variables
+    #     # Assumes environment variables e.g.
+    #     #   HONEYCOMB_WRITEKEY=0123face4567cafe8901beef2345feed
+    #     #   HONEYCOMB_DATASET=myapp-development
+    #     #   HONEYCOMB_SERVICE=myapp
+    #
+    #     Honeycomb.init
+    #
+    # @param writekey [String] (required) the Honeycomb API key (aka "write
+    #     key") - get yours from your {https://ui.honeycomb.io/account Account
+    #     Page}. Can also be specified via the HONEYCOMB_WRITEKEY environment
+    #     variable.
+    # @param dataset [String] (required) the name of the Honeycomb
+    #     {https://docs.honeycomb.io/getting-data-in/datasets/best-practices/
+    #     dataset} your app should send events to. Can also be specified via the
+    #     HONEYCOMB_DATASET environment variable.
+    # @param service_name [String] the name of your app, included in all events
+    #     your app will send. Defaults to the dataset name if not specified. Can
+    #     also be specified via the HONEYCOMB_SERVICE environment variable.
+    # @param debug [Boolean] if true, your app will not send any events to
+    #     Honeycomb, but will instead print them to your app's standard error.
+    #     It will also log diagnostic messages to standard error.
+    # @param logger [Logger] provide a logger to receive diagnostic messages,
+    #     e.g. to override the default logging device or verbosity. By default
+    #     warnings and above will be logged to standard error; under normal
+    #     operation nothing will be logged.
     def init(
       writekey: ENV['HONEYCOMB_WRITEKEY'],
       dataset: ENV['HONEYCOMB_DATASET'],
@@ -42,6 +79,37 @@ module Honeycomb
       @initialized = true
     end
 
+    # Call at app shutdown to ensure all pending events have been sent to
+    # Honeycomb.
+    def shutdown
+      if defined?(@client) && @client
+        @client.close
+      end
+    end
+
+    # Reset the Beeline to a pristine state, ready to be `.init`ed again.
+    # Intended for testing purposes only.
+    #
+    # @api private
+    def reset
+      # TODO encapsulate all this into a Beeline object so we don't need
+      # explicit cleanup
+
+      shutdown
+
+      @logger = nil
+      @without = nil
+      @service_name = nil
+      @debug = nil
+      @client = nil
+      @initialized = false
+    end
+
+    private
+    def after_init_hooks
+      @after_init_hooks ||= []
+    end
+
     def new_client(options)
       client = options.delete :client
 
@@ -85,32 +153,6 @@ module Honeycomb
       end
     end
 
-    def shutdown
-      if defined?(@client) && @client
-        @client.close
-      end
-    end
-
-    # @api private
-    def reset
-      # TODO encapsulate all this into a Beeline object so we don't need
-      # explicit cleanup
-
-      shutdown
-
-      @logger = nil
-      @without = nil
-      @service_name = nil
-      @debug = nil
-      @client = nil
-      @initialized = false
-    end
-
-    private
-    def after_init_hooks
-      @after_init_hooks ||= []
-    end
-
     def run_hook(label, block)
       if @without.include?(label)
         @logger.debug "Skipping hook '#{label}' due to opt-out" if @logger

data/lib/honeycomb/span.rb

@@ -1,10 +1,8 @@
 require 'securerandom'
 
 module Honeycomb
-  module Span
-  end
-
   class << self
+    # @api private
     def with_trace_id(trace_id = SecureRandom.uuid)
       Thread.current[:honeycomb_trace_id] = trace_id
       yield trace_id
@@ -12,10 +10,12 @@ module Honeycomb
       Thread.current[:honeycomb_trace_id] = nil
     end
 
+    # @api private
     def trace_id
       Thread.current[:honeycomb_trace_id]
     end
 
+    # @api private
     def with_span_id(span_id)
       parent_span_id = Thread.current[:honeycomb_span_id]
       Thread.current[:honeycomb_span_id] = span_id
@@ -24,7 +24,7 @@ module Honeycomb
       Thread.current[:honeycomb_span_id] = parent_span_id
     end
 
-    # TODO rethink this API
+    # @api private
     def span(service_name:, name:, span_id: SecureRandom.uuid)
       event = client.event
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: honeycomb-beeline
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sam Stokes
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-01 00:00:00.000000000 Z
+date: 2018-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: libhoney
@@ -239,7 +239,7 @@ description: |2
       Ruby apps. It understands the common packages you use and automatically
       instruments them to send useful events to Honeycomb.
 email:
-- sam@honeycomb.io
+- support@honeycomb.io
 executables: []
 extensions: []
 extra_rdoc_files: []