In our Circonus Labs public github repo, we have started a project called Circonus Instrumentation Packs, or CIP. This is a series of libraries to make it even easier to submit telemetry data from your application.
Currently there are CIP directories for go, java, and node.js. Each separate language directory has useful resources to help instrument applications written in that language.
Some languages have a strong leaning toward frameworks, while others are about patterns, and still others are about tooling. These packs are intended to “meld in” with the common way of doing things in each language, so that developer comfort is high and integration time and effort are minimal.
Each of these examples utilize the HTTP Trap check, which you can create within Circonus. Simply create a new JSON push (HTTPTrap) check in Circonus using the HTTPTRAP broker, and then the CheckID, UUID and secret will be available on the check details page.
This can be done via the user interface or via the API. The “target” for the check does not need to be an actual hostname or IP address; the name of your service might be a good substitute.
We suggest that you use a different trap for different node.js apps, as well as for production, staging, and testing.
Below is a bit more detail on each of the currently available CIPs:
Java
Java has a very popular instrumentation library called “metrics,” originally written by Coda Hale and later adopted by Dropwizard. Metrics has some great ideas that we support whole-heartedly; in particular, the use of histograms for more insightful reporting. Unfortunately, the way these measurements are captured and reported makes calculating service level agreements and other such analytics impossible. Furthermore, the implementations of the underlying histograms (Reservoirs in metrics-terminology) are opaque to the reporting tools. The Circonus metrics support in this CIP is designed to layer (non-disruptively) on top of the Dropwizard metrics packages.
Go
This library supports named counters, gauges, and histograms. It also provides convenience wrappers for registering latency instrumented functions with Go’s built-in http server.
Initializing only requires you set the AuthToken (which you generate in your API Tokens page) and CheckId, and then “Start” the metrics reporter.
You’ll need two github repos:
- circonusllhist – a go implementation of Circonus log-linear histograms
- circonus-gometrics – a go implementation of metrics reporting for Circonus
Here is the sample code (also found in the circonus-gometrics readme):
[slide]package main
import (
"fmt"
"net/http"
metrics "github.com/circonus-gometrics"
)
func main() {
// Get your Auth token at https://login.circonus.com/user/tokens
metrics.WithAuthToken("cee5d8ec-aac7-cf9d-bfc4-990e7ceeb774")
// Get your Checkid on the check details page
metrics.WithCheckId(163063)
metrics.Start()
http.HandleFunc("/", metrics.TrackHTTPLatency("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, %s!", r.URL.Path[1:])
}))
http.ListenAndServe(":8080", http.DefaultServeMux)
}
After you start the app (go run the_file_name.go), load http://localhost:8080 in your broswer, or curl http://localhost:8080. You’ll need to approve access to the API Token (if it is the first time you have used it), and then you can create a graph (make sure you are collecting histogram data) and you’ll see something like this:
Node.js
This instrumentation pack is designed to allow node.js applications to easily report telemetry data to Circonus using the UUID and Secret (instead of an API Token and CheckID). It has special support for providing sample-free (100% sampling) collection of service latencies for submission, visualization, and alerting to Circonus.
Here is a basic example to measure latency:
First, some setup – making the app;
% mkdir restify-circonus-example % cd restify-circonus-example % npm init .
(This defaults to npm init . works fine.) Then:
% npm install --save restify % npm install --save probability-distributions % npm install --save circonus-cip
Next, edit index.js and include:
var restify = require('restify'),
PD = require("probability-distributions"),
circonus_cip = require('circonus-cip')
var circonus_uuid = '33e894e6-5b94-4569-b91b-14bda9c650b1'
var circonus_secret = 'ssssssssh_its_oh_so_quiet'
var server = restify.createServer()
server.on('after', circonus_cip.restify(circonus_uuid, circonus_secret))
server.get('/', function (req, res, next) {
setTimeout(function() {
res.writeHead(200, { 'Content-Type': 'text/plain' });
//res.write("Hello to a new world of understanding.\n");
res.end("Hello to a new world of understanding.\n");
next();
}, PD.rgamma(1, 3, 2) * 200);
})
server.listen(8888)
Now just start up the app:
node index.js
Then go to your browser and load localhost:8888, or at the prompt curl http:localhost:8888.
You’ll then go and create the graph in your account. Make sure to enable collection of the metric – “… httptrap: restify `GET `/ `latency…” as a histogram, and you’ll end up with a graph like this:
