Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vercel/tracing-js
An implementation of Opentracing API for honeycomb.io
https://github.com/vercel/tracing-js
honeycomb performance-analysis tracing
Last synced: 12 days ago
JSON representation
An implementation of Opentracing API for honeycomb.io
- Host: GitHub
- URL: https://github.com/vercel/tracing-js
- Owner: vercel
- License: apache-2.0
- Created: 2019-02-22T18:39:19.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2021-05-05T18:13:59.000Z (over 3 years ago)
- Last Synced: 2024-12-17T23:23:14.703Z (16 days ago)
- Topics: honeycomb, performance-analysis, tracing
- Language: TypeScript
- Homepage: https://npmjs.com/@vercel/tracing-js
- Size: 64.5 KB
- Stars: 46
- Watchers: 63
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: license.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# @vercel/tracing-js
[](https://www.npmjs.com/package/@vercel/tracing-js) [](https://packagephobia.now.sh/result?p=@vercel/tracing-js) [](https://circleci.com/gh/vercel/workflows/tracing-js)
A partial implementation of the [OpenTracing JavaScript API](https://opentracing-javascript.surge.sh) for [honeycomb.io](https://www.honeycomb.io) backend.
[](https://ui.honeycomb.io)
## Getting Started
The minimum code you need to get started is the following:
```ts
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`).
```ts
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:
```ts
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.
```ts
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](https://github.com/vercel/tracing-js/tree/master/examples) directory.