Add InfluxDB.now and InfluxDB::Client#now

Author: dmke

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
 

lib/influxdb/client.rb

@@ -48,7 +48,7 @@ class Client
     # +: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 @@ def stopped?
       @stopped
     end
 
+    def now
+      InfluxDB.now(config.time_precision)
+    end
+
     private
 
     def find_writer

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