first commit

docs/foundation/timing/datetime/src/otel/datetime-otel.md

@@ -0,0 +1,69 @@
+# 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.