loopback4-tracing

LoopBack 4 Tracing Component

Prerequisites
Installation
- Initialize tracing
- Bind the component
Usage
Configuration
Example
Debug
Related resources
Contributing
License

Prerequisites

Some modules need to be installed as peer dependencies with at least a certain version.

@loopback/core  >=2.14.0
@loopback/rest  >=9.1.2

Installation

npm install loopback4-tracing

Initialize tracing

Before loading any application code it is required to initialize tracing. This is usually done at the top of the index.js or index.ts file.

require("loopback4-tracing").init({/* config */});

or in TypeScript it is also possible to do

import { initializeTracing } from "loopback4-tracing";

initializeTracing({/* config */});

Bind the component

This will add the tracing interceptor and observer to the application. The interceptor will create method invocation spans and the observer is required to gracefully shutdown the tracer provider and exporters when the application is stopped.

import { TracingBindings, TracingComponent } from "loopback4-tracing";

export class MyApplication extends BootMixin(
    ServiceMixin(RepositoryMixin(RestApplication))
) {
    constructor(options?: ApplicationConfig) {
        super(options);

        this.component(TracingComponent);
    }
}

Usage

The module provides a lot of auto instrumentations by default but is also possible to create custom spans in your code.

Trace decorator

The easiest way create custom spans is by using the decorator which can be added to any method.

import { trace } from "loopback4-tracing";

class ExampleService {
    constructor() {}

    @trace()
    exampleMethod() {
        // do some work
    }
}

The decorator will wrap the method into a span which will use the method name as span name by default. It is also possible to use a custom span name by setting the operation name in the decorator options.

@trace({ operationName: "customName" })

Create custom span

The first step is get the tracer of the service either by using dependency injection

import { Tracer, TracingBindings } from "loopback4-tracing";

class ExampleService {
    constructor(
        @inject(TracingBindings.TRACER)
        private tracer: Tracer
    ) {}

    exampleMethod() {
        const span = this.tracer.startSpan("exampleMethod");

        // do some work

        span.end();
    }
}

or by directly importing the tracer

import { tracer } from "loopback4-tracing";

function exampleFunction() {
    const span = tracer.startSpan("exampleFunction");

    // do some work

    span.end();
}

Get active span

In some cases it might not be desired to create a new span but instead get the active span to add additional events and attributes to it.

import { getActiveSpan } from "loopback4-tracing";

function exampleFunction() {
    const span = getActiveSpan();

    span.addEvent("some event");

    span.setAttribute("custom.attribute", "some value");
}

Configuration

Most of the time it is not recommended to change the default configuration but there are some cases where it makes sense, for example to enable / disable default instrumentations provided by the module such as http.

The module can be configured by providing custom values in the init function or by using environment variables which will have highest priority.

Note: By default tracing is not enabled. The recommended approach is to enable tracing by setting the environment variable TRACING_ENABLED=true and to only enable it if the collected traces are analyzed.

Configuration parameters

Parameter	Environment Variable	Description	Default	Type
`enabled`	`TRACING_ENABLED`	Enable tracing	`false`	`boolean`
`serviceName`	`TRACING_SERVICE_NAME`	Name of service	`pkg.name`	`string`
`serviceVersion`	`TRACING_SERVICE_VERSION`	Version of service	`pkg.version`	`string`
`propagationFormat`	`TRACING_PROPAGATION_FORMAT`	Propagation format	`"jaeger"`	`"jaeger" \| "w3c"`
`setRequestId`	`TRACING_SET_REQUEST_ID`	Set request id in error and response	`true`	`boolean`
`jaeger.enabled`	`TRACING_JAEGER_ENABLED`	Enable jaeger exporter	`true`	`boolean`
`jaeger.host`	`TRACING_JAEGER_HOST`	Jaeger host	`"localhost"`	`string`
`jaeger.port`	`TRACING_JAEGER_PORT`	Jaeger port	`6832`	`number`
`jaeger.endpoint`	`TRACING_JAEGER_ENDPOINT`	Jaeger traces endpoint	`undefined`	`string`
`jaeger.spanProcessor.type`	`TRACING_JAEGER_SPAN_PROCESSOR`	Jaeger span processor type	`"batch"`	`"simple" \| "batch"`
`console.enabled`	`TRACING_CONSOLE_ENABLED`	Enable console exporter	`false`	`boolean`
`diagnostics.enabled`	`TRACING_DIAGNOSTICS_ENABLED`	Enable diagnostics logger	`false`	`boolean`
`diagnostics.logLevel`	`TRACING_DIAGNOSTICS_LOG_LEVEL`	Log level of diag logger	`9999`	`DiagLogLevel`
`methodInvocations.enabled`	`TRACING_METHOD_INVOCATIONS_ENABLED`	Enable method invocation spans	`true`	`boolean`
`http.enabled`	`TRACING_HTTP_ENABLED`	Enable http instrumentation	`true`	`boolean`

For further details about possible configuration options, see tracing options.

Note: Some values can not be configured by using environment variables but instead need to be provided to the init function.

Example

For an example on how to create custom spans see tracing interceptor and for more information, please read the opentelemetry tracing documentation.

Debug

To enable debug logs set the DEBUG environment variable to loopback:tracing:*, see Setting debug strings for further details.

Related resources

Contributing

License

This project is licensed under the MIT license. See the LICENSE file for more info.

nflaig/loopback4-tracing