influxdb 0.6.2 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7762707820de5633483a02078dd8d6254fbda6bd412fbf56c67e8517bd51684
-  data.tar.gz: 3ba80a79c409b7768a65616cf2f6b1e7a6097c862799a56cf5a9bc419a5c49e5
+  metadata.gz: de9d8162fab3d514cea64b236b6646e3f5ac82fbd73b2212d27e62a0941477a2
+  data.tar.gz: 8d2ad9db604f1792f384628c9b29a233abea16c7f21bd6db97bb472ee51e12af
 SHA512:
-  metadata.gz: 76cf43822faa5426b10160f7bb40cbd48af59a4cd1bfd494cd7978a82484b984e35440e3f714491884f78e6d497163567c162e66164c602bb7eeefe84c7b86a9
-  data.tar.gz: 742e37b48e925a5e0985570cc502a976c41f9059258d6347a9a132d8a4ef452d070f344aa20e4880a1b0bd800a887220816c9c370f2a176a04855a18dc865b98
+  metadata.gz: cba9385d8d07bf5299ef050a26df71e2cc70341d02bffe7e6e64d9fe91885cec6d6aba40a154c0a5aa871f653b80f0c40316f9ccf59eb37557ec93b82c6c4581
+  data.tar.gz: 26f8ee0318e7b3be065b768b3b134b8e4dadd741be340a97e0f4381994bc4bcf29f7e49bdce0a76dad20c02ed7b2c25ad759a6dcfca7e10299ba3d976a11b687

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 For the full commit log, [see here](https://github.com/influxdata/influxdb-ruby/commits/master).
 
+## v0.6.3, released 2018-11-30
+
+- Added `InfluxDB.now(precision)` and `InfluxDB::Client#now` as companions
+  to `InfluxDB.convert_timestamp`.
+
 ## v0.6.2, released 2018-11-30
 
 - Added `InfluxDB.convert_timestamp` utility to convert a `Time` to a

data/README.md

@@ -14,7 +14,7 @@ Maintained by [@toddboom](https://github.com/toddboom) and [@dmke](https://githu
 - [Usage](#usage)
   - [Creating a client](#creating-a-client)
   - [Writing data](#writing-data)
-    - [A Note About Time Precision](#a-note-about-time-precision)
+  - [A Note About Time Precision](#a-note-about-time-precision)
   - [Querying](#querying)
 - [Advanced Topics](#advanced-topics)
   - [Administrative tasks](#administrative-tasks)
@@ -145,34 +145,8 @@ influxdb.write_point(name, data)
 influxdb.write_point(name, data, time_precision)
 ```
 
-### A Note About Time Precision
-
-The default precision in this gem is `"s"` (second), as Ruby's `Time#to_i`
-operates on this resolution.
-
-If you write data points with sub-second resolution, you _have_ to configure
-your client instance with a more granular `time_precision` option **and** you
-need to provide timestamp values which reflect this precision. **If you don't do
-this, your points will be squashed!**
-
-> A point is uniquely identified by the measurement name, tag set, and
-> timestamp. If you submit a new point with the same measurement, tag set, and
-> timestamp as an existing point, the field set becomes the union of the old
-> field set and the new field set, where any ties go to the new field set. This
-> is the intended behavior.
-
-See [How does InfluxDB handle duplicate points?][docs-faq] for details.
-
-For example, this is how to specify millisecond precision (which moves the
-pitfall from the second- to the millisecond barrier):
-
-```ruby
-influxdb = InfluxDB::Client.new(time_precision: "ms")
-time = (Time.now.to_r * 1000).to_i
-# A faster, albeit less readable alternative:
-# time = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-influxdb.write_point("foobar", { values: { n: 42 }, timestamp: time })
-```
+> **Attention:** Please also read the
+> [note about time precision](#a-note-about-time-precision) below.
 
 Allowed values for `time_precision` are:
 
@@ -337,6 +311,56 @@ influxdb = InfluxDB::Client.new(
 influxdb.write_point('hitchhiker', { values: { value: 666 } })
 ```
 
+### A Note About Time Precision
+
+The default precision in this gem is `"s"` (second), as Ruby's `Time#to_i`
+operates on this resolution.
+
+If you write data points with sub-second resolution, you _have_ to configure
+your client instance with a more granular `time_precision` option **and** you
+need to provide timestamp values which reflect this precision. **If you don't do
+this, your points will be squashed!**
+
+> A point is uniquely identified by the measurement name, tag set, and
+> timestamp. If you submit a new point with the same measurement, tag set, and
+> timestamp as an existing point, the field set becomes the union of the old
+> field set and the new field set, where any ties go to the new field set. This
+> is the intended behavior.
+
+See [How does InfluxDB handle duplicate points?][docs-faq] for details.
+
+For example, this is how to specify millisecond precision (which moves the
+pitfall from the second- to the millisecond barrier):
+
+```ruby
+client = InfluxDB::Client.new(time_precision: "ms")
+time = (Time.now.to_r * 1000).to_i
+client.write_point("foobar", { values: { n: 42 }, timestamp: time })
+```
+
+For convenience, InfluxDB provides a few helper methods:
+
+```ruby
+# to get a timestamp with the precision configured in the client:
+client.now
+
+# to get a timestamp with the given precision:
+InfluxDB.now(time_precision)
+
+# to convert a Time into a timestamp with the given precision:
+InfluxDB.convert_timestamp(Time.now, time_precision)
+```
+
+As with `client.write_point`, allowed values for `time_precision` are:
+
+- `"ns"` or `nil` for nanosecond
+- `"u"` for microsecond
+- `"ms"` for millisecond
+- `"s"` for second
+- `"m"` for minute
+- `"h"` for hour
+
+[docs-faq]: http://docs.influxdata.com/influxdb/v1.7/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points
 
 ### Querying
 

data/lib/influxdb/client.rb

@@ -48,7 +48,7 @@ module InfluxDB
     # +:verify_ssl+:: verify ssl server certificate?
     # +:ssl_ca_cert+:: ssl CA certificate, chainfile or CA path.
     #                  The system CA path is automatically included
-    # +:retry:: number of times a failed request should be retried. Defaults to infinite.
+    # +:retry+:: number of times a failed request should be retried. Defaults to infinite.
     def initialize(database = nil, **opts)
       opts[:database] = database if database.is_a? String
       @config = InfluxDB::Config.new(opts)
@@ -72,6 +72,10 @@ module InfluxDB
       @stopped
     end
 
+    def now
+      InfluxDB.now(config.time_precision)
+    end
+
     private
 
     def find_writer

data/lib/influxdb/timestamp_conversion.rb

@@ -1,5 +1,45 @@
 module InfluxDB #:nodoc:
-  TIMESTAMP_CONVERSIONS = {
+  # Converts a Time to a timestamp with the given precision.
+  #
+  # === Example
+  #
+  #  InfluxDB.convert_timestamp(Time.now, "ms")
+  #  #=> 1543533308243
+  def self.convert_timestamp(time, precision = "s")
+    factor = TIME_PRECISION_FACTORS.fetch(precision) do
+      raise ArgumentError, "invalid time precision: #{precision}"
+    end
+
+    (time.to_r * factor).to_i
+  end
+
+  # Returns the current timestamp with the given precision.
+  #
+  # Implementation detail: This does not create an intermediate Time
+  # object with `Time.now`, but directly requests the CLOCK_REALTIME,
+  # which in general is a bit faster.
+  #
+  # This is useful, if you want or need to shave off a few microseconds
+  # from your measurement.
+  #
+  # === Examples
+  #
+  #  InfluxDB.now("ns")   #=> 1543612126401392625
+  #  InfluxDB.now("u")    #=> 1543612126401392
+  #  InfluxDB.now("ms")   #=> 1543612126401
+  #  InfluxDB.now("s")    #=> 1543612126
+  #  InfluxDB.now("m")    #=> 25726868
+  #  InfluxDB.now("h")    #=> 428781
+  def self.now(precision = "s")
+    name, divisor = TIME_PRECISION_FACTORS.fetch(precision) do
+      raise ArgumentError, "invalid time precision: #{precision}"
+    end
+
+    time = Process.clock_gettime Process::CLOCK_REALTIME, name
+    (time / divisor).to_i
+  end
+
+  TIME_PRECISION_FACTORS = {
     "ns" => 1e9.to_r,
     nil  => 1e9.to_r,
     "u"  => 1e6.to_r,
@@ -8,16 +48,16 @@ module InfluxDB #:nodoc:
     "m"  => 1.to_r / 60,
     "h"  => 1.to_r / 60 / 60,
   }.freeze
-  private_constant :TIMESTAMP_CONVERSIONS
+  private_constant :TIME_PRECISION_FACTORS
 
-  # Converts a Time to a timestamp with the given precision.
-  #
-  # `convert_timestamp(Time.now, "ms")` might return `1543533308243`.
-  def self.convert_timestamp(time, time_precision)
-    factor = TIMESTAMP_CONVERSIONS.fetch(time_precision) do
-      raise "Invalid time precision: #{time_precision}"
-    end
-
-    (time.to_r * factor).to_i
-  end
+  CLOCK_NAMES = {
+    "ns" => [:nanosecond, 1],
+    nil  => [:nanosecond, 1],
+    "u"  => [:microsecond, 1],
+    "ms" => [:millisecond, 1],
+    "s"  => [:second, 1],
+    "m"  => [:second, 1.to_r / 60],
+    "h"  => [:second, 1.to_r / 60 / 60],
+  }.freeze
+  private_constant :CLOCK_NAMES
 end

data/lib/influxdb/version.rb

@@ -1,3 +1,3 @@
 module InfluxDB # :nodoc:
-  VERSION = "0.6.2".freeze
+  VERSION = "0.6.3".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: influxdb
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.3
 platform: ruby
 authors:
 - Todd Persen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-29 00:00:00.000000000 Z
+date: 2018-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler