honeycomb-beeline 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8226a2444f449e489670d844e544ec8986ff40b32016ae9199031ae2fef1df8
-  data.tar.gz: 11e5d5f9dc8dcc000e6a4cdb5dbebd35f0fe332c9ff5ab0a85f4b084f428f7bd
+  metadata.gz: 32263488f94bb0aa40611cb4706d001d62885b4de58f86ecd3ce8ccc0416cbc3
+  data.tar.gz: 53b773d27af7256c876009a824b8855418d80faa460815a5a3c54febe8ac6514
 SHA512:
-  metadata.gz: 5370b82bf792605cf79bcf67a5930a0430f498e84f0472e5046b3a027d52761d0fbc3410b21374a2fc32c61beb20738defa47db30a80a650b9ede888b09bc13a
-  data.tar.gz: c70d4cd7b0ea59c6642286db68b38bd0c637715e5468bfa096c8684486d93bcbebb0b7b037be01bb440f10c645199465a6500dfd54ab62fb602e467dea017a46
+  metadata.gz: 2bbb53742e2b9ccd2392893a260ce17d74e27eb46d9e20a9f56e60a0fca910cd5007734880a36d825f33ad188917a02dbb3d7dbf754e9950abfa04fb6a07b67e
+  data.tar.gz: 635c9e858d1393f4cd61ecbe375faeb60fc5b6bcdf8727fea662b10562371334a607e2ec757bc96cc9ec157c2f73bf828a586547de7091c0f5c47a8f0d685c4d

data/README.md

@@ -4,15 +4,21 @@ 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.
 
-## Setup
+Sign up for a [Honeycomb trial](https://ui.honeycomb.io/signup) to obtain a
+writekey before starting.
+
+## Installation
 
-Setup requires minimal changes to your app. First add this line to your Gemfile:
+Add `honeycomb-beeline` to your Gemfile:
 
 ```ruby
 gem 'honeycomb-beeline'
 ```
+Now run `bundle install` to install the gem.
 
-Then in your app's startup script - e.g. for a Rack app "config.ru" is a good
+## Setup
+
+In your app's startup script - e.g. for a Rack app "config.ru" is a good
 place - add the following code:
 
 ```ruby
@@ -21,8 +27,6 @@ require 'honeycomb-beeline'
 Honeycomb.init
 ```
 
-Now run `bundle install` to install the gem.
-
 ## Configuration
 
 You'll need to configure your Honeycomb writekey so that your app can
@@ -51,13 +55,160 @@ Honeycomb.init(writekey: '<MY HONEYCOMB WRITEKEY>', dataset: '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.
 
-## Development
+## Example questions
+
+Now your app is instrumented and sending events, try using Honeycomb to ask
+these questions:
+
+ * Which of my app's routes are the slowest?
+```
+BREAKDOWN: request.path
+CALCULATE: P99(duration_ms)
+FILTER: type == http_server
+ORDER BY: P99(duration_ms) DESC
+```
+ * Where's my app spending the most time?
+```
+BREAKDOWN: type
+CALCULATE: SUM(duration_ms)
+ORDER BY: SUM(duration_ms) DESC
+```
+ * Which users are using the endpoint that I'd like to deprecate? First add a
+   [custom field](#adding-additional-context) `user.email`, then try:
+```
+BREAKDOWN: app.user.email
+CALCULATE: COUNT
+FILTER: request.path == /my/deprecated/endpoint
+```
+
+## Example event
+
+Here is an example of an `http_server` event (recording that your web app
+processed an incoming HTTP request) emitted by the Beeline:
+
+```json
+{
+  "meta.beeline_version": "0.2.0",
+  "meta.local_hostname": "killerbee",
+  "service_name": "my-test-app",
+  "meta.package": "rack",
+  "meta.package_version": "1.3",
+  "type": "http_server",
+  "name": "GET /dashboard",
+  "request.method": "GET",
+  "request.path": "/dashboard",
+  "request.protocol": "https",
+  "request.http_version": "HTTP/1.1",
+  "request.host": "my-test-app.example.com",
+  "request.remote_addr": "172.217.1.238",
+  "request.header.user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36",
+  "trace.trace_id": "b694512a-833f-4b35-be5f-6c742ba18e12",
+  "trace.span_id": "c35cc326-ed90-4881-a4a8-68526d252f2e",
+  "response.status_code": 200,
+  "duration_ms": 303.057396
+}
+```
+
+## Adding additional context
+
+The Beeline will automatically instrument your incoming HTTP requests, database
+queries and outbound HTTP requests to send events to Honeycomb. However, it can
+be very helpful to extend these events with additional context specific to your
+app.  You can add your own fields by calling `Rack::Honeycomb.add_field`. For
+example, this snippet shows how to associate the currently logged-in user with
+each `http_server` event:
+
+```ruby
+get '/hello' do
+  user = authenticate_user()
+
+  # this will add a custom field 'app.user.email' to the http_server event
+  Rack::Honeycomb.add_field(env, 'user.email', user.email)
+
+  "Hello, #{user.name}!"
+end
+```
+
+## Instrumented packages
+
+The Beeline will automatically send the following events if you are using one of
+the listed packages:
+
+### `http_server` (incoming HTTP requests)
+
+* [Sinatra](http://sinatrarb.com) - via [rack-honeycomb](https://github.com/honeycombio/rack-honeycomb)
+* Any other [Rack](https://rack.github.io)-based web app - via [rack-honeycomb](https://github.com/honeycombio/rack-honeycomb) (requires manually adding the middleware)
+
+### `db` (database queries)
+
+* [ActiveRecord](https://rubygems.org/gems/activerecord) - via
+  [activerecord-honeycomb](https://github.com/honeycombio/activerecord-honeycomb)
+* [Sequel](https://sequel.jeremyevans.net/) - via
+  [sequel-honeycomb](https://github.com/honeycombio/sequel-honeycomb)
+
+### `http_client` (outbound HTTP requests)
+
+* [Faraday](https://github.com/lostisland/faraday) - via
+  [faraday-honeycomb](https://github.com/honeycombio/faraday-honeycomb)
+
+## Known limitations
+
+ * The Beeline will try to autodetect your web framework and automatically
+   install its middleware. Currently this only works for Sinatra apps, and
+   also fails in some more exotic configurations of Sinatra. If you find you
+   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
+   integration](https://github.com/honeycombio/honeycomb-rails).
+ * Alternative concurrency models such as EventMachine or Celluloid are not
+   currently supported.
+
+If support for one of these scenarios is important to you, please [let us
+know](#get-in-touch)!
+
+## Troubleshooting
 
-### Releasing a new version
+If you've setup the Beeline as above but you aren't seeing data for your app in
+Honeycomb, or you're seeing errors on startup, here are a few things to try:
 
-Travis will automatically upload tagged releases to Rubygems. To release a new
-version, run
+### Debug mode
+
+To verify the Beeline is working as expected, try running it in debug mode:
+
+```ruby
+Honeycomb.init(debug: true)
 ```
-bump patch --tag   # Or bump minor --tag, etc.
-git push --follow-tags
+
+Alternatively, you can also enable debug mode with no code changes by setting
+`HONEYCOMB_DEBUG=true` in your environment.
+
+In debug mode, the Beeline will not send any events to Honeycomb, but will
+instead print them to your app's standard error. It will also log startup
+messages to standard error.
+
+### Logging
+
+By default the Beeline will log errors but otherwise keep quiet. To see more
+detail about what it's doing, you can pass a logger object (compliant with the
+[stdlib Logger API](https://ruby-doc.org/stdlib-2.4.1/libdoc/logger/rdoc/)) to
+`Honeycomb.init`:
+
+```ruby
+require 'logger'
+logger = Logger.new($stderr)
+logger.level = :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.
+
+### 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
+[contributions](https://github.com/honeycombio/beeline-ruby/blob/master/CONTRIBUTING.md).

data/lib/honeycomb/beeline/version.rb

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

data/lib/honeycomb/client.rb

@@ -2,6 +2,7 @@ require 'honeycomb/beeline/version'
 
 require 'libhoney'
 
+require 'logger'
 require 'socket'
 
 module Honeycomb
@@ -16,14 +17,19 @@ module Honeycomb
       dataset: ENV['HONEYCOMB_DATASET'],
       service_name: ENV['HONEYCOMB_SERVICE'] || dataset,
       without: [],
+      debug: ENV.key?('HONEYCOMB_DEBUG'),
       logger: nil,
       **options
     )
       reset
 
-      @logger = logger
       @without = without
       @service_name = service_name
+      @logger = logger || Logger.new($stderr).tap {|l| l.level = Logger::WARN }
+      @debug = debug
+      if debug
+        @logger ||= Logger.new($stderr)
+      end
 
       options = options.merge(writekey: writekey, dataset: dataset)
       @client = new_client(options)
@@ -40,11 +46,17 @@ module Honeycomb
       client = options.delete :client
 
       options = {user_agent_addition: USER_AGENT_SUFFIX}.merge(options)
-      client ||= begin
-        unless options[:writekey] && options[:dataset]
-          raise ArgumentError, "must specify writekey and dataset"
+      if @debug
+        raise ArgumentError, "can't specify both client and debug options", caller if client
+        @logger.info 'logging events to standard error instead of sending to Honeycomb' if @logger
+        client = Libhoney::LogClient.new(verbose: true, **options)
+      else
+        client ||= if options[:writekey] && options[:dataset]
+          Libhoney::Client.new(options)
+        else
+          @logger.warn "#{self.name}: no #{options[:writekey] ? 'dataset' : 'writekey'} configured, disabling sending events" if @logger
+          Libhoney::NullClient.new(options)
         end
-        Libhoney::Client.new(options)
       end
       client.add_field 'meta.beeline_version', Beeline::VERSION
       client.add_field 'meta.local_hostname', Socket.gethostname rescue nil
@@ -56,9 +68,11 @@ module Honeycomb
       raise ArgumentError unless block_given?
 
       hook = if block.arity == 0
-               ->(_) { block.call }
-             elsif block.arity > 1
-               raise ArgumentError, 'Honeycomb.after_init block should take 1 argument'
+               ->(_, _) { block.call }
+             elsif block.arity == 1
+               ->(client, _) { block.call client }
+             elsif block.arity > 2
+               raise ArgumentError, 'Honeycomb.after_init block should take 2 arguments'
              else
                block
              end
@@ -87,6 +101,7 @@ module Honeycomb
       @logger = nil
       @without = nil
       @service_name = nil
+      @debug = nil
       @client = nil
       @initialized = false
     end
@@ -100,14 +115,14 @@ module Honeycomb
       if @without.include?(label)
         @logger.debug "Skipping hook '#{label}' due to opt-out" if @logger
       else
-        block.call @client
+        block.call @client, @logger
       end
     rescue => e
-      warn "Honeycomb.init hook '#{label}' raised #{e.class}: #{e}"
+      @logger.warn "Honeycomb.init hook '#{label}' raised #{e.class}: #{e}" if @logger
     end
   end
 
-  after_init :log do
-    @logger.info "Honeycomb inited" if @logger
+  after_init :log do |_, logger|
+    logger.info "Honeycomb inited" if logger
   end
 end

data/lib/honeycomb/instrumentations.rb

@@ -15,10 +15,12 @@ module Honeycomb
 
   INSTRUMENTATIONS.each do |instrumentation|
     auto = instrumentation::AutoInstall
-    if auto.available?
-      hook_label = instrumentation.name.sub(/::Honeycomb$/, '').downcase.to_sym
-      after_init(hook_label) do |client|
-        auto.auto_install!(honeycomb_client: client, logger: @logger)
+    hook_label = instrumentation.name.sub(/::Honeycomb$/, '').downcase.to_sym
+    after_init(hook_label) do |client, logger|
+      if auto.available?(logger: logger)
+        auto.auto_install!(honeycomb_client: client, logger: logger)
+      else
+        logger.debug "Not autoinitialising #{instrumentation.name}" if logger
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: honeycomb-beeline
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sam Stokes
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-30 00:00:00.000000000 Z
+date: 2018-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: libhoney
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.6.0
+        version: 1.8.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.6.0
+        version: 1.8.1
 - !ruby/object:Gem::Dependency
   name: activerecord-honeycomb
   requirement: !ruby/object:Gem::Requirement