Auto-Instrumented Express example (signalfx#22)

Author: rmfitzpatrick

README.md

@@ -109,3 +109,18 @@ language/platform.
 - [AWS Lambda](./aws-lambda): Examples for instrumenting spans for AWS Lambda written in Java, Python, Node, Go
 
 
+## Auto-Instrumentation
+
+For customers who have not instrumented their applications, or have done so in an OpenTracing-compatible
+fashion, we offer several SignalFx Tracing libraries.  Their detailed documentation is available in their
+respective source locations:
+
+- [Java](https://github.com/signalfx/signalfx-java-tracing)
+- [Node.js](https://github.com/signalfx/signalfx-nodejs-tracing)
+- [Python](https://github.com/signalfx/signalfx-python-tracing)
+- [Ruby](https://github.com/signalfx/signalfx-ruby-tracing)
+
+Please note these offerings are currently in Beta status.
+
+- [SignalFx Tracing Examples](./signalfx-tracing)
+

signalfx-tracing/README.md

@@ -0,0 +1,11 @@
+# SignalFx Tracing Libraries
+
+This repository contains example applications for some popular open source web
+frameworks and libraries that have been auto-instrumented using a SignalFx Tracing
+library for their respective platforms and languages.  It is meant as a potentially
+more tangible introduction to getting starting with auto-instrumentation in your 
+environment of choice than general documentation can sometimes be.
+
+## SignalFx Tracing Supported Languages and Platforms
+
+### [Node.js](./signalfx-nodejs-tracing) - https://github.com/signalfx/signalfx-nodejs-tracing

signalfx-tracing/signalfx-nodejs-tracing/README.md

@@ -0,0 +1,14 @@
+# SignalFx Tracing Library for JavaScript
+
+This repository contains an example application that utilizes auto-instrumentation 
+for a supported web framework and the Node.js http client.  This is made possible
+via the [SignalFx Tracing Library for JavaScript](https://github.com/signalfx/signalfx-nodejs-tracing).
+
+For more detailed information about the functionality of the provided tracer and
+instrumentation configuration options, please see the
+[`signalfx-tracing`](https://www.npmjs.com/package/signalfx-tracing) module's
+[API documentation](https://github.com/signalfx/signalfx-nodejs-tracing/blob/master/docs/API.md).
+
+## Libraries and Framework Examples
+
+### [Express](./express)

signalfx-tracing/signalfx-nodejs-tracing/express/README.md

@@ -0,0 +1,59 @@
+# Express.js Auto-Instrumentation Example
+
+This is an example of automatically producing distributed traces using the
+[SignalFx Tracing Library for JavaScript](https://github.com/signalfx/signalfx-nodejs-tracing).
+Please examine the instrumented [client](./client.js) and [server](./server.js) for
+some basic patterns in accessing the instrumentations of an [http](https://nodejs.org/api/http.html)
+client and an [Express](http://expressjs.com/) application. This example is of a simple
+guess-the-word game named "Snowman" that is auto-instrumented by a lone
+[tracer invocation](./snowman/tracer.js).
+
+## Building the example app and client
+
+To run this example locally and send traces to your available Smart Agent or Gateway,
+from this directory do the following:
+
+```bash
+  $ npm install
+  $ # Run the server from one shell session:
+  $ npm start 
+  $ # Run the client commands from another:
+  $ # You can also use ` ./client.js --help` directly
+  $ npm run client -- --help
+  Snowman [command]
+
+  Commands:
+    snowman new             Make a new game.
+    snowman guess [letter]  Make a guess.
+    snowman answer          Report the answer
+    snowman delete          Delete your current game
+```
+
+The `signalfx-tracing` module and this application configuration assume that your Smart Agent
+or Gateway is accepting traces at http://localhost:9080/v1/trace.  If this is not the case,
+you can set the `SIGNALFX_INGEST_URL` environment variable to the desired url to suit your
+environment before launching the server and client.
+
+## Playing Snowman
+
+The example application is a simple word game where you must guess an unknown word by its
+constituent letters from a pool of 1000 randomly selected Unix `words` file entries.  Each
+client request will automatically create an initiating parent span for distributed propagation
+to some basic REST api endpoints implemented via Express.
+
+```bash
+  $ # You can also use ` ./client.js new` directly
+  $ npm run client new
+  message: Game successfully created.
+  progress: _________
+
+  $ npm run client guess x
+  message: Error: There is no "x" in the word.
+  guesses: x
+  progress: _________
+  remainingMisses: 7
+  ( ............... )
+
+  $ npm run client answer
+  message: The answer was: manducate.  Deleting game.
+```

signalfx-tracing/signalfx-nodejs-tracing/express/client.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Initialize the tracer and initiate auto-instrumentation of all supported libraries
+// and frameworks.  In this client example, we instrumented the http module used by the
+// snowman client module.
+const tracer = require('./snowman/tracer')
+
+// Note that importing other modules should occur after init() to ensure their supported
+// dependencies have been auto-instrumented.
+const yargs = require('yargs')
+const fs = require('fs')
+const client = require('./snowman/client')
+
+function writeId(id) {
+  // Write a new game's id to local .snowman file
+  return new Promise((resolve, reject) => {
+    fs.writeFile('.snowman', id, (err) => {
+      if (err) {
+        reject(err)    
+      } else {
+        resolve()
+      }
+    })
+  })
+}
+
+function getId() {
+  // Obtain an existing game's id from local .snowman
+  return new Promise((resolve, reject) => {
+    fs.readFile('.snowman', (err, data) => {
+      if (err) {
+        reject(`Error obtaining game id: ${err}.  Be sure to run "new" to create a game.`)
+      } else {
+        const id = data.toString() 
+        resolve(id)
+      }
+    })
+  })
+}
+
+function printResponse(response) {
+  const properties = ['message', 'guesses', 'progress', 'remainingMisses']
+  for (let i = 0; i < properties.length; i++) {
+    const prop = properties[i]
+    if (response[prop]) {
+      console.log(`${prop}: ${response[prop]}`)
+    }
+ }
+}
+
+yargs
+  .scriptName('snowman')
+  .command('new', 'Make a new game.', {}, (argv) => {
+    client.newGame().then((response) => {
+      return writeId(response.id).then(() => {
+        printResponse(response)
+      }).catch((e) => console.error(e))
+    }).catch((e) => console.error(e))
+  })
+  .command('guess [letter]', 'Make a guess.', {}, (argv) => {
+    getId().then((id) => { 
+      client.makeGuess(argv.letter, id).then((response) => {
+        printResponse(response)
+        if (response.remainingMisses !== undefined) {
+          // render the snowman
+          for (let i = response.remainingMisses; i < 8; i++ ) {
+            console.log(client.snowman[i])
+          }
+        }
+      }).catch((e) => console.error(e))
+    }).catch((e) => console.error(e))
+  })
+  .command('answer', 'Report the answer', {}, (argv) => {
+    getId().then((id) => { 
+      client.getAnswer(id).then(response => {
+        printResponse(response)
+      }).catch((e) => console.error(e))
+    }).catch((e) => console.error(e))
+  })
+  .command('delete', 'Delete your current game', {}, (argv) => {
+    getId().then((id) => { 
+      client.deleteGame(id).then(response => {
+        printResponse(response)
+      }).catch((e) => console.error(e))
+    }).catch((e) => console.error(e))
+  })
+  .help().argv

signalfx-tracing/signalfx-nodejs-tracing/express/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "traced-express-snowman",
+  "version": "1.0.0",
+  "description": "An auto-instrumented Express word game",
+  "main": "server.js",
+  "scripts": {
+    "start": "SIGNALFX_TRACING_DEBUG=true SIGNALFX_SERVICE_NAME=snowman-server node ./server.js",
+    "client": "SIGNALFX_SERVICE_NAME=snowman-client node ./client.js"
+  },
+  "dependencies": {
+    "body-parser": ">=1.0.0",
+    "express": ">=4.0.0",
+    "signalfx-tracing": "latest",
+    "uuid": ">=3.0.0",
+    "yargs": "^13.2.1"
+  },
+  "author": "SignalFx, Inc.",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "eslint": "^5.15.1"
+  }
+}

signalfx-tracing/signalfx-nodejs-tracing/express/server.js

@@ -0,0 +1,16 @@
+// The core of the auto-instrumentation process is made in the
+// tracer.js module.  It consists of a single import and invocation
+// of the 'signalfx-tracing' module.
+const tracer = require('./snowman/tracer')
+
+// Note express module import must come after init() that occurs
+// in snowman/tracer module import, as well as any modules that load it.
+const express = require('express')
+const bodyParser = require('body-parser')
+const snowman = require('./snowman')
+
+const app = express()
+app.use(bodyParser.json())
+app.use('/snowman', snowman.router)
+
+app.listen(snowman.config.serverPort)

signalfx-tracing/signalfx-nodejs-tracing/express/snowman/client.js

@@ -0,0 +1,70 @@
+const { serverUrl } = require('./config')
+
+// http module auto-instrumentation will occur once the tracer is initialized,
+// which occurs in the sourcing client script.
+const http = require('http')
+
+const snowmanUrl = `${serverUrl}/snowman`
+
+// progress graphic
+let snowman = ['        (\'_\')']
+for (let i = 1; i < 8; i++) {
+  snowman.push(`${' '.repeat(8 - i)}( ${'.'.repeat(i * 2 + 1)} )`)
+}
+
+function resolveData(res, resolve) {
+  // resolves a Promise with parsed http response
+  let data = '' 
+  res.on('data', d => {
+    data += d
+  })
+  res.on('end', () => {
+    resolve(JSON.parse(data))
+  })
+}
+
+function newGame() {
+  return new Promise((resolve, reject) => {
+    const req = http.request(`${snowmanUrl}/new`, { method: 'POST' }, (res) => {
+      resolveData(res, resolve)
+    })
+    req.on('error', (e) => reject(e))
+    req.end()
+  })
+}
+
+function makeGuess(guess, id) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(`${snowmanUrl}/${id}`, { method: 'POST' }, res => {
+      resolveData(res, resolve)
+    })
+    req.on('error', (e) => reject(e))
+
+    const content = { guess }
+    req.setHeader('Content-Type', 'application/json')
+    req.write(JSON.stringify(content))
+    req.end()
+  })
+}
+
+function getAnswer(id) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(`${snowmanUrl}/${id}/answer`, { method: 'GET' }, res => {
+      resolveData(res, resolve)
+    })
+    req.on('error', (e) => reject(e))
+    req.end()
+  })
+}
+
+function deleteGame(id) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(`${snowmanUrl}/${id}`, { method: 'DELETE' }, res => {
+      resolveData(res, resolve)
+    })
+    req.on('error', (e) => reject(e))
+    req.end()
+  })
+}
+
+module.exports = { snowman, newGame, makeGuess, getAnswer, deleteGame }

signalfx-tracing/signalfx-nodejs-tracing/express/snowman/config.js

@@ -0,0 +1,6 @@
+const serverPort = 3000
+
+module.exports= {
+  serverPort, 
+  serverUrl: `http://localhost:${serverPort}`
+}