Tracing

Motive

This package provides tracing capabilities using OpenTelemetry SDK, making it easier to configure and work with distributed tracing in your applications.

API documentation

Check the autogenerated documentation here.

example

Below is a simple example of how to work with tracing. Please note that you need to manually install any auto-instrumentation library that you require. The following code shows a simple example of how to work with tracing. please notice that you need to manually install any auto-instrumentation library that you require.

import { Tracing } from '@map-colonies/tracing';
import { trace } from '@opentelemetry/api';

const tracing = new Tracing();

tracing.start();

const tracer = trace.getTracer('tracing-name')

const span = tracer.startSpan('some-action');

span.setAttribute('some-attribute', 'ITS VALUE');

// DO STUFF

span.end();

tracing.stop().then(() => console.log('done'));

Another way to initialize tracing with custom attributes:

import { Tracing } from '@map-colonies/tracing';

const tracing = new Tracing({ 
  attributes: { 
    'service.version': '1.0.0', 
    'service.name': 'my-service-name' 
  } 
});
tracing.start();
...

Configuration

Common configuration

| name |allowed value| default value | description |---|---|---|---| |TELEMETRY_SERVICE_NAME|string|package.json name| The name of the service to put as attribute |TELEMETRY_SERVICE_VERSION|string|package.json version| The version of the service to put as attribute |TELEMETRY_HOST_NAME|string|os.hostname()|The value of the hostname attribute to use, will override the hostname

Tracing configuration

| name |allowed value| default value | description |---|---|---|---| |TELEMETRY_TRACING_ENABLED|'true', 'false'|'false'|Should Tracing be enabled |TELEMETRY_TRACING_URL*|string|http://localhost:4318/v1/traces|The URL to the OpenTelemetry Collector |TELEMETRY_TRACING_RATIO|float|1|The amount of traces to sample (0-1) |TELEMETRY_TRACING_DEBUG|'true', 'false'|'false'|Enable debug mode for tracing which enables opentelemetry debug log and console trace export

* required (only when tracing is enabled).

Related Packages

This package is part of the MapColonies infrastructure packages monorepo. For other telemetry-related functionality, see:

• @map-colonies/semantic-conventions - Semantic conventions for telemetry data
• @map-colonies/tracing-utils - Utilities for working with tracing