# datetime-otel

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

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

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

## Usage: Advanced Example

```ts
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.