cloudnativejs / appmetrics-zipkin

Provide zipkin integration from appmetrics

The appmetrics-zipkin module is deprecated.

appmetrics-zipkin provides Zipkin instrumentation of Node.js applications using a single line: require('appmetrics-zipkin').

Unlike other zipkin instrumentation packages, appmetrics-zipkin will automatically inject missing trace header information into any inbound request and use the same value for the outbound request without any user intervention. This gives you a full trace across the http message with out any extra code.

Configure Zipkin Endpoint

Connecting to a Zipkin endpoint is done by adding the desired hostname and port to appmetrics-zipkin.properties file.

Alternatively, the hostname, port and service name (used by Zipkin to identify your application) can be added when including appmetrics-zipkin into your application:

var appzip = require('appmetrics-zipkin')({
  host: 'localhost',
  port: 9411,
  serviceName:'frontend',
  sampleRate: 1.0
});

Note: The properties file has precedence over the inline settings

If no configuration details are provided, the endpoint will be localhost:9411, the serviceName will be set to the program name that requires appmetrics-zipkin and the sample rate will be 1.0 (100% of requests).

Usage

var appzip = require('appmetrics-zipkin');
var express = require('express');
var app = express();


app.get('/api', (req, res) => res.send(new Date().toString()));
app.listen(9000, () => {
  console.log('Backend listening on port 9000!');
});

Note: require('appmetrics-zipkin') must be included before requiring other packages to ensure those packages are correctly instrumented. Failure to do can result in spans not being sent to the Zipkin server.

Using Zipkin with Node.js and Kubernetes

Deploy the Zipkin service with a given service name and exposure type, for example, naming the service zipkin and choosing to expose the service via the NodePort mechanism.

Your Node.js code to send Zipkin traffic to the discovered server would be as follows:

var zipkinHost = "localhost"
var zipkinPort = 9411  

if (process.env.ZIPKIN_SERVICE_HOST && process.env.ZIPKIN_SERVICE_PORT) {
  console.log("Routing Zipkin traffic to the Zipkin Kubernetes service")
  zipkinHost = process.env.ZIPKIN_SERVICE_HOST
  zipkinPort = process.env.ZIPKIN_SERVICE_PORT
} else {
  console.log("Detected we're running the Zipkin server locally")
}

var appzip = require('appmetrics-zipkin')({
  host: zipkinHost,
  port: zipkinPort,
  serviceName:'my-kube-frontend',
  sampleRate: 1.0
});

You can see if the environment variables are present with the following commands.

Use kubectl get pods to discover the pod of your Zipkin deployment.

Use kubectl exec -it <the pod name from above> printenv | grep SERVICE to determine the environment variables present for the Zipkin service.

Example output:

[Node.js@IBM icp-nodejs-sample]$ kubectl exec -it test-zipkin-289126497-pjf5b printenv | grep SERVICE
ZIPKIN_SERVICE_HOST=10.0.0.105
ZIPKIN_SERVICE_PORT=9411

Module Long Term Support Policy

This module adopts the Module Long Term Support (LTS) policy, with the following End Of Life (EOL) dates:

Module Version	Release Date	Minimum EOL	EOL With	Status
V1.x.x	Oct 2017	Dec 2019		Current

License

Apache-2.0

appmetrics-zipkin's Issues

Add Kubernetes example in README.md

We should document how to use this module with a Zipkin server deployed on Kubernetes.

It's pretty simple to do if users deploy Zipkin with the NodePort mechanism, you can programatically discover it using$SERVICE_NAME_SERVICE_HOST and $SERVICE_NAME_SERVICE_HOST.

The service name may just be "zipkin", like it is with Microservice Builder, so in our application code we'd have something like:

if (process.env.ZIPKIN_SERVICE_HOST && process.env.ZIPKIN_SERVICE_PORT) {
  console.log("Routing Zipkin traffic to the Zipkin Kubernetes service")
  zipkinHost = process.env.ZIPKIN_SERVICE_HOST
  zipkinPort = process.env.ZIPKIN_SERVICE_PORT
} else {
  console.log("Detected we're running locally")
}

A list of environment variables for your Kubernetes cluster (once kubectl has been configured) is available with):

kubectl exec $SERVICE_NAME env.

We could go one step further and have an examples directory as well with simple Node.js applications that can talk to each other, be deployed, and interactions between the endpoints can be traced with Zipkin (like here but with Kubernetes). I think that's beyond the scope of this item though.

Can I only add traceId in some of requests endpoint?

Is there a way to filter endpoint? Because I don't want to send trace records to my zipkin server for health check endpoint.
Currently I added appmetrics-zipkin to my express-js server and I find it adds traceid globally and all of requests records are kept in my zipkin server. However some of them such as health-check endpoint is unnecessary. Is there any method I can filter my health check endpoint?

No spans when appmetrics-zipkin and appmetrics-dash are provided (on Kube)

When deploying a Node.js sample application to Kubernetes, if I have the require/attach statements for appmetrics-prometheus and appmetrics-dash, I get no spans appearing. No errors in my Zipkin logs either though.

Without the includes/attach statements I get new spans OK.

How can i log db time , file time , and other for an api?

I just want to know i am seeing every where only one line is mention to setup zipkins tracking .
var appzip = require('appmetrics-zipkin')({
host: 'localhost',
port: 9411,
serviceName:'backend',
sampleRate: 1.0
});
It is tracking api in my zipkins setup , but i dont see docs ,for example

Let say i have api which have datbase call , file read , file write , How can i trace how mach time which function has take in the particular api .
Does this module do that or i have to use other module to do so?

Any blog is there , I can not see any blog for that with respect to my use case ?

Receiving no spans following the readme

Following the readme, getting no spans at all now.

var appzip = require('appmetrics-zipkin');
var express = require('express');
var app = express();

app.get('/api', (req, res) => res.send(new Date().toString()));
app.listen(9000, () => {
  console.log('Backend listening on port 9000!');
});

Start Zipkin, port 9411, change defaults so we can see any traces (start/end time adjustments, newest first, no limit).

Go to localhost:9000/api, see the server output OK.

No data.

No data. Doesn't look to be trying to use Zipkin at all, even if I kill the Zipkin server I don't get any errors e.g. connection refused ones.

Tried appmetrics-zipkin 1.0.2 as well, node 6.12.0, node 6.10.3 (was on my path), node 8.9.0. Tried with

var appzip = require('appmetrics-zipkin')({
  host: 'localhost',
  port: 9411,
  serviceName:'frontend'
});

too.

package.json:

{
  "name": "easiest",
  "version": "1.0.0",
  "description": "",
  "main": "server.js",
  "dependencies": {
    "appmetrics-zipkin": "^1.0.3",
    "express": "^4.16.2"
  },
  "devDependencies": {},
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js"
  },
  "author": "",
  "license": "ISC"
}

How can I use HTTPS protocol

As I understand, package does not support HTTPS protocol:
https://github.com/CloudNativeJS/appmetrics-zipkin/blob/master/appmetrics-zipkin.js#L105​​​​​​​

Add Travis integration for builds

Enable verbosity config

It'd be useful to have, in appmetrics-zipkin.properties for example, and via a method call, to be able to configure how noisy the module behaves.

Either we use a standard Node.js logging library (so whatever the log4j equivalent is) or do it ourselves with custom levels - for now I'm really only looking for silent and normal.

I expect, in appmetrics-zipkin.propeties, to have:
host=...
port=...
logging=silent for example.

When the silent option is provided, i want to have zero errors reported (so when requests can't reach a Zipkin server because it's not yet configured or available for example).

With normal I'd want the behaviour as it is now. Anything extra (e.g. providing trace data) should be considered as part of #24 IMO.

Tests are failing on Mac OS

When the same code is run on both Ubuntu and OSX,
it fails on OSX -
the traces of a specific request reach zipkin but the traceId that were set on the headers are different than those on zipkin.

e2e tracing not showing up with http requests

Hi all, I've got a simple example sending a message between two Node.js servers (both on different ports) and I expect to have the trace data show up with the Zipkin UI that shows each service on the same view.

What I'm getting instead is trace data for server A ("the pusher") and server B ("the getter"). I expect to see trace data to and from each endpoint, not just from eachpoint: it's as though they're not linked (so they're different traces and not sharing the same trace ID).

When my pusher sends data to the getter, the trace shows up as follows:

Is this expected behaviour? I expect to see "pusher -> getter -> pusher" as one trace with three spans.

Recreate steps
I used yo nodeserver to generate two Node.js applications then changed the port so they're listening on ports 3000 and 3001. The "pusher" logic will send a http request when the /push/number endpoint is accessed.

Important pusher logic, this is in my index.html page:

  <div class="controller">
      <input type="number" name="generate-length" id="generate-length"></input>
      <input type="button" name="generate-message-button" value="Generate a string of this length - must be a number!" onclick="redirect();">
    </div>

    <script type="text/javascript">
      function redirect() {
        var value = document.getElementById("generate-length").value;
        window.location = '/push/' + value;
      }
    </script>

Both applications are using appmetrics-zipkin 1.0.2 and are configured to push to the same Zipkin server but with different service names.

The getter logic does the following:

router.get('/:number', function(req, res, next) {
  var lengthOfString = req.params.number
  
  if (!req || !req.params || !req.params.number || isNaN(lengthOfString) || lengthOfString > 1000000000) {
    res.writeHead(301, {'Content-Type': 'text/plain'});
    res.write("Can't handle this request: I need a number less than 1,000,000,000\n")
    res.end();
  }

  let myString = ''

  for (let i = 0; i < lengthOfString; i++){
    myString += String.fromCharCode(65+i%26)
  }

  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.write("request to return " + lengthOfString + " chars received - result is " + myString.toLowerCase())
  res.end()
});

app.use("/receive", router);

If you're an IBMer please take a look at the example here and follow the instructions - I haven't pushed this to public Github yet as it's not quite working!

Add validation of hostname and port

Can we add checking that the hostname and port supplied by the user are valid

Can I get the request and response body for each request made?

Is there a way by which somehow i can get the request and response body for each request received and served by a service ?

Add trace options

I'm testing appmetrics-zipkin with new versions of IBM Cloud Private regularly, I have a sample that uses it but will often silently not be working as expected.

It'd be useful to have environment variables we can set that, when set, enables extra output to be printed (we'll essentially be tracing the tracer).

Here's what I'm proposing.

ZIPKIN_TRACE_PRINT_SPANS
If set, print the span information that we're creating on an endpoint being used

ZIPKIN_TRACE_PRINT_TRACES
If set, print the trace information (linking multiple spans between multiple services for example).

ZIPKIN_TRACE_PRINT_SERVER_IP
If set, print the Zipkin server IP we're trying to send data to.

ZIPKIN_TRACE_PRINT_SERVER_PORT
If set, print the Zipkin server port we're trying to send data to.

ZIPKIN_TRACE_CLIENT_VERSION
If set, print the Zipkin client module version that we're using.

ZIPKIN_TRACE_APPMETRICS_VERSION
If set, print the version of appmetrics we're using (as we're piggybacking off appmetrics probes AFAIK, this is important to know).

ZIPKIN_TRACE_SERVER_VERSION
If set, print the version of Zipkin running on the server (not sure how backwards compatible Zipkin servers are with clients so this may also be useful to know).

If an application is also making HTTP requests they seem to be nested when they shouldn't be

This is my sample app:

require('appmetrics-zipkin')({
  host: 'localhost',
  port: 9411,
  serviceName:'frontend',
  sampleRate: 1.0
});

var http = require('http');

const port = 3000;

const requestHandler = (request, response) => {  
  response.end('Hello')
}

const server = http.createServer(requestHandler);

server.listen(port, (err) => {  
  if (err) {
    return console.log('An error occurred', err)
  }
  console.log(`Server is listening on ${port}`)
});

setInterval(function() {
  try {
  	http.get('http://localhost:3000/')
  } catch (err) {
  	console.log("caught error");
  	console.error(err);
  }
}, 3000);

It is making HTTP calls, but not from within the scope of the HTTP request handler so I don't think the outbound call should be nested inside the incoming call. In OpenZipkin we see this however:

Cut a new NPM release

Now that appmetrics-zipkin has a test suite it would be great if a new NPM release could be cut

Add eslint to code checks

Tests!

It's possible to start a zipkin server in a docker container with a 1-line command

docker run -d -p 9411:9411 openzipkin/zipkin

and then query it with a REST API - https://github.com/openzipkin/zipkin-api

It would be great get some simple tests running with appmetrics-zipkin.

HTTP Timeout not handled

Hello,

Can I handle HTTP requests which send no response ?

Example:

` var appzip = require("appmetrics-zipkin")({
host: "localhost",
port: 9411,
serviceName: "frontend",
sampleRate: 1.0
});

var express = require("express");
var app = express();

app.get("/timeout", (req, res) => {

});

var server = app.listen(9000, () => {

});

server.setTimeout(5000);

`

I call /timeout and after 5seconds the server will stop it (timeout) but the Zipkin will not handle this issue.

No Longer maintained?

Hi,
It seems this is no longer maintained - is that the case?

Proposal: Archive repository and deprecate on npm

This module has not been in active development/maintained for a while. I propose formally deprecating the module for clarity to any users.

To do:

• PR a deprecation note to the README - #54
• Deprecate the module on npm (requires npm publish permissions)
• Archive the GitHub repository

The number of traces and spans are shown incorrectly in Zipkin

Tried this library, unfortunately does not give the right results under high concurrency scenarios.
Ex:
Client—> Service-A —> Service-B

In my case Service-A and Service-B are microservices built using node.js. To simulate the high concurrency scenario, do the following :
-In Service-A, after a request is received from the client, add a setTimeout() of about 10 seconds, after which Service-A calls Service-B
-Have the Client send 5 requests one after the other within 10 seconds.
-Service-A will receive all 5 requests, before it is forwarded to Service-B

Under the above scenario, the expectation is to see 5 different traces with 2 spans in each trace. Instead I see a single trace with 6 spans in it.

Does it work with other web framework like koa?

Does it work with other web framework like koa?

Can we get the traceId to use for logging?

Is there a way to get the traceId which is propagated to Zipkin.

I want to log the traceId in log file during my logging so as to search the logs later.

Crash if application makes outbound requests

I started testing for the 1.1.1 release but my simple application was crashing. It doesn't crash without appmetrics-zipkin.

require('appmetrics-zipkin')({
  host: 'localhost',
  port: 9411,
  serviceName:'frontend',
  sampleRate: 1.0
});

var http = require('http');

const port = 3000;

const requestHandler = (request, response) => {  
  response.end('Hello')
}

const server = http.createServer(requestHandler);

server.listen(port, (err) => {  
  if (err) {
    return console.log('An error occurred', err)
  }
  console.log(`Server is listening on ${port}`)
});

setInterval(function() {http.get('http://localhost:3000/')}, 3000);

Error was:

events.js:183
      throw er; // Unhandled 'error' event
      ^

Error: connect ECONNREFUSED 127.0.0.1:80
    at Object._errnoException (util.js:1022:11)
    at _exceptionWithHostPort (util.js:1044:20)
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1198:14)