README.md

loopback4-tracing

LoopBack 4 Tracing Component

Contents

• Prerequisites
• Installation
  • Initialize tracing
  • Bind the component
• Usage
  • Trace decorator
  • Create custom span
  • Get active span
• 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

• Specifications for OpenTelemetry
• Jaeger Distributed Tracing

Contributing

License

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