suaveplan/packages/foundation/timing/datetime/src/otel/datetime-otel.md

datetime-otel

(no submodules)

Purpose

datetime-otel provides lightweight OpenTelemetry instrumentation for the @suaveplan/datetime package. It registers a histogram for expandRecurrence call durations and a counter for businessDaysBetween interval evaluations. Both instruments are initialised lazily via metrics.getMeter(), which is a no-op when no global MeterProvider is configured, ensuring zero overhead in environments without observability infrastructure.

The module exposes thin wrapper functions (recordExpandRecurrence, recordBusinessDaysBetween) so the hot-path modules do not need to import @opentelemetry/api directly.

Features

• datetime.expand_recurrence.duration_ms histogram (unit: ms)
• datetime.business_days_between.total counter (unit: {days})
• Zero-overhead when no OTel SDK is configured
• Named meter @suaveplan/datetime for easy filtering in dashboards

Usage: Basic Example

import { recordExpandRecurrence } from "@suaveplan/datetime/otel";

const start = Date.now();
// ... run expandRecurrence ...
recordExpandRecurrence(Date.now() - start);

Usage: Advanced Example

import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { recordBusinessDaysBetween } from "@suaveplan/datetime/otel";

// Wire up an SDK meter provider before the first import of datetime modules
const provider = new MeterProvider();
// metrics.setGlobalMeterProvider(provider);  // done at app startup

// Later, inside businessDaysBetween implementation:
recordBusinessDaysBetween(365); // records 365 day-intervals evaluated

API Reference

expandRecurrenceDuration

Histogram — OpenTelemetry histogram for expandRecurrence durations.

businessDaysBetweenTotal

Counter — OpenTelemetry counter for businessDaysBetween day-intervals.

recordExpandRecurrence(durationMs: number): void

Records a single expandRecurrence call duration. Call immediately after the expansion completes.

• durationMs — wall-clock elapsed time in milliseconds

recordBusinessDaysBetween(count: number): void

Increments the businessDaysBetween counter by the number of calendar days evaluated.

• count — number of calendar-day intervals walked during the call

Implementation Notes

metrics.getMeter() is called once at module initialisation. The returned Meter instance is cached for the lifetime of the process. In environments without a registered MeterProvider, all record/add calls are no-ops at the OTel SDK level, incurring only a function-call overhead.

The histogram uses millisecond granularity, which is sufficient for typical recurrence expansions (tens to hundreds of milliseconds). For sub-millisecond benchmarks, use the mitata benchmark suite instead.