@fewlines/fwl-tracing v1.0.0
FWL Tracing
Disclaimer: this package is made for our internal usage and is only open source for convenience so we might not consider Pull Requests or Issues. Feel free to fork though.
This is part of the Fewlines Web Libraries packages. It provides a simple way to do tracing with OpenTelemetry.
Installation
yarn add @fewlines/fwl-tracing
Getting Started
As OpenTelemetry libraries need to monkey patch packages before them being called, the easiest way is to initialize tracing in a separate file that is required using node’s (or ts-node's) -r option before application code runs.
So for instance, have a tracing.ts
file with that content:
// src/tracing.ts
import { startTracer } from "@fewlines/fwl-tracing";
startTracer({ serviceName: "serviceName" });
And start your server with ts-node -r src/tracing.ts src/index.ts
.
Once you're done, your index.ts
could get the Tracer with:
import { getTracer } from "@fewlines/fwl-tracing";
const tracer = getTracer();
Usage
Once you have a tracer (of type Tracer
), you will have a span
method:
import { Span, Tracer } from "@fewlines/fwl-tracing";
// ...
function(tracer: Tracer) {
tracer.span("span name", async (span: Span) => {
// If you want to add attributes to your span
span.setAttribute(key, value);
// any code there that return a Promise (in this example, the callback is an `async` function so any value should do
});
}
This way is the recommended way as it will automatically end the span for you.
However, if you ever are in need to more fine grain control (for instance, in a middleware), you can use createSpan
:
Here is an example of a logging middleware:
import { NextFunction, Request, Response } from "express";
import { Logger } from "@fewlines/fwl-logging";
import { Tracer, Span } from "@fewlines/fwl-tracing";
export function loggingMiddleware(tracer: Tracer, logger: Logger) {
function onCloseOrFinish(span: Span, startTime: bigint): () => void {
return function () {
const response = this as Response;
response.removeListener("finish", onCloseOrFinish);
const end = process.hrtime.bigint();
logger.log(`${response.req.path}: ${response.statusCode} in ${end - startTime}`);
span.end();
};
}
return function (
_request: Request,
response: Response,
next: NextFunction,
): void {
const startTime = process.hrtime.bigint();
const span = tracer.createSpan("logging middleware");
response.once("finish", onCloseOrFinish(span, startTime));
next();
};
}
Keep in mind that this method is only required because we need to call next()
and we want to start the span across the whole request.
The recommended method is to use tracer.span
.
5 years ago