risingstack / opentracing-auto

Out of the box distributed tracing for Node.js applications with OpenTracing.

opentracing-auto

Out of the box distributed tracing for Node.js applications with OpenTracing. Support multiple Tracers.

WARNING: experimental library, do not use in production yet

Technologies

• async_hooks
• OpenTracing

Requirements

• Node.js, >= v8

Getting started

npm install @risingstack/opentracing-auto

// must be in the first two lines of your application
const Instrument = require('@risingstack/opentracing-auto')
const { Tracer } = require('opentracing') // or any OpenTracing compatible tracer like jaeger-client
const tracer1 = new Tracer()
const tracer2 = new Tracer()

const instrument = new Instrument({
  tracers: [tracer1, tracer2]
})

// rest of your code
const express = require('express')
// ...

This package depends on require-in-the-middle and shimmer to monkeypatch tracing information onto the modules listed below. Therefore it is crucial that you require() supported modules after creating the tracing instrument.

If you are using node 8.5+'s experimental module support, you will need to manually hook supported modules:

import Instrument from '@risingstack/opentracing-auto';
import jaeger from 'jaeger-client';
import UDPSender from 'jaeger-client/dist/src/reporters/udp_sender';
import http from 'http';

const instrument = new Instrument({
  tracers: [
    new jaeger.Tracer(
      'my-service-name',
      new jaeger.RemoteReporter(new UDPSender.default({ host: 'my-jaeger-host' })),
      new jaeger.RateLimitingSampler(1),
      {}
    ),
  ],
});

instrument.hookModule(http, 'http');

API

new Instrument({ tracers: [tracer1, tracer2] })

Instrument modules.

• tracers: Array of OpenTracing compatible tracers
  • required
• httpTimings: Adds HTTP timings (DNS lookup, Connect, TLS, Time to first byte, Content transfer)
  • default: false

instrument.unpatch()

Unpatch instrumentations

Instrumentations

• http, https
• express
• restify
• mongodb-core
• pg
• mysql
• redis

Example

The example require a running MongoDB and Jaeger.

To start Jaeger and visit it's dashboard:

docker run -d -p5775:5775/udp -p6831:6831/udp -p6832:6832/udp -p5778:5778 -p16686:16686 -p14268:14268 jaegertracing/all-in-one:latest && open http://localhost:16686

npm run example
curl http://localhost:3000
open http://localhost:16686

HTTP timings

You can enable it with the httpTimings: true

Debug

Start your application with the DEBUG=opentracing-auto* environment variable.

Feature ideas

• More database instrumentation: Redis etc.
• More messaging layer instrumentation: HTTP/2, GRPC, RabbitMQ, Kafka etc.

opentracing-auto's Issues

use `req.get('host')` to replace `req.hostname` , so that the port information can be preserved

opentracing-auto/src/instrumentation/express.js

Line 25 in 4c00173

const url = `${req.protocol}://${req.hostname}${req.originalUrl}`

Child traces not associated with correct parent

I added a 5 second delay to the server1 example in jaeger-node, and then did a few simultaneous requests. All child spans showed up as children of the first request, no child spans were associated with the subsequent requests.

url.format will ignore `path` parameter, use `pathname` and `search` instead

opentracing-auto/src/instrumentation/httpClient.js

Line 28 in 4c00173

path: options.path || options.pathName || '/'

Upgrade require-in-the-middle to 3.0.0

This new version allows for multiple versions of require-in-the-middle to be present in the same dependency-tree without interfering. Previously the last one to be called would win.

IOredis support

I'd like to add ioredis library support

Not working with Node 10

Hello. Thank you for creating this package, it has been a big help for us. Been using this (in prod 😅) for a while.

After we updated to Node 10 it stopped working for outgoing requests, the express module still works, but httpClient does not.

  opentracing-auto:instrumentation:httpClient Patched +0ms
  opentracing-auto:instrument Instrumentation "httpClient" applied on module "http" { moduleVersion: undefined, supportedVersions: undefined } +53ms

  opentracing-auto:instrument Instrumentation "express" applied on module "express" { moduleVersion: '4.16.3', supportedVersions: [ '4.x' ] } +127ms
  opentracing-auto:instrumentation:expressError Patched +0ms
  opentracing-auto:instrument Instrumentation "expressError" applied on module "express" { moduleVersion: '4.16.3', supportedVersions: [ '4.x' ] } +1ms

And then when we get incoming requests:

opentracing-auto:cls Root span started +0ms
  opentracing-auto:instrumentation:express Operation started http_server { 'http.url': 'http://localhost:4000/', 'http.method': 'GET' } +33s

But on outgoing requests we get no logs of httpClient doing anything.

Any ideas?

HTTP timing image

Is this repo still alive?

The concept is great, exactly what I am looking for, but seems like this repo has not seen any maintenance since 2 years. Still accepting PRs ?

Support older Node versions

Are there any plans to support older Node versions? While I generally agree that using the latest LTS for applications is definitely recommended, I think libraries should always support older versions.

Since async_hooks is the main feature of Node 8 for tracing, I think supporting 0.10 to 7 would probably be possible in one go.

circle loop when use http repoter

when use http reporter, will lead circle loop report.
httpClient plugin will on req and res event, http reporter request will be listen too, so once report send http, will be listen and to report, this will circle loop.

childOf

Is it possible to add this instrumentalization root span as a child of another span?

Usecase: I already have existing trace come from another service, and want to append to it.

What is missing for use in production?

There is this disclaimer: "do not use in production!"

What is missing to use it in production from your point of view?

From browsing through the code it looks promising to me, but I need something that can be put into production running on node.js >=8.10 or so...