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:

| Header | Format | Matches | |---|---|---| | X-Trace-Id | 32-char hex (W3C) | trace_id field in application logs | | Trace_Id | 32-char hex (W3C) | trace_id field in application logs | | X-Amzn-Trace-Id | Root=1-<8hex>-<24hex> (AWS X-Ray) | the raw X-Amzn-Trace-Id header stored in AWS ALB access logs / OpenSearch |

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

| name |allowed value| default value | description |---|---|---|---| |TELEMETRY_SERVICE_NAME|string|from package.json| The service name |TELEMETRY_SERVICE_VERSION|string| from package.json| The service version |TELEMETRY_HOST_NAME|string|os.hostname()|The host name

Tracing configuration

| name |allowed value| default value | description |---|---|---|---| |TELEMETRY_TRACING_ENABLED|'true', 'false'|'false'|Should Tracing be enabled |TELEMETRY_TRACING_URL*|string|http://localhost:55681/v1/trace|The URL to the OpenTelemetry Collector |TELEMETRY_TRACING_RATIO|float|1|The amount of traces to sample

* required (only when tracing is enabled).

Metric configuration

| name |allowed value| default value | description |---|---|---|---| |TELEMETRY_METRICS_ENABLED|'true', 'false'|'false'|Should Metrics be enabled| |TELEMETRY_METRICS_URL*|string|http://localhost:55681/v1/metrics|The URL to the OpenTelemetry Collector |TELEMETRY_METRICS_INTERVAL|number|15000|The interval in miliseconds between sending data to the collector

* required (only when tracing is enabled).