influxdb-rails 1.0.0.beta3 → 1.0.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8e24e0318b414fc061b67a99de2cacebd24be2b383475367262e8538a36091e
-  data.tar.gz: b5f8f6bf8e22f7deeeb49412c2728ef6d0271e8ba4d987a410e3c07daf928f72
+  metadata.gz: 2461ed02fc4166901dc276517fc631e5adc65f80c0dd3443e76c2339432315d9
+  data.tar.gz: 2e7073aeb190f52ac858696a52c92078dbe685282ff7689ac477dd9bc20cfa90
 SHA512:
-  metadata.gz: 5d3d4fae5ac74cb363ae2eb8cb8370172ba924ef8a131320e26d48fa1517e0a8f885407eaf27210c2c8bf37a55b076b4b43c41ce5ec51e3a87b78443d8ecee90
-  data.tar.gz: 8b531e4b1b9a1dc3d40c6e2661a5249844f6183b86cc1f763bd51bb844642b1e51aa1cc3f363272f9a79e8148faa1b5ba3a948074341c969c9b9b63c341edd52
+  metadata.gz: fba1e70ddf5caf88cb5432788339a0a311c742a990700ecc9c26fdc7a4f60078faaa7ca042d3e15642465ab0f39e3feba80ac0914f2039024cb793318bd0a551
+  data.tar.gz: 47f43debfcc01f18887b33bcbeaa6cda34dfc63a3eed465abc848d61249080fdb74e1041c04ccfc9e37b3c4d4cc1482db215d88d58ab95423698d3d5b35814e4

data/.rubocop.yml

@@ -32,6 +32,7 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Exclude:
   - 'spec/**/*.rb'
+  - 'influxdb-rails.gemspec'
 
 Metrics/LineLength:
   Max: 100
@@ -51,6 +52,10 @@ Naming/UncommunicativeMethodParamName:
 Naming/FileName:
   Exclude:
   - lib/influxdb-rails.rb
+  - sample-dashboard/Rakefile
+
+Style/Documentation:
+  Enabled: false
 
 Style/FormatStringToken:
   Enabled: false

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 For the full commit log, [see here](https://github.com/influxdata/influxdb-rails/commits/master).
 
+## v1.0.0.beta4, unreleased
+
+- Introduces a Sample Grafana Dashboard + docker-compose demo (#75/#79, @hennevogel)
+- Redesign Measurement Output (#66, @dmke, @ChrisBr, @hennevogel)
+  - Switching from emitting eight different measurements to one called `rails`
+    to support easier aggregation across data, to simplify configuration and to
+    stay closer to the InfluxDB/Grafana nomenclature.
+- Introduced configuration option `ignored_hooks` to disable specifc hooks
+- Enable SQL subscriber by default
+  - Set a default location (:raw) for SQL subscriber
+- Add dynamic values (#65, @ChrisBr)
+- Remove empty tags (#64, @ChrisBr)
 
 ## v1.0.0.beta3, released 2019-01-07
 
@@ -10,7 +22,6 @@ For the full commit log, [see here](https://github.com/influxdata/influxdb-rails
   some tags to values (#63, @ChrisBr)
 - Remove SCHEMA queries from SQL instrumentation (#61, @ChrisBr)
 
-
 ## v1.0.0.beta2, released 2018-12-07
 
 - Added `tags_middleware` config option (#47, @Kukunin)
@@ -31,15 +42,6 @@ For the full commit log, [see here](https://github.com/influxdata/influxdb-rails
 
 - Support for Ruby <= 2.2.x has been removed
 - Support for Rails <= 4.1.x has been removed
-- Changed keys for exceptions (#43, @vassilevsky & @kkentzo)
-  - Exception message and backtrace are now InfluxDB values (changed from tags).
-  - The keys changed from `message` to `exception_message` and from
-    `backtrace` to `exception_backtrace`, since a single shard does not
-    allow for tags and values to share the same key
-  - To convert existing exception traces into the new format for
-    consistency, see [this gist][migrate].
-- Removed `time` key from InfluxDB::Rails::ExceptionPresenter#context`
-  - use `InfluxDB::Rails.current_timestamp` directly
 - Removed previously deprecated methods:
   - `InfluxDB::Rails::Configuration#reraise_global_exceptions`
   - `InfluxDB::Rails::Configuration#database_name`

data/README.md

@@ -13,100 +13,142 @@ metrics directly into [InfluxDB](http://influxdb.org/).
 
 This gem is designed for Rails 4.2+, Ruby 2.3+ and InfluxDB 0.9+.
 
+## Table of contents
+
+- [Installation](#installation)
+- [Usage](#installation)
+- [Configuration](#configuration)
+- [Demo](#demo)
+- [FAQ](#frequently-asked-questions)
+- [Contributing](#contributing)
 
 ## Installation
 
-```
-$ [sudo] gem install influxdb-rails
+Add the gem to your `Gemfile`:
+
+```console
+echo 'gem "influxdb-rails"' >>Gemfile
+bundle install
 ```
 
-Or add it to your `Gemfile`, etc.
+To get things set up, create an initializer:
 
+```console
+bundle exec rails generate influxdb
+```
+
+This creates a file `config/initializers/influxdb_rails.rb`, which allows
+configuration of this gem.
 
 ## Usage
 
-To get things set up, just create an initializer:
+Out of the box, you'll automatically get reporting for sql, model, view and
+controller Rails instrumentation for every request.
 
-```
-$ cd /to/you/rails/application
-$ touch config/initializers/influxdb_rails.rb
+### Action Controller
+
+Reported ActiveSupport instrumentation hooks:
+
+- [start\_processing.action\_controller](https://guides.rubyonrails.org/active_support_instrumentation.html#start-processing-action-controller)
+- [process\_action.action\_controller](https://guides.rubyonrails.org/active_support_instrumentation.html#process-action-action-controller)
+
+Reported values:
+
+```ruby
+  controller: 48.467,
+  view: 46.848
+  db: 0.157,
+  started: 1465839830100400200
+  request_id: "d5bf620b-3494-425b-b7e1-4953597ea744"
 ```
 
-In this file, you can configure the `InfluxDB::Rails` adapter. The default
-config should look something like this:
+Reported tags:
 
-``` ruby
-InfluxDB::Rails.configure do |config|
-  config.influxdb_database = "rails"
-  config.influxdb_username = "root"
-  config.influxdb_password = "root"
-  config.influxdb_hosts    = ["localhost"]
-  config.influxdb_port     = 8086
-
-  # config.retry = false
-  # config.async = false
-  # config.open_timeout = 5
-  # config.read_timeout = 30
-  # config.max_delay = 300
-  # config.time_precision = 'ms'
-
-  # config.tags_middleware = ->(tags) { tags }
-
-  # config.series_name_for_controller_runtimes = "rails.controller"
-  # config.series_name_for_view_runtimes       = "rails.view"
-  # config.series_name_for_db_runtimes         = "rails.db"
-  # config.series_name_for_render_template     = "rails.render_template"
-  # config.series_name_for_render_partial      = "rails.render_partial"
-  # config.series_name_for_render_collection   = "rails.render_collection"
-  # config.series_name_for_sql                 = nil
-  # config.series_name_for_exceptions          = "rails.exceptions"
-  # config.series_name_for_instrumentation     = "instrumentation"
-
-  # Set the application name to something meaningful, by default we
-  # infer the app name from the Rails.application class name.
-  # config.application_name = Rails.application.class.parent_name
-end
+```ruby
+{
+  hook:        "process_action",
+  server:      Socket.gethostname,
+  app_name:    configuration.application_name,
+  method:      "PostsController#index",
+  http_method: "GET",
+  format:      "html",
+  status:      "200"
+}
 ```
 
-To see all default values, take a look into `InfluxDB::Rails::Configuration::DEFAULTS`,
-defined in `lib/influxdb/rails/configuration.rb`
+### Action View
+
+Reported ActiveSupport instrumentation hooks:
 
-Out of the box, you'll automatically get reporting of your controller,
-view, and db runtimes and rendering of template, partial and collection for each request.
-Reporting of SQL queries is disabled by default because it is still in experimental mode
-and currently requires String parsing which might cause performance issues on query
-intensive applications. You can enable it by setting the `series_name_for_sql`
-configuration.
+- [render\_template.action\_view](https://guides.rubyonrails.org/active_support_instrumentation.html#render-template-action-view)
+- [render\_partial.action\_view](https://guides.rubyonrails.org/active_support_instrumentation.html#render-partial-action-view)
+- [render\_collection.action\_view](https://guides.rubyonrails.org/active_support_instrumentation.html#render-collection-action-view)
 
-It is possible to disable the rendering series by setting the series_name to nil.
+Reported values:
 
 ```ruby
-  # config.series_name_for_render_template     = nil
-  # config.series_name_for_render_partial      = nil
-  # config.series_name_for_render_collection   = nil
+  value: 48.467,
+  count: 3,
+  cache_hits: 0,
+  request_id: "d5bf620b-3494-425b-b7e1-4953597ea744"
 ```
 
-You can also call through to the underlying `InfluxDB::Client` object to write arbitrary data.
-If you do that, it might be usefull to add the current context to these custom data points which can get
-accessed with ``InfluxDB::Rails.current.location``.
+Reported tags:
 
+```ruby
+  hook:       ["render_template", "render_partial", "render_collection"]
+  server:     Socket.gethostname,
+  app_name:   configuration.application_name,
+  location:   "PostsController#index",
+  filename:   "/some/file/action.html",
+```
 
-``` ruby
-InfluxDB::Rails.client.write_point "events",
-  tags:   { url: "/foo", user_id: current_user.id, location: InfluxDB::Rails.current.location },
-  values: { value: 0 }
+### Active Record
+
+Reported ActiveSupport instrumentation hooks:
+
+- [sql.active\_record](https://guides.rubyonrails.org/active_support_instrumentation.html#sql-active-record)
+
+Reported values:
+
+```ruby
+  sql: "SELECT \"posts\".* FROM \"posts\"",
+  request_id: "d5bf620b-3494-425b-b7e1-4953597ea744"
 ```
 
-Additional documentation for `InfluxDB::Client` lives in the
-[influxdb-ruby](http://github.com/influxdata/influxdb-ruby) repo.
+Reported tags:
 
+```ruby
+  hook:       "sql",
+  server:     Socket.gethostname,
+  app_name:   configuration.application_name,
+  location:   "PostsController#index",
+  operation:  "SELECT",
+  class_name: "POST",
+  name:       "Post Load"
+```
+
+## Configuration
+
+The only setting you actually need to configure is the name of the database
+within the InfluxDB server instance (don't forget to create this database!).
+
+```ruby
+InfluxDB::Rails.configure do |config|
+  config.client.database = "rails"
+end
+```
 
-### Tags
+You'll find *most* of the configuration settings in the initializer file. The
+canonical list of default values is located in `lib/influxdb/rails/configuration.rb`
+(`InfluxDB::Rails::Configuration::DEFAULTS`).
+
+### Custom Tags
 
 You can modify the tags sent to InfluxDB by defining a middleware, which
-receives the current tag set (`Hash` with `Symbol` keys and `String`
-values) as argument and returns a hash in the same form. The middleware
-can be any object, as long it responds to `#call` (like a `Proc`):
+receives the current tag set as argument and returns a hash in the same
+form. The middleware can be any object, as long it responds to `#call`
+(like a `Proc`):
 
 ```ruby
 InfluxDB::Rails.configure do |config|
@@ -116,176 +158,159 @@ InfluxDB::Rails.configure do |config|
 end
 ```
 
-If you want to add dynamically tags per request, you can access the ``InfluxDB::Rails.current.tags`` to
-do so. For instance, you could add the current user as tag to every data point.
+The `tags` argument is a Hash (mapping Symbol keys to String values). The
+actual keys and values depend on the series name (`tags[:series]`, see
+next section).
+
+If you want to add dynamically tags or fields *per request*, you can access
+`InfluxDB::Rails.current` to do so. For instance, you could add the current
+user as tag or redis query time to every data point:
 
 ```ruby
 class ApplicationController
+  before_action :set_influx_data
 
-  before_action :set_influx_tags
-
-  def set_influx_tags
+  def set_influx_data
     InfluxDB::Rails.current.tags = { user: current_user.id }
+    InfluxDB::Rails.current.values = { redis_value: redis_value }
   end
 end
-
 ```
 
-By default, the following tags are sent for *non-exception series*
-(`rails.controller`, `rails.view`, `rails.db` and `instrumentation`):
+### Custom client configuration
 
-```ruby
-{
-  method:      "#{payload[:controller]}##{payload[:action]}",
-  server:      Socket.gethostname,
-  app_name:    configuration.application_name,
-  http_method: payload[:method],
-  format:      payload[:format],
-  status:      payload[:status]
-}
-```
-For the render series (``rails.render_partial``, ``rails.render_view`` and ``rails.render_collection``)
+The settings named `config.client.*` are used to construct an `InfluxDB::Client`
+instance, which is used internally to transmit the reporting data points
+to your InfluxDB server. You can access this client as well, and perform
+arbitrary operations on your data:
 
 ```ruby
-  server:     Socket.gethostname,
-  app_name:   configuration.application_name,
-  location:   "#{payload[:controller]}##{payload[:action]}",
-  filename:   payload[:identifier],
-  count:      payload[:count],
-  cache_hits: payload[:cache_hits],
+InfluxDB::Rails.client.write_point "events",
+  tags:   { url: "/foo", user_id: current_user.id, location: InfluxDB::Rails.current.location },
+  values: { value: 0 }
 ```
 
-For the SQL series (``rails.sql``, disabled by default)
-
-```ruby
-  server:     Socket.gethostname,
-  app_name:   configuration.application_name,
-  location:   "#{payload[:controller]}##{payload[:action]}",,
-  operation:  "SELECT",
-  class_name: "USER",
-  name:       payload[:name],
-```
+If you do that, it might be useful to add the current context to these custom
+data points which can get accessed with `InfluxDB::Rails.current.location`.
 
-For more information about the payload, have a look at the [official ActiveSupport documentation](https://guides.rubyonrails.org/active_support_instrumentation.html#process-action-action-controller).
+See [influxdb-ruby](http://github.com/influxdata/influxdb-ruby) for a
+full list of configuration options and detailed usage.
 
+### Disabling hooks
 
-For the exceptions (series name `rails.exceptions`):
+If you are not interested in certain reports you can disable them in the configuration.
 
 ```ruby
-{
-  application_name:   InfluxDB::Rails.configuration.application_name,
-  application_root:   InfluxDB::Rails.configuration.application_root,
-  framework:          InfluxDB::Rails.configuration.framework,
-  framework_version:  InfluxDB::Rails.configuration.framework_version,
-  language:           "Ruby",
-  language_version:   "#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}",
-  custom_data:        @custom_data,
-  class:              @exception.class.to_s,
-  method:             "#{@controller}##{@action}",
-  filename:           File.basename(@backtrace.lines.first.try(:file)),
-  server:             Socket.gethostname,
-  status:             "open",
-}
+InfluxDB::Rails.configure do |config|
+  config.ignored_hooks = ['sql.active_record', 'render_template.action_view']
+end
 ```
 
+## Demo
+Want to see this in action? Check out our [sample dashboard](https://github.com/influxdata/influxdb-rails/tree/master/sample-dashboard).
 
 ## Frequently Asked Questions
 
+### I'm seeing far less requests recorded in InfluxDB than my logs suggest.
 
-**Q: I'm seeing far less requests recorded in InfluxDB than my logs suggest.**
+By default, this gem writes data points with *millisecond time precision*
+to the InfluxDB server. If you have more than 1000 requests/second (and/or
+multiple parallel requests), **only the last** data point (within the
+same tag set) is stored. See [InfluxDB server docs][duplicate-points] for
+further details.
 
-By default, this gem only sends data points with *second time precision*
-to the InfluxDB server. If you experience multiple requests per second,
-**only the last** point (with the same tag set) is stored.
+To work around this limitation, set the `config.client.time_precision`
+to one of `"us"` (microseconds, 1·10<sup>-6</sup>s) or `"ns"` (nanoseconds,
+1·10<sup>-9</sup>s).
 
-See [InfluxDB server docs][duplicate-points] for further details.
-To work around this limitation, set the `config.time_precision` to one
-of `"ms"` (milliseconds, 1·10<sup>-3</sup>s), `"us"` (microseconds,
-1·10<sup>-6</sup>s) or `"ns"` (nanoseconds, 1·10<sup>-9</sup>s).
+Please note: This will only ever reduce the likelihood of data points
+overwriting each other, but not eliminate it completely.
 
 [duplicate-points]: https://docs.influxdata.com/influxdb/v1.4/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points
 
 
-**Q: How does the measurement influence the response time?**
+### How does the measurement influence the response time?
+
+This gem subscribes to various `ActiveSupport::Notifications` hooks.
+(cf. [guide][arn-guide] · [docs][arn-docs] · [impl][arn-impl]). The
+controller notifications are run *after* a controller action has finished,
+and should not impact the response time.
 
-This gem subscribes to the `process_action.action_controller` controller
-notification (via `ActiveSupport::Notifications` · [guide][arn-guide] ·
-[docs][arn-docs] · [impl][arn-impl]), i.e. it runs *after* a controller
-action has finished.
+Other notification hooks (rendering and SQL queries) run *inline* in the
+request processing. The amount of overhead introduced should be negligible,
+though. However reporting of SQL queries relies on Ruby string parsing which
+might cause performance issues on traffic intensive applications. Disable it in
+the configuration if you are not willing to tolerate this.
 
-The thread processing incoming HTTP requests however is blocked until
-the notification is processed. By default, this means calculating and
-enqueueing some data points for later processing (`config.async = true`),
-which usually is negligible. The asynchronuous sending happens in a seperate
-thread, which batches multiple data points.
+By default, this gem performs writes to InfluxDB asynchronously. A single
+hooks usually only performs some time delta calculations, and then enqueues
+the data point into a worker queue (which is processed by a background
+thread).
 
-If you, however, use a synchronous client (`config.async = false`), the
-data points are immediately sent to the InfluxDB server. Depending on
+If you, however, use a synchronous client (`config.client.async = false`),
+the data points are immediately sent to the InfluxDB server. Depending on
 the network link, this might cause the HTTP thread to block a lot longer.
 
 [arn-guide]: http://guides.rubyonrails.org/v5.1/active_support_instrumentation.html#process-action-action-controller
 [arn-docs]: http://api.rubyonrails.org/v5.1/classes/ActiveSupport/Notifications.html
 [arn-impl]: https://github.com/rails/rails/blob/5-1-stable/actionpack/lib/action_controller/metal/instrumentation.rb#L30-L38
 
+### How does this gem handle an unreachable InfluxDB server?
 
-**Q: How does this gem handle an unreachable InfluxDB server?**
-
-By default, the InfluxDB client will retry indefinetly, until a write
-succeedes (see [client docs][] for details). This has two important
-implcations, depending on the value of `config.async`:
+By default, the InfluxDB client will retry indefinitely, until a write
+succeeds (see [client docs][] for details). This has two important
+implications, depending on the value of `config.client.async`:
 
-- if the client runs asynchronously (i.e. in a seperate thread), the queue
-  might fill up with hundrets of megabytes of data points
+- if the client runs asynchronously (i.e. in a separate thread), the queue
+  might fill up with hundreds of megabytes of data points
 - if the client runs synchronously (i.e. inline in the request/response
   cycle), it might block all available request threads
 
-In both cases, your application server might become inresponsive and needs
-to be restarted (which can happen automatically in `cgroups` contexts).
+In both cases, your application server might become unresponsive and needs
+to be restarted (which can happen automatically in `cgroups` contexts,
+like Docker containers).
 
-If you setup a maximum retry value (`Integer === config.retry`), the
-client will try upto that amount of times to send the data to the server
+If you setup a maximum retry value (`Integer === config.client.retry`),
+the client will try up to that amount of times to send the data to the server
 and (on final error) log an error and discard the values.
 
 [client docs]: https://github.com/influxdata/influxdb-ruby#retry
 
-
-**Q: What happens with unwritten points, when the application restarts?**
-
-The data points are simply discarded.
-
-
-**Q: What happens, when the InfluxDB client or this gem throws an exception? Will the user see 500 errors?**
+### What happens, when the InfluxDB client or this gem throws an exception? Will the user see 500 errors?
 
 No. The controller instrumentation is wrapped in a `rescue StandardError`
 clause, i.e. this gem will only write the error to the `client.logger`
 (`Rails.logger` by default) and not disturb the user experience.
 
+### What happens with unwritten points, when the application restarts?
 
-## Testing
-
-```
-git clone git@github.com:influxdata/influxdb-rails.git
-cd influxdb-rails
-bundle
-bundle exec rake
-```
-
+The data points are simply discarded.
 
 ## Contributing
 
-- Fork this repository on GitHub.
-- Make your changes.
+- Fork this repository on GitHub
+- Make your changes
   - Add tests.
   - Add an entry in the `CHANGELOG.md` in the "unreleased" section on top.
 - Run the tests:
   - Either run them manually:
+
     ```console
-    $ rake test:all
+    rake test:all
     ```
+
   - or wait for [Travis][travis-pr] to pick up your changes, *after*
     you made a pull request.
 - Send a pull request.
-  - Please rebase against the master branch.
-- If your changes look good, we'll merge them.
+- If your changes are looking good, we'll merge them.
 
 [travis-pr]: https://travis-ci.org/influxdata/influxdb-rails/pull_requests
+
+### Testing Tasks
+
+```console
+rake            # unit tests + Rubocop linting
+rake spec       # only unit tests
+rake rubocop    # only Rubocop linter
+rake test:all   # integration tests with various Rails version
+```

data/influxdb-rails.gemspec

@@ -4,14 +4,19 @@ require "influxdb/rails/version"
 
 Gem::Specification.new do |spec|
   spec.name        = "influxdb-rails"
-  spec.version     = InfluxDB::Rails::VERSION
-  spec.authors     = ["Dominik Menke", "Todd Persen"]
-  spec.email       = ["dominik.menke@gmail.com", "todd@influxdb.com"]
-  spec.homepage    = "https://influxdata.com"
   spec.summary     = "InfluxDB bindings for Ruby on Rails."
-  spec.description = "This gem automatically instruments your Ruby on Rails" \
-                     " 4.2/5.x applications using InfluxDB for storage."
+  spec.description = "This gem instruments your Ruby on Rails application using InfluxDB."
+  spec.version     = InfluxDB::Rails::VERSION
+  spec.authors     = ["Christian Bruckmayer", "Henne Vogelsang"]
+  spec.email       = ["christian@bruckmayer.net", "hvogel@hennevogel.de"]
   spec.licenses    = ["MIT"]
+  spec.homepage    = "https://influxdata.com"
+  spec.metadata = {
+    "bug_tracker_uri"   => "https://github.com/influxdata/influxdb-rails/issues",
+    "changelog_uri"     => "https://github.com/influxdata/influxdb-rails/blob/master/CHANGELOG.md",
+    "documentation_uri" => "https://github.com/influxdata/influxdb-rails/blob/master/README.md",
+    "source_code_uri"   => "https://github.com/influxdata/influxdb-rails",
+  }
 
   spec.files         = `git ls-files`.split($/) # rubocop:disable Style/SpecialGlobalVars
   spec.test_files    = spec.files.grep(%r{^(test|spec|features|smoke)/})
@@ -25,11 +30,12 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "activerecord"
   spec.add_development_dependency "bundler", ">= 1.0.0"
   spec.add_development_dependency "fakeweb"
+  spec.add_development_dependency "pry"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rdoc"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "rspec-rails", ">= 3.0.0"
   spec.add_development_dependency "rubocop", "~> 0.61.1"
-  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "sqlite3", "1.3.13"
   spec.add_development_dependency "tzinfo"
 end