@betshare/infra-telemetry

Shared OpenTelemetry bootstrap for BetShareMarket TypeScript services. Wires a NodeSDK with OTLP HTTP exporters (traces + metrics), the standard auto-instrumentations (filesystem instrumentation disabled), and a small set of process-runtime metrics/traces, all stamped with a consistent BetShareMarket resource. Extracted verbatim from the duplicated src/telemetry/bootstrap.ts copies in api-events, api-caller, and monitoring-service (the monitoring-service copy — the one with real OTel types — was the canonical source).

Install

In production, consume from the private registry, version-pinned per service:

npm install @betshare/infra-telemetry

// package.json
"@betshare/infra-telemetry": "^0.1.0"

API

import { initializeTelemetry } from "@betshare/infra-telemetry";

const telemetry = initializeTelemetry({
  serviceName: "api-events",
  serviceVersion: "1.0.0",
  pipelineFamily: "ingestion",
});

await telemetry.ready; // resolves once the SDK has started (or logged a startup error)

initializeTelemetry(config: TelemetryConfig): TelemetryRuntime

Starts the OpenTelemetry NodeSDK once per process (idempotent — repeat calls return the same TelemetryRuntime and ignore the new config) and registers SIGTERM / SIGINT shutdown hooks.

TelemetryConfig:

| field | required | default | | ------------------ | -------- | ---------------------------------------------------- | | serviceName | yes | — | | serviceVersion | yes | — | | pipelineFamily | yes | — | | environment | no | ENV / NODE_ENV / "development" | | serviceNamespace | no | "betsharemarket" |

TelemetryRuntime:

• commonAttributes — resource attributes applied to every signal (service.name, service.version, service.namespace, service.instance.id, deployment.environment, betsharemarket.pipeline.family, betsharemarket.runtime.language).
• meterName — "<serviceName>.runtime".
• tracerName — "<serviceName>.bootstrap".
• ready — Promise<void> that resolves after the SDK starts. Failures are caught and logged, never thrown, so the host process keeps running even when no collector is reachable.
• shutdown() — flushes and stops the SDK; also wired to SIGTERM/SIGINT.

Environment variables

• OBSERVABILITY_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT — collector base URL. Any trailing /v1/{traces,metrics,logs} or slash is stripped and the per-signal path is re-appended. Defaults to http://127.0.0.1:4318 when unset (the bootstrap degrades gracefully — it does not fail if nothing is listening).
• OTEL_EXPORTER_OTLP_HEADERS — key=value,key2=value2 exporter headers.
• OTEL_METRIC_EXPORT_INTERVAL — metric export interval in ms (default 15000).

Service usage

Each service keeps a thin re-export shim at src/telemetry/bootstrap.ts so existing imports stay unchanged:

// services/<svc>/src/telemetry/bootstrap.ts
export * from "@betshare/infra-telemetry";

// services/<svc>/src/index.ts (unchanged)
import { initializeTelemetry } from "./telemetry/bootstrap";

Services still importing @opentelemetry/api directly (e.g. observability.ts for metrics/trace/SpanStatusCode) must keep that dependency; only the NodeSDK/exporter/resource packages move into this package.