Add stats examples (#210)

* Add stats examples

* Use high-resolution real time (process.hrtime) to record latency value

examples/stats/exporter/prometheus.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2018, OpenCensus Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// TODO(mayurkale): Add example.

examples/stats/exporter/stackdriver.js

@@ -0,0 +1,166 @@
+/**
+ * Copyright 2018, OpenCensus Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This is an example of exporting a custom metric from
+ * OpenCensus to Stackdriver.
+ */
+
+const { Stats, MeasureUnit, AggregationType } = require("@opencensus/core");
+const {
+  StackdriverStatsExporter
+} = require("@opencensus/exporter-stackdriver");
+
+const fs = require("fs");
+const readline = require("readline");
+
+// Create the Stats manager
+const stats = new Stats();
+
+// [START setup_exporter]
+// Enable OpenCensus exporters to export metrics to Stackdriver Monitoring.
+// Exporters use Application Default Credentials to authenticate.
+// See https://developers.google.com/identity/protocols/application-default-credentials
+// for more details.
+// Add your project id to the Stackdriver options
+const exporter = new StackdriverStatsExporter({ projectId: "your-project-id" });
+
+// Pass the created exporter to Stats
+stats.registerExporter(exporter);
+// [END setup_exporter]
+
+// The latency in milliseconds
+const mLatencyMs = stats.createMeasureDouble(
+  "repl/latency",
+  MeasureUnit.MS,
+  "The latency in milliseconds per REPL loop"
+);
+
+// Counts/groups the lengths of lines read in.
+const mLineLengths = stats.createMeasureInt64(
+  "repl/line_lengths",
+  MeasureUnit.BYTE,
+  "The distribution of line lengths"
+);
+
+// Create a stream to read our file
+const stream = fs.createReadStream("./test.txt");
+
+// Create an interface to read and process our file line by line
+const lineReader = readline.createInterface({ input: stream });
+
+const tagKey = "method";
+
+// Register the view.
+const latencyView = stats.createView(
+  "demo/latency",
+  mLatencyMs,
+  AggregationType.DISTRIBUTION,
+  [tagKey],
+  "The distribution of the repl latencies",
+  // Latency in buckets:
+  // [>=0ms, >=25ms, >=50ms, >=75ms, >=100ms, >=200ms, >=400ms, >=600ms, >=800ms, >=1s, >=2s, >=4s, >=6s]
+  [0, 25, 50, 75, 100, 200, 400, 600, 800, 1000, 2000, 4000, 6000]
+);
+
+// Register the view.
+const lineCountView = stats.createView(
+  "demo/lines_in",
+  mLineLengths,
+  AggregationType.COUNT,
+  [tagKey],
+  "The number of lines from standard input"
+);
+
+// Register the view.
+const lineLengthView = stats.createView(
+  "demo/line_lengths",
+  mLineLengths,
+  AggregationType.DISTRIBUTION,
+  [tagKey],
+  "Groups the lengths of keys in buckets",
+  // Bucket Boudaries:
+  // [>=0B, >=5B, >=10B, >=15B, >=20B, >=40B, >=60B, >=80, >=100B, >=200B, >=400, >=600, >=800, >=1000]
+  [0, 5, 10, 15, 20, 40, 60, 80, 100, 200, 400, 600, 800, 1000]
+);
+
+// The begining of our REPL loop
+let [_, startNanoseconds] = process.hrtime();
+let endNanoseconds;
+
+// REPL is the read, evaluate, print and loop
+lineReader.on("line", function(line) {
+  // Read
+  try {
+    const processedLine = processLine(line); // Evaluate
+    console.log(processedLine); // Print
+
+    // Registers the end of our REPL
+    [_, endNanoseconds] = process.hrtime();
+
+    const tags = { method: "repl", status: "OK" };
+
+    stats.record({
+      measure: mLineLengths,
+      tags,
+      value: processedLine.length
+    });
+
+    stats.record({
+      measure: mLatencyMs,
+      tags,
+      value: sinceInMilliseconds(endNanoseconds, startNanoseconds)
+    });
+  } catch (err) {
+    const errTags = { method: "repl", status: "ERROR", error: err.message };
+    stats.record({
+      measure: mLatencyMs,
+      errTags,
+      value: sinceInMilliseconds(endNanoseconds, startNanoseconds)
+    });
+  }
+
+  // Restarts the start time for the REPL
+  startNanoseconds = endNanoseconds;
+});
+
+/**
+ * The default export interval is 60 seconds. The thread with the
+ * StackdriverStatsExporter must live for at least the interval past any
+ * metrics that must be collected, or some risk being lost if they are recorded
+ * after the last export.
+ */
+setTimeout(function() {
+  console.log("Completed.");
+}, 60 * 1000);
+
+/**
+ * Takes a line and process it.
+ * @param {string} line The line to process
+ */
+function processLine(line) {
+  // Currently, it just capitalizes it.
+  return line.toUpperCase();
+}
+
+/**
+ * Converts to milliseconds.
+ * @param {number} endNanoseconds The end time of REPL.
+ * @param {number} startNanoseconds The start time of REPL.
+ */
+function sinceInMilliseconds(endNanoseconds, startNanoseconds) {
+  return (endNanoseconds - startNanoseconds) / 1e6;
+}

examples/stats/exporter/test.txt

@@ -0,0 +1,6 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+culpa qui officia deserunt mollit anim id est laborum.

examples/stats/helloworld/index.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2018, OpenCensus Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// TODO(mayurkale): Add basic helloworld example.