influxdb-rails 1.0.0.beta3 → 1.0.1.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8e24e0318b414fc061b67a99de2cacebd24be2b383475367262e8538a36091e
-  data.tar.gz: b5f8f6bf8e22f7deeeb49412c2728ef6d0271e8ba4d987a410e3c07daf928f72
+  metadata.gz: 3fe64b1f95e624972f8ef34c23e3d3f3b9312d33bbdd8480c1ba630449edcc03
+  data.tar.gz: 95efa62efbc63f9d480cf896c8b6b37d32aebd27e9ca874fcb5d9542cdcf6de0
 SHA512:
-  metadata.gz: 5d3d4fae5ac74cb363ae2eb8cb8370172ba924ef8a131320e26d48fa1517e0a8f885407eaf27210c2c8bf37a55b076b4b43c41ce5ec51e3a87b78443d8ecee90
-  data.tar.gz: 8b531e4b1b9a1dc3d40c6e2661a5249844f6183b86cc1f763bd51bb844642b1e51aa1cc3f363272f9a79e8148faa1b5ba3a948074341c969c9b9b63c341edd52
+  metadata.gz: 9d730e69f948734211948092f47f2d089cde0a117e8cf50a4abd6de0a76f382f16f7e7da565547a5e6daf3740aa806ba2376f2dfe8145c4d61749639bdc095e7
+  data.tar.gz: 25e4085b54c19d22e6fa06bc09f52243fe1d4cc932de513deebafe922b6c415eed2a0250d120a663bdd5621401669a9eba922178e2136b519d2c98124e7fe63a

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/.github/workflows/rubocop.yml

@@ -0,0 +1,18 @@
+name: Rubocop
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7
+          bundler-cache: true
+      - run: bundle exec rake rubocop

data/.github/workflows/spec.yml

@@ -0,0 +1,31 @@
+name: Specs
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  spec:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [ '2.5', '2.6', '2.7', 'head' ]
+        rails: [ 'gemfiles/Gemfile.rails-6.1.x', 'gemfiles/Gemfile.rails-6.0.x', 'gemfiles/Gemfile.rails-5.2.x']
+        exclude:
+          - { ruby: '2.7', rails: 'gemfiles/Gemfile.rails-5.2.x' }
+          - { ruby: 'head', rails: 'gemfiles/Gemfile.rails-5.2.x' }
+          - { ruby: '2.5', rails: 'gemfiles/Gemfile.rails-6.0.x' }
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+    env:
+      BUNDLE_GEMFILE: ${{ matrix.rails }}
+    name: Ruby ${{ matrix.ruby }} ${{ matrix.rails }} specs
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake spec

data/.gitignore

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

data/.rubocop.yml

@@ -11,10 +11,7 @@ AllCops:
   - 'vendor/bundle/**/*'
   DisplayCopNames: true
   StyleGuideCopsOnly: false
-  TargetRubyVersion: 2.3
-
-Rails:
-  Enabled: false
+  TargetRubyVersion: 2.4
 
 Layout/EmptyLinesAroundArguments:
   Enabled: false
@@ -22,7 +19,7 @@ Layout/EmptyLinesAroundArguments:
 Layout/SpaceBeforeBlockBraces:
   EnforcedStyleForEmptyBraces: space
 
-Layout/AlignHash:
+Layout/HashAlignment:
   EnforcedColonStyle: table
   EnforcedHashRocketStyle: table
 
@@ -32,8 +29,9 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Exclude:
   - 'spec/**/*.rb'
+  - 'influxdb-rails.gemspec'
 
-Metrics/LineLength:
+Layout/LineLength:
   Max: 100
   Exclude:
   - 'spec/**/*.rb'
@@ -45,12 +43,16 @@ Metrics/ModuleLength:
 Metrics/ParameterLists:
   Max: 6
 
-Naming/UncommunicativeMethodParamName:
+Naming/MethodParameterName:
   AllowedNames: [io, id, db, ex]
 
 Naming/FileName:
   Exclude:
   - lib/influxdb-rails.rb
+  - sample-dashboard/Rakefile
+
+Style/Documentation:
+  Enabled: false
 
 Style/FormatStringToken:
   Enabled: false
@@ -76,3 +78,34 @@ Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: comma
   Exclude:
   - "spec/**/*.rb"
+
+Lint/DuplicateBranch:
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement:
+  Enabled: true
+Lint/EmptyBlock:
+  Enabled: true
+Lint/EmptyClass:
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks:
+  Enabled: true
+Lint/ToEnumArguments:
+  Enabled: true
+Lint/UnexpectedBlockArity:
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator:
+  Enabled: true
+Style/ArgumentsForwarding:
+  Enabled: true
+Style/CollectionCompact:
+  Enabled: true
+Style/DocumentDynamicEvalDefinition:
+  Enabled: true
+Style/NegatedIfElseCondition:
+  Enabled: true
+Style/NilLambda:
+  Enabled: true
+Style/RedundantArgument:
+  Enabled: true
+Style/SwapValues:
+  Enabled: true

data/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 For the full commit log, [see here](https://github.com/influxdata/influxdb-rails/commits/master).
 
+## v1.0.1.beta3, release 2020-10-16
+- Drop `perform_start.active_job` subscriber, it's rather useless on dashboards.
+
+## 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
 
@@ -10,7 +52,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,22 +72,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,100 +12,193 @@ 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
 
-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.
+Reported ActiveSupport instrumentation hooks:
 
-It is possible to disable the rendering series by setting the series_name to nil.
+- [sql.active\_record](https://guides.rubyonrails.org/active_support_instrumentation.html#sql-active-record)
+
+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.
-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:       "sql",
+  server:     Socket.gethostname,
+  app_name:   configuration.application_name,
+  location:   "PostsController#index",
+  operation:  "SELECT",
+  class_name: "POST",
+  name:       "Post Load"
+```
 
-``` ruby
-InfluxDB::Rails.client.write_point "events",
-  tags:   { url: "/foo", user_id: current_user.id, location: InfluxDB::Rails.current.location },
-  values: { value: 0 }
+### Active Job
+
+Reported ActiveSupport instrumentation hooks:
+
+- [enqueue.active\_job](https://guides.rubyonrails.org/active_support_instrumentation.html#enqueue-active-job)
+- [perform.active\_job](https://guides.rubyonrails.org/active_support_instrumentation.html#perform-active-job)
+
+Reported values:
+
+```ruby
+  value: 89.467
 ```
 
-Additional documentation for `InfluxDB::Client` lives in the
-[influxdb-ruby](http://github.com/influxdata/influxdb-ruby) repo.
+Reported tags:
+
+```ruby
+  hook:       ["enqueue", "perform"],
+  state:      ["queued", "succeeded", "failed"],
+  job:        "SomeJobClassName",
+  queue:      "queue_name"
+```
+
+*Note*: Only the measurements with the hook `perform` report a duration in the value.
+The enqueue hook is a counter and always reports 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`.
 
-### Tags
+## 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`).
+
+### 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 +208,197 @@ 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`):
+### Block Instrumentation
+If you want to add custom instrumentation, you can wrap any code into a block instrumentation
 
 ```ruby
-{
-  method:      "#{payload[:controller]}##{payload[:action]}",
-  server:      Socket.gethostname,
-  app_name:    configuration.application_name,
-  http_method: payload[:method],
-  format:      payload[:format],
-  status:      payload[:status]
-}
+InfluxDB::Rails.instrument "expensive_operation", tags: { }, values: { } do
+  expensive_operation
+end
 ```
-For the render series (``rails.render_partial``, ``rails.render_view`` and ``rails.render_collection``)
+
+Reported tags:
 
 ```ruby
+  hook:       "block_instrumentation"
   server:     Socket.gethostname,
   app_name:   configuration.application_name,
-  location:   "#{payload[:controller]}##{payload[:action]}",
-  filename:   payload[:identifier],
-  count:      payload[:count],
-  cache_hits: payload[:cache_hits],
+  location:   "PostsController#index",
+  name:       "expensive_operation"
 ```
 
-For the SQL series (``rails.sql``, disabled by default)
+Reported values:
+```ruby
+  value: 100 # execution time of the block
+```
+
+You can also overwrite the `value`
 
 ```ruby
-  server:     Socket.gethostname,
-  app_name:   configuration.application_name,
-  location:   "#{payload[:controller]}##{payload[:action]}",,
-  operation:  "SELECT",
-  class_name: "USER",
-  name:       payload[:name],
+InfluxDB::Rails.instrument "user_count", values: { value: 1 } do
+  User.create(name: 'mickey', surname: 'mouse')
+end
 ```
 
-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).
+or call it even without a block
 
+```ruby
+InfluxDB::Rails.instrument "temperature", values: { value: 25 }
+```
 
-For the exceptions (series name `rails.exceptions`):
+### 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
-{
-  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.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
+```