Telemetry

Motive

This package goal is to make the experience of configuring and working with OpenTelemetry easier.

example

Below are short examples for tracing and metrics. More examples are available at the examples folder, and the various opentelemetry repos.

Tracing

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 '@bondsports/telemetry';
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');

// DO STUFF

span.end();

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

Another way for initialize tracing with custom resource:

import { Tracing } from '@bondsports/telemetry';
import { Resource } from '@opentelemetry/resources';

const resource = new Resource({ 'service.version': number, 'service.name': 'my-service-name' });

const tracing = new Tracing([], resource);
...

Metrics

The following code shows a simple example of how to work with metrics.

import { Metrics } from '@bondsports/telemetry';

const metrics = new Metrics('sample-meter');

const meter = metrics.start();

const counter = meter.createCounter('sample_counter');

counter.add(1);

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

Trace-ID response headers (Express middleware)

getTraceIdHeaderMiddleware sets three response headers derived from the active OpenTelemetry span so clients and log-aggregation tools can correlate a single request across systems:

When the inbound request already carries an X-Amzn-Trace-Id header (typical behind an AWS ALB), its value is echoed verbatim so any Self= / Sampled= / custom fields set by intermediate hops are preserved. Otherwise the header is reconstructed from the active span's trace ID.

import express from 'express';
import { getTraceIdHeaderMiddleware } from '@bondsports/telemetry';

const app = express();
app.use(getTraceIdHeaderMiddleware());

Configuration

Common configuration

Tracing configuration

* required (only when tracing is enabled).

Metric configuration

* required (only when tracing is enabled).