• Stars
    star
    561
  • Rank 77,379 (Top 2 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created about 8 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Zipkin instrumentation for Node.js and browsers

Zipkin JS

Build Status npm version npm Gitter chat

This is a set of libraries for instrumenting Node.js and browser applications. The zipkin library can be run in both Node.js and the browser.

If you'd like to try this out right away, try our example app which shows how tracing services looks.

Installation

npm install zipkin --save

Basic Setup

const {
  Tracer,
  BatchRecorder,
  jsonEncoder: {JSON_V2}
} = require('zipkin');
const CLSContext = require('zipkin-context-cls');
const {HttpLogger} = require('zipkin-transport-http');

// Setup the tracer
const tracer = new Tracer({
  ctxImpl: new CLSContext('zipkin'), // implicit in-process context
  recorder: new BatchRecorder({
    logger: new HttpLogger({
      endpoint: 'http://localhost:9411/api/v2/spans',
      jsonEncoder: JSON_V2
    })
  }), // batched http recorder
  localServiceName: 'service-a' // name of this application
});

// now use tracer to construct instrumentation! For example, fetch
const wrapFetch = require('zipkin-instrumentation-fetch');

const remoteServiceName = 'youtube'; // name of the application that
                                     // will be called (optional)
const zipkinFetch = wrapFetch(fetch, {tracer, remoteServiceName});

Browser

The zipkin library can be used in the browser. The web example shows an example of a browser based application making a call to a backend server with trace headers attached.

Instrumentation

The following libraries can be instrumented in the browser:

  • fetch (zipkin-instrumentation-fetch)

Transports

The following transport is available for use in the browser:

For debugging purposes, you can also use the ConsoleRecorder:

const tracer = new Tracer({
  ctxImpl: new ExplicitContext(),
  recorder: new ConsoleRecorder(),
  localServiceName: 'service-a' // name of this application
});

Typescript

Since some of the zipkin-js libraries are used in both the browser and Node.js runtimes, some Typescript may complain about missing dependencies when attempting to compile with these libraries for the browser. For instance, the zipkin-transport-http library will determine at runtime whether to use the window.fetch API instead of node-fetch but the compiler will attempt to resolve node-fetch. As a workaround, you can stub the libraries since they are not used in your tsconfig.json (this assumes you added the empty module to your package.json but any library could be used):

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "node-fetch": [
        "node_modules/empty/index.js"
      ],
      "os": [
        "node_modules/empty/index.js"
      ],
    }
  }
}

Node.js

The following libraries are specific to Node.js. Node.js version 8.x and later are supported:

  • zipkin-context-cls
  • zipkin-encoder-thrift

Instrumentations

Various Node.js libraries have been instrumented with Zipkin support. Every instrumentation has an npm package called zipkin-instrumentation-*.

At the time of writing, zipkin-js instruments these libraries:

  • cujojs/rest (zipkin-instrumentation-cujojs-rest)
  • express (zipkin-instrumentation-express)
  • fetch (zipkin-instrumentation-fetch)
  • got (zipkin-instrumentation-gotjs)
  • hapi (zipkin-instrumentation-hapi)
  • memcached (zipkin-instrumentation-memcached)
  • redis (zipkin-instrumentation-redis)
  • restify (zipkin-instrumentation-restify)
  • postgres (zipkin-instrumentation-postgres)
  • request (zipkin-instrumentation-request)
  • request-promise (zipkin-instrumentation-request-promise)
  • connect (zipkin-instrumentation-connect)
  • superagent (zipkin-instrumentation-superagent)
  • grpc-client (zipkin-instrumentation-grpc-client)
  • axios (zipkin-instrumentation-axiosjs)
  • KafkaJS (zipkin-instrumentation-kafkajs)
  • koa (zipkin-instrumentation-koa)

Every module has a README.md file that describes how to use it.

Transports

You can choose between multiple transports; they are npm packages called zipkin-transport-*.

Currently, the following transports are available:

Every package has its own README.md which describes how to use it.

Clock precision

Zipkin timestamps are microsecond, not millisecond granularity. When running in node.js, process.hrtime is used to achieve this.

In browsers, microsecond precision requires installing a shim like browser-process-hrtime:

// use higher-precision time than milliseconds
process.hrtime = require('browser-process-hrtime');

Developing

The code base is a monorepo. We use Lerna for managing inter-module dependencies, which makes it easier to develop coordinated changes between the modules. Instead of running lerna directly, the commands are wrapped with npm; npm run lerna-publish.

To setup the development environment, run:

yarn

Running all tests: yarn test

  • Note that the memcached, redis and postgres integration tests requires you to have local instances running.
  • The Kafka transport integration test will start an embedded Kafka server for the test, which requires you to have Java installed on your machine.
  • The KafkaJS instrumentation tests require docker and docker-compose and will start up a containerized Kafka instance to run against. Its NPM script uses commands that require a recent version of bash.

Running tests for one module npm run lerna-test -- --scope zipkin-instrumentation-foo

Running yarn will execute all tests, which can be distracting if you are only attempting to change one module. Knowing that tests are managed with lerna underneath, you can use the --scope parameter to constrain what's run.

Ex. to only run integration tests for postgres

npm run lerna-test -- --scope zipkin-instrumentation-postgres

Ex. to only run a single integration test in the zipkin package

npm run lerna-test -- --scope zipkin -- test/batch-recorder.integrationTest.js

Running code style linting: yarn lint

Before raising a pull request, make sure there are no lint problems, by running yarn lint. Otherwise, your pull request will be colored red.

Notes

* AppVeyor is currently broken and ignored. PR welcome from those with Windows boxes.

Debugging

To debug tests, you'll need a recent version of chrome installed. You'll also need to add the debugger keyword where you want to pause.

Add the word debugger to the code you are investigating

Say you want to debug this test:

  it('should handle overlapping server and client', () => {
    recorder.record(newRecord(rootId, new Annotation.ServiceName('frontend')));

Literally insert the word debugger

  it('should handle overlapping server and client', () => {
  debugger
    recorder.record(newRecord(rootId, new Annotation.ServiceName('frontend')));

Run lerna-test-debug

Now, run lerna-test-debug, optionally scoping to the module and test you are working on.

Ex.

npm run lerna-test-debug -- --scope zipkin -- test/batch-recorder.integrationTest.js

Start Chrome DevTools for Node

In Chrome, open the url chrome://inspect/#devices and click "Open dedicated DevTools for Node"

Skip the first breakpoint

The first breakpoint is just mocha (the test runner), skip it by clicking the play button:

debugging

Inspect your state!

Now, you should be at a breakpoint. You can inspect the state of fields by looking at the first Closure scope like so:

debugging

Publishing

If you are a user waiting for a merged feature to get released, nag us on the related pull request or gitter.

The actual publish process is easy: Log in to npm with the openzipkin user. Then, run npm run lerna-publish.

More Repositories

1

zipkin

Zipkin is a distributed tracing system
Java
16,769
star
2

brave

Java distributed tracing implementation compatible with Zipkin backend services.
Java
2,327
star
3

zipkin-go

Zipkin distributed tracing library for go.
Go
604
star
4

b3-propagation

Repository that describes and sometimes implements B3 propagation
518
star
5

zipkin4net

A .NET client library for Zipkin
C#
341
star
6

zipkin-php

Zipkin instrumentation for PHP
PHP
270
star
7

brave-example

A collection of examples how to use brave instrumentation in various frameworks and libraries.
Java
210
star
8

zipkin-dependencies

Spark job that aggregates zipkin spans for use in the UI
Java
174
star
9

zipkin-reporter-java

Shared library for reporting zipkin spans on transports such as http or kafka
Java
122
star
10

zipkin-ruby

zipkin-tracer ruby gem
Ruby
98
star
11

zipkin-gcp

Reporters and collectors for use in Google Cloud Platform
Java
89
star
12

zipkin-aws

Reporters and collectors for use in Amazon's cloud
Java
69
star
13

zipkin-php-example

See how much time php services spend on an http request
PHP
59
star
14

zipkin-api

Zipkin's language independent model and HTTP Api Definitions
Thrift
59
star
15

zipkin-js-example

Example project that shows how to use zipkin with javascript
JavaScript
58
star
16

zipkin-finagle

Integration between Finagle tracing to Zipkin transports such as http and kafka
Java
40
star
17

openzipkin.github.io

content for https://zipkin.io
HTML
39
star
18

zipkin-browser-extension

Chrome and Firefox browser extensions for Zipkin
JavaScript
25
star
19

pyramid_zipkin-example

See how much time python services spend on an http request
Python
14
star
20

brave-cassandra

Tracing instrumentation for Cassandra and the DataStax Java Driver
Java
12
star
21

docker-java

A small Docker image based on azul/zulu-openjdk-alpine
Shell
11
star
22

zipkin-api-example

Example of how to use the OpenApi/Swagger api spec
Go
9
star
23

brave-karaf

Karaf integration and tests for Brave (java Zipkin tracer)
Java
6
star
24

zipkin-layout-factory

Spring Boot Layout Factory for Zipkin Server derivatives
Shell
6
star
25

zipkin-support

repository for support questions raised as issues
4
star
26

zipkin-ruby-example

Ruby
4
star
27

docker-alpine

Alpine Linux base layer for Zipkin Docker images
Shell
3
star
28

zipkin-release

Documentation and templates used for projects released the same way as OpenZipkin
Python
1
star