influxdb-rails 1.0.0.beta2 → 1.0.1.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7b5a411b14d5a465a1a4c503498d8c642de1c818213dfe3e437a1177eefa5d1
-  data.tar.gz: f50dc54acb96ac4e9b758aa5be109ffd40a1396b4e43844800fc670496c1d76c
+  metadata.gz: d47f714f971f95efc094148a585d056fe54cfa5847d30a2e18847ccc87a63f7b
+  data.tar.gz: 16c57b616923500e54755db3116560f7573837cc2c6c663ff1ecaf03b30bc16e
 SHA512:
-  metadata.gz: 123a265d9418ff25a10b469cb798e9ed004af8a679fde861c40f81c5f96a20aea192576d10dfed877293afa6c59412cccb40d0b7fd14e52461aaa76c6712c092
-  data.tar.gz: 6189e83dfce1d8812c0ce8553f3095ee0be21608f71db0375edc1e6aab4cfaf646675d481ed53144056437b853df71a9e9085009fea936384a167bdac41d0433
+  metadata.gz: 957abc17d22ddb564455fa17c3dbb927715dbf44b004bc53da1c71dc405d3d15ca0b9fa7804c7bd0d30e09f68d68bc7b82dcffea9e4c1dd8d07086065d0f6e8f
+  data.tar.gz: 6a8f535427d62b5b7db4830885a26fb8c4ed64ffce7d8b40d2cae618d130829bb6ee5cffcaad34a1443233e4fec5eca154638511b9adf1d96fb61b91c51dda33

data/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  # Enable version updates for bundler
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    allow:
+      - dependency-type: "all"
+    labels:
+      - "dependencies"

data/.gitignore

@@ -8,3 +8,4 @@ pkg/*
 spec/support/rails*/log/*
 .ruby-*
 vendor/bundle
+tmp

data/.rubocop.yml

@@ -11,7 +11,7 @@ AllCops:
   - 'vendor/bundle/**/*'
   DisplayCopNames: true
   StyleGuideCopsOnly: false
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.4
 
 Rails:
   Enabled: false
@@ -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/.travis.yml

@@ -7,26 +7,19 @@ before_install:
   - gem update bundler --no-doc
 rvm:
   - ruby-head
-  - 2.5.3
-  - 2.4.5
-  - 2.3.8
+  - "2.7"
+  - "2.6"
+  - "2.5"
 gemfile:
+  - gemfiles/Gemfile.rails-6.0.x
   - gemfiles/Gemfile.rails-5.2.x
-  - gemfiles/Gemfile.rails-5.1.x
-  - gemfiles/Gemfile.rails-5.0.x
-  - gemfiles/Gemfile.rails-4.2.x
 env:
   - TEST_TASK=spec
 matrix:
   allow_failures:
     - rvm: ruby-head
   include:
-    - { rvm: "2.5.3",   gemfile: "Gemfile", env: [TEST_TASK=rubocop] }
-  exclude:
-    # Rails < 5 not on MRI 2.4+
-    - { rvm: ruby-head, gemfile: "gemfiles/Gemfile.rails-4.2.x" }
-    - { rvm: "2.4.5",   gemfile: "gemfiles/Gemfile.rails-4.2.x" }
-    - { rvm: "2.5.3",   gemfile: "gemfiles/Gemfile.rails-4.2.x" }
+    - { rvm: "2.6",   gemfile: "Gemfile", env: [TEST_TASK=rubocop] }
 addons:
   apt:
     packages:

data/CHANGELOG.md

@@ -2,10 +2,56 @@
 
 For the full commit log, [see here](https://github.com/influxdata/influxdb-rails/commits/master).
 
+## v1.0.1.beta2, released 2020-09-14
+- Implement [`deliver.action_mailer`](https://guides.rubyonrails.org/active_support_instrumentation.html#deliver-action-mailer) subscriber
+- Add missing Active Job documentation
+- Drop support for Ruby 2.4
+- Drop support for Rails < 5.2
+
+## v1.0.1.beta1, released 2020-08-21
+- Drop support for Ruby 2.3
+- Drop support for Rails 4.x
+- Add `auth_method` to client configuration (#96, @anlek)
+- Drop undocumented `instrumentation_enabled` setting, use
+  `ignored_environments` do disable instrumentation
+- Simplified spec with a PORO test client
+- Implement `instantiation.active_record` subscriber (https://guides.rubyonrails.org/active_support_instrumentation.html#instantiation-active-record)
+- Implement `enqueue.active_job` subscriber (https://guides.rubyonrails.org/active_support_instrumentation.html#enqueue-active-job)
+- Implement `perform_start.active_job` subscriber (https://guides.rubyonrails.org/active_support_instrumentation.html#perform-start-active-job)
+- Implement `perform.active_job` subscriber (https://guides.rubyonrails.org/active_support_instrumentation.html#perform-active-job)
+- Implement block instrumentation `InfluxDB::Rails.instrument do; 1 + 1; end`
+- Record unhandled exceptions as tags for process_action.action_controller
+
+## v1.0.0, released 2019-10-23
+The Final release, no code changes.
+
+## v1.0.0.beta5, unreleased
+- Silently eat all dropped configuration options and do not crash
+- Add per action view to the sample dashboard
+
+## v1.0.0.beta4
+
+- 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
+
+- Add dynamic tags (#62, @ChrisBr)
+- Reduce cardinality of resulting InfluxDB measurement by moving
+  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)
+- Added `tags_middleware` config option (#47, @Kukunin)
 - Removed path tag from metrics (introduced with #50), because it
   potentially produces "exceed tag value limit" (#54, @ChrisBr)
 - Added render instrumentation (#53, @ChrisBr)
@@ -23,22 +69,11 @@ 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`
   - `InfluxDB::Rails::Configuration#application_id`
 
-[migrate]: https://gist.github.com/dmke/2d0f4ccf9f43faf82e732dc041e90ca2
-
 ## v0.4.3, released 2017-12-12
 
 - Added `time_precision` config option (#42, @kkentzo)

data/README.md

@@ -1,7 +1,6 @@
-> You are looking at the README for the master branch of this gem.
-> The latest released version lives in the stable-04 branch,
-> [see here](https://github.com/influxdata/influxdb-rails/tree/stable-04#readme)
-> for an online version.
+> :warning: You are looking at the README for the master branch of this gem.
+> See the latest [released version (1.0.0)](https://github.com/influxdata/influxdb-rails/tree/v1.0.0#readme)
+> instead.
 
 # influxdb-rails
 
@@ -13,97 +12,194 @@ 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
 
+Add the gem to your `Gemfile`:
+
+```console
+echo 'gem "influxdb-rails"' >>Gemfile
+bundle install
 ```
-$ [sudo] gem install influxdb-rails
-```
 
-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.
+
+### 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"
+```
+
+Reported tags:
+
+```ruby
+{
+  hook:        "process_action",
+  server:      Socket.gethostname,
+  app_name:    configuration.application_name,
+  method:      "PostsController#index",
+  http_method: "GET",
+  format:      "html",
+  status:      ["200", ""]
+  exception:   ["", "ArgumentError"]
+}
 ```
-$ cd /to/you/rails/application
-$ touch config/initializers/influxdb_rails.rb
+
+*Note*: If an exception happens during that particular instrumentation the
+`status` will be blank and the tag `exception` will contain the name of the
+exception class.
+
+### Action View
+
+Reported ActiveSupport instrumentation hooks:
+
+- [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)
+
+Reported values:
+
+```ruby
+  value: 48.467,
+  count: 3,
+  cache_hits: 0,
+  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:       ["render_template", "render_partial", "render_collection"]
+  server:     Socket.gethostname,
+  app_name:   configuration.application_name,
+  location:   "PostsController#index",
+  filename:   "/some/file/action.html",
 ```
 
-To see all default values, take a look into `InfluxDB::Rails::Configuration::DEFAULTS`,
-defined in `lib/influxdb/rails/configuration.rb`
+### Active Record
+
+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.
+- [sql.active\_record](https://guides.rubyonrails.org/active_support_instrumentation.html#sql-active-record)
 
-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
+  sql: "SELECT \"posts\".* FROM \"posts\"",
+  request_id: "d5bf620b-3494-425b-b7e1-4953597ea744"
 ```
 
-You can also call through to the underlying `InfluxDB::Client` object to write arbitrary data like this:
+Reported tags:
 
-``` ruby
-InfluxDB::Rails.client.write_point "events",
-  tags:   { url: "/foo", user_id: current_user.id },
-  values: { value: 0 }
+```ruby
+  hook:       "sql",
+  server:     Socket.gethostname,
+  app_name:   configuration.application_name,
+  location:   "PostsController#index",
+  operation:  "SELECT",
+  class_name: "POST",
+  name:       "Post Load"
 ```
 
-Additional documentation for `InfluxDB::Client` lives in the
-[influxdb-ruby](http://github.com/influxdata/influxdb-ruby) repo.
+### Active Job
+
+Reported ActiveSupport instrumentation hooks:
+
+- [enqueue.active\_job](https://guides.rubyonrails.org/active_support_instrumentation.html#enqueue-active-job)
+- [perform_start.active\_job](https://guides.rubyonrails.org/active_support_instrumentation.html#perform-start-active-job)
+- [perform.active\_job](https://guides.rubyonrails.org/active_support_instrumentation.html#perform-active-job)
+
+Reported values:
+
+```ruby
+  value: 89.467
+```
+
+Reported tags:
+
+```ruby
+  hook:       ["enqueue", "perform_start", "perform"],
+  state:      ["queued", "running", "succeeded", "failed"],
+  job:        "SomeJobClassName",
+  queue:      "queue_name"
+```
+
+*Note*: Only the measurements with the hook `perform` report a duration in the value.
+The other hooks are counters and always report a value of `1`.
+
+### Action Mailer
+
+Reported ActiveSupport instrumentation hooks:
+
+- [deliver.action\_mailer](https://guides.rubyonrails.org/active_support_instrumentation.html#deliver-action-mailer)
+
+Reported values:
+
+```ruby
+  value: 1
+```
+
+Reported tags:
+
+```ruby
+  hook:               "deliver",
+  mailer:             "SomeMailerClassName"
+```
+
+*Note*: The hook is just a counter and always report a value of `1`.
+
+## 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
+```
 
+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`).
 
-### Tags
+### 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|
@@ -113,134 +209,197 @@ InfluxDB::Rails.configure do |config|
 end
 ```
 
-By default, the following tags are sent for *non-exception series*
-(`rails.controller`, `rails.view`, `rails.db` and `instrumentation`):
+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
-{
-  method:   "#{payload[:controller]}##{payload[:action]}",
-  server:   Socket.gethostname,
-  app_name: configuration.application_name,
-}
+class ApplicationController
+  before_action :set_influx_data
+
+  def set_influx_data
+    InfluxDB::Rails.current.tags = { user: current_user.id }
+    InfluxDB::Rails.current.values = { redis_value: redis_value }
+  end
+end
 ```
 
-and for the exceptions (series name `rails.exceptions`):
+### Block Instrumentation
+If you want to add custom instrumentation, you can wrap any code into a block instrumentation
 
 ```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.instrument "expensive_operation", tags: { }, values: { } do
+  expensive_operation
+end
+```
+
+Reported tags:
+
+```ruby
+  hook:       "block_instrumentation"
+  server:     Socket.gethostname,
+  app_name:   configuration.application_name,
+  location:   "PostsController#index",
+  name:       "expensive_operation"
+```
+
+Reported values:
+```ruby
+  value: 100 # execution time of the block
+```
+
+You can also overwrite the `value`
+
+```ruby
+InfluxDB::Rails.instrument "user_count", values: { value: 1 } do
+  User.create(name: 'mickey', surname: 'mouse')
+end
 ```
 
+or call it even without a block
+
+```ruby
+InfluxDB::Rails.instrument "temperature", values: { value: 25 }
+```
+
+### Custom client configuration
+
+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
+InfluxDB::Rails.client.write_point "events",
+  tags:   { url: "/foo", user_id: current_user.id, location: InfluxDB::Rails.current.location },
+  values: { value: 0 }
+```
+
+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`.
+
+See [influxdb-ruby](http://github.com/influxdata/influxdb-ruby) for a
+full list of configuration options and detailed usage.
+
+### Disabling hooks
+
+If you are not interested in certain reports you can disable them in the configuration.
+
+```ruby
+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 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.
+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.
 
-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.
+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.
 
-If you, however, use a synchronous client (`config.async = false`), the
-data points are immediately sent to the InfluxDB server. Depending on
+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.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
+```