Merge pull request #9 from Serphentas/fix-timestamp

Fix #6

README.md

@@ -12,24 +12,35 @@ npm install graphite
 
 ## Usage
 
-Sending data:
+You first have to define the Graphite client:
 
 ```js
 var graphite = require('graphite');
 var client = graphite.createClient('plaintext://graphite.example.org:2003/');
+```
+
+You can send metrics without a timestamp. The current Unix epoch will then be used in place:
 
+```js
 var metrics = {foo: 23};
 client.write(metrics, function(err) {
   // if err is null, your data was sent to graphite!
 });
 ```
 
-Sending data with tags:
+If you wish to set your own timestamp, you must use `Date.now()` (millisecond precision) as parameter and not `Math.floor(Date.now() / 1000)` (second precision), otherwise your metrics will probably get ignored by Graphite:
 
 ```js
-var graphite = require('graphite');
-var client = graphite.createClient('plaintext://graphite.example.org:2003/');
+var metrics = {foo: 23};
+var timestamp = Date.now();
+client.write(metrics, timestamp, function(err) {
+  // if err is null, your data was sent to graphite!
+});
+```
 
+In Graphite [1.1.1 (21.12.17)](http://graphite.readthedocs.io/en/latest/releases/1_1_1.html), [tagging](http://graphite.readthedocs.io/en/latest/tags.html) becomes available. You can send tagged metrics as follows:
+
+```js
 var metrics = {foo: 23};
 var tags = {'name': 'foo.bar', 'some.fancy.tag': 'somefancyvalue'};
 client.writeTagged(metrics, tags, function(err) {

lib/GraphiteClient.js

@@ -44,13 +44,25 @@ GraphiteClient.appendTags = function(flatMetrics, tags) {
   return res;
 };
 
+/**
+ * Writes the given metrics to the underlying plaintext socket to Graphite
+ *
+ * If no timestamp is given, the current Unix epoch is used (second precision).
+ *
+ * If a timestamp is provided, it must have a millisecond precision, otherwise
+ * Graphite will probably reject the data.
+ *
+ * @param {object} metrics
+ * @param {object} timestamp
+ * @param {function} cb
+ */
 GraphiteClient.prototype.write = function(metrics, timestamp, cb) {
   if (typeof timestamp === 'function') {
-    cb        = timestamp;
-    timestamp = null;
+    cb = timestamp;
+    timestamp = Date.now();
   }
 
-  timestamp = timestamp || Date.now();
+  // cutting timestamp for precision up to the second
   timestamp = Math.floor(timestamp / 1000);
 
   this._carbon.write(GraphiteClient.flatten(metrics), timestamp, cb);