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

note

This page was generated from a remote source. you can find it on https://github.com/MapColonies/infra-packages/blob/master/packages/README.md