npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@chankamlam/express-jaeger

v1.1.29

Published

Jaeger middleware to request tracing for express application

Downloads

231

Readme

Express-Jaeger


                                         _                            
  _____  ___ __  _ __ ___  ___ ___      (_) __ _  ___  __ _  ___ _ __ 
 / _ \ \/ / '_ \| '__/ _ \/ __/ __|_____| |/ _` |/ _ \/ _` |/ _ \ '__|
|  __/>  <| |_) | | |  __/\__ \__ \_____| | (_| |  __/ (_| |  __/ |   
 \___/_/\_\ .__/|_|  \___||___/___/    _/ |\__,_|\___|\__, |\___|_|   
          |_|                         |__/            |___/           

Jaeger middleware to request tracing for express application

Required Reading

Opentracing

To fully understand Opentracing, it's helpful to be familiar with the OpenTracing project and terminology more specifically.

Jaeger(One Of Request Tracing System implement Opentracing)

To fully understand Jaeger, it's helpful to be familiar with the Jaeger project and Jaeger Client for Node

Simple Concept

avatar

One request map to one trace

One trace atleast has one span which is master span

Master span can have many children spans

Installation

npm i @chankamlam/express-jaeger -S

Architecture of Jaeger Server

for development

avatar

for prodution

avatar

Build up Jaeger Server Infra locally(development env)

docker run -d -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 -p5775:5775/udp -p6831:6831/udp -p6832:6832/udp \
  -p5778:5778 -p16686:16686 -p14268:14268 -p9411:9411 jaegertracing/all-in-one:latest

Quick Start

const express = require("express");
const jaeger = require("@chankamlam/express-jaeger");
const app = express();

const config = {
    serviceName: 'service1-express',
    sampler: {
        type: "const",
        param: 1
    },
    reporter: {
        collectorEndpoint: "http://localhost:14268/api/traces"
    },
};                                                      // required
const options = { 
  baggagePrefix: "-Johua-",                             // optional,you can let options={}
  excludePath:["/api/v1/health","/api/v1/metric"]       // exclude path
  }; 

app.use(express.json()) // for parsing application/json
app.use(express.urlencoded({ extended: true })) // for parsing application/
x-www-form-urlencoded

app.use(jaeger(config,options,(req,res)=>{
   // here to write your code
   // which is showing here is to auto record query/body/path for every request
    const jaeger = req.jaeger
    jaeger.setTag("route",req.path)
    jaeger.setTag("body",req.body)
    jaeger.setTag("query",req.query)
}));

app.all("/abc", async function (req, res) {
    res.send({code: 200, msg: result});
});

app.listen(3000, '127.0.0.1', function () {
    console.log('start');
});

Usage

normallyUsingSpan2Log

const express = require("express");
const jaeger = require("@chankamlam/express-jaeger")
const app = express();

// setup config, atleast need this param
const config = {
    serviceName: 'aservice-express',                              // your service name
    sampler: {                                                    // setup sampler
        type: "const",
        param: 1
    },
    reporter: {
        collectorEndpoint: "http://localhost:14268/api/traces"    // your jaeger server endpoint
    },
};

// setup options, defaut is {}
const options = { 
  baggagePrefix: "-Johua-",
  excludePath:["/api/v1/health","/api/v1/metric"]                 // exclude path
   };

/*  
 *  using jager,after this it will has one object which called jaeger,
 *  with four properties(span,tracer,request,tags) binding in req
 */
app.use(jaeger(config,options));

app.get("/normallyUsingSpan2Log", async function (req, res) {
    const jaeger = req.jaeger;
    jaeger.log("timestamp",Date.now());
    res.send({code: 200, msg: "success"});
});
app.listen(3000, '127.0.0.1', function () {
    console.log('start server...');
});

usingSpan2LogWithError

app.get("/errorUsingSpan2Log", async function (req, res) {
    const jaeger = req.jaeger;
    const tags = req.jaeger.tags;
    try {
      throw Error("err");           // create exception to test
    } catch (err) {
      jaeger.setTag(tags.ERROR, true);   // diaplay to JaegerUI when you mark tag as "error"
      jaeger.log("errorMsg", err.message);
    }
    res.send({code: 200, msg: "success"});
});

remoteCallingAndlogResult

app.get("/remoteCallingAndlogResult", async function (req, res) {
    const jaeger = req.jaeger
    // for remote request, you have to use jaeger.axios which wrap axios by tracing
    const result = await jaeger
                         .axios({url:"http://localhost:3001/bc"})
                         .then(r=>r.data);
    jaeger.log("result",result)
    res.send({code: 200, msg: "success"});
});

remoteCallingAndlogResultInTwoSpan

app.get("/remoteCallingAndlogResultInTwoSpan", async function (req, res) {

    const jaeger = req.jaeger

    // default under master span (auto create by every request)
    const span1 = jaeger.createSpan("resut1")
    const result1 = await jaeger
                          .axios({url:"http://localhost:3001/a"})
                          .then(r=>r.data);
    span1.log("result1",result1)
    span1.finish();

    // default under master span (auto create by every request)
    const span2 = jaeger.createSpan("resut2")
    const result2 = await jaeger
                          .axios({url:"http://localhost:3001/b",method:"post",data:{}})
                          .then(r=>r.data);
    span2.log("result2",result2)
    span2.finish();

    jaeger.log("resultOfMasterSpan","here is master span")
    res.send({code: 200, msg: "success"});
});

Lookup Request Tracing

open url http://localhost:16686 , remember to build up the Jager Server locally first

avatar avatar

Object Detail

Config

for detail, pls look up to Jaeger Client for Node

{
  serviceName: "string",           // required
  disable: "boolean",
  sampler: {
    type: "string",                // required
    param: "number",               // required
    hostPort: "string",
    host: "string",
    port: "number",
    refreshIntervalMs: "number"
  },
  reporter: {
    logSpans: "boolean",
    agentHost: "string",
    agentPort: "number",
    collectorEndpoint: "string",   // required
    username: "string",
    password: "string",
    flushIntervalMs: "number"
  },
  throttler: {
    host: "string",
    port: "number",
    refreshIntervalMs: "number"
  }
}

options

for detail, pls look up to Jaeger Client for Node

{
    contextKey: "string",
    baggagePrefix: "string",
    metrics: "object", // a metrics
    logger: "object",  // a logger
    tags: "object",    // set of key-value pairs which will be set as process-level tags on the Tracer itself.
    traceId128bit: "boolean",
    shareRpcSpan: "boolean",
    debugThrottler: "boolean",
    excludePath:"array"  // array of parttern for excluding record the access
}

jaeger

jaeger object will bind in req when you do "app.use(jaeger(config,options))"

{
  log           : function(name,content)    // write the log to master span
  setTag        : function(name,value)      // setup tag to master span
  setTracingTag : function(name,value)      // setup tag to master span and children span 
  addTags       : function({k1:v1,k2:v2})   // setup mutiple tags to master span
  createSpan    : function(name)            // create a new span un der master span
  tags          : object                    // all defined tags of opentracing which can be used
  axios         : function(url,options)     // using it to remote call service if not it will be broken the tracing to next service
}

log

req.jaeger.log("info","..........")

setTag

const jaeger = req.jaeger
const tags = jaeger
// using defined tags by opentracing
jaeger.setTag(tags.ERROR,true)
// using your customize tag
jaeger.setTag("warning",true)

setTracingTag

const jaeger = req.jaeger
const tags = jaeger
jaeger.setTracingTag("waybill","wb-123456")

addTags

const jaeger = req.jaeger
const tags = jaeger
// add mutiple tag one time
jaeger.addTags({"error":true,"info":true})

createSpan

const span = jaeger.createSpan("subSpanName")   // create a sub span under master span
// you also can call method of span
span.log("info","info......")
span.setTag("info",true)
// remember to call finish() if not there is no record send to jaeger
span.finish();

tags

predefined tag, some come from OpenTracing project

axios

jaeger.axios wrap axios with tracing header, for usage detail pls look up to axios

license

MIT