@vercel/tracing-js
    TypeScript icon, indicating that this package has built-in type declarations

    0.5.1 • Public • Published

    @vercel/tracing-js

    npm install size circleci

    A partial implementation of the OpenTracing JavaScript API for honeycomb.io backend.

    homecomb-ui

    Getting Started

    The minimum code you need to get started is the following:

    import { Tracer } from '@vercel/tracing-js';
    const tracer = new Tracer({ serviceName }, { writeKey, dataset });
    const span = tracer.startSpan(spanName);
    functionToTrace();
    span.finish();

    Connecting Traces Across Multiple Services

    You can set a parent trace, even if you don't have a reference to the Span object.

    Instead, you can create a new SpanContext.

    You'll need the traceId and parentSpanId (typically found in req.headers).

    const spanContext = new SpanContext(traceId, parentSpanId);
    const childSpan = tracer.startSpan('child', { childOf: spanContext });
    // ...do work here, call function, etc
    childSpan.finish();

    But a better solution is to use the setupHttpTracing helper function like the following:

    async function handler(req: IncomingMessage, res: ServerResponse) {
      const spanContext = setupHttpTracing({ tracer, req, res });
      const fetch = setupFetchTracing({ spanContext });
      await sleep(100, spanContext);
      const output = await fetch(upstreamUrl);
      res.write(output);
    }

    Advanced Usage

    This is the canonical usage in most API services with a couple of example child functions we can trace called sleep and route.

    We take advantage of the SpanContext of the parent span when creating a child span.

    We also use a DeterministicSampler so that all services will use the same sample rate because one trace might have multiple services and we don't want to lose part of a trace due to sampling.

    import micro from 'micro';
    import { Tracer, SpanContext, DeterministicSampler } from '@vercel/tracing-js';
    
    const tracer = new Tracer(
      {
        serviceName: 'my-first-service',
        environment: process.env.ENVIRONMENT,
        dc: process.env.DC,
        podName: process.env.POD_NAME,
        nodeName: process.env.NODE_NAME,
        sampler: new DeterministicSampler(process.env.TRACE_SAMPLE_RATE),
      },
      {
        writeKey: process.env.HONEYCOMB_KEY!,
        dataset: process.env.HONEYCOMB_DATASET!,
      },
    );
    
    // example child function we wish to trace
    async function sleep(ms: number, childOf: SpanContext) {
      const span = tracer.startSpan(sleep.name, { childOf });
      return new Promise(resolve =>
        setTimeout(() => {
          span.finish();
          resolve();
        }, ms),
      );
    }
    
    // example child function we wish to trace
    async function route(path: string, childOf: SpanContext) {
      const span = tracer.startSpan(route.name, { childOf });
      await sleep(200, span.context());
    
      if (!path || path === '/') {
        span.finish();
        return 'Home page';
      } else if (path === '/next') {
        span.finish();
        return 'Next page';
      } else {
        span.finish();
        throw new Error('Page not found');
      }
    }
    
    // example parent function we wish to trace
    async function handler(req: IncomingMessage, res: ServerResponse) {
      const span = tracer.startSpan(handler.name);
      const spanContext = span.context();
      await sleep(100, spanContext);
      const output = await route(req.url, spanContext);
      res.end(output);
      span.finish();
    }
    
    micro(handler).listen(3000);

    See a complete example of multi-service tracing in the examples directory.

    Keywords

    none

    Install

    npm i @vercel/tracing-js

    DownloadsWeekly Downloads

    62

    Version

    0.5.1

    License

    Apache-2.0

    Unpacked Size

    41.5 kB

    Total Files

    26

    Last publish

    Collaborators

    • schlez
    • epallerols
    • domysee
    • nwienert
    • arbw
    • gudmundur
    • marcgreenstock
    • stephdietz
    • vvo
    • falcoagustin
    • nabsul
    • bmealey
    • brethudson
    • maedahbatool
    • matt.straka
    • jasongullickson
    • f3d0r
    • gaspar09
    • jtaylor0196
    • pieparker
    • kelly
    • dferber90
    • healeycodes
    • broph123
    • codybrouwers
    • ebb-tide
    • gdborton
    • msimulcik
    • jeffreyarneson
    • jaredpalmer
    • kikobeats
    • domeccleston
    • nutlope
    • hungrybearstudio
    • codetaromiura
    • mattcleg
    • gkaragkiaouris
    • geovanisouza92
    • dglsparsons
    • lostinpatterns
    • pralhad-vercel
    • vercel-release-bot
    • williamli
    • southpolesteve
    • goncy
    • chibicode
    • ijjk
    • andybitz
    • iamevilrabbit
    • joecohens
    • tootallnate
    • styfle
    • zeit-bot
    • quietshu
    • hankvercel
    • mglagola
    • javivelasco
    • igorklopov
    • paco
    • dav-is
    • timer
    • lucleray
    • leerobinson
    • matheuss
    • nkzawa
    • anatrajkovska
    • timneutkens
    • elsigh
    • cl3arglass
    • samsisle
    • chriswdmr
    • rizbizkits
    • ernestd
    • ismaelrumzan
    • jhoch
    • mrmckeb
    • kuvos
    • creationix
    • rauchg
    • huozhi
    • aadityajshah
    • cmvnk
    • lfades
    • paulogdm
    • ktcarter
    • okbel
    • padmaia
    • msweeneydev
    • delba
    • catsaremlg
    • steventey
    • sokra
    • gsandhu
    • dbredvick
    • kdy1