Initial Commit

packages/foundation/timing/datetime/src/otel/datetime-otel.ts

@@ -0,0 +1,83 @@
+import { metrics } from "@opentelemetry/api";
+
+const meter = metrics.getMeter("@suaveplan/datetime");
+
+/**
+ * Histogram tracking the wall-clock duration of `expandRecurrence` calls in
+ * milliseconds. Use this to detect expensive recurrence expansions in production.
+ */
+export const expandRecurrenceDuration = meter.createHistogram(
+    "datetime.expand_recurrence.duration_ms",
+    {
+        description: "Duration of expandRecurrence() calls in milliseconds",
+        unit: "ms",
+    }
+);
+
+/**
+ * Histogram tracking the size (number of dates emitted) by
+ * `expandRecurrence`. Pairs with {@link expandRecurrenceDuration} to
+ * correlate output size with latency.
+ */
+export const expandRecurrenceSize = meter.createHistogram(
+    "datetime.expand_recurrence.size",
+    {
+        description: "Number of dates emitted by expandRecurrence()",
+        unit: "{dates}",
+    }
+);
+
+/**
+ * Histogram tracking the wall-clock duration of `businessDaysBetween` calls
+ * in milliseconds.
+ */
+export const businessDaysBetweenDuration = meter.createHistogram(
+    "datetime.business_days_between.duration_ms",
+    {
+        description: "Duration of businessDaysBetween() calls in milliseconds",
+        unit: "ms",
+    }
+);
+
+/**
+ * Histogram tracking the calendar-day span evaluated by
+ * `businessDaysBetween` calls.
+ */
+export const businessDaysBetweenSize = meter.createHistogram(
+    "datetime.business_days_between.size",
+    {
+        description: "Calendar-day span evaluated by businessDaysBetween()",
+        unit: "{days}",
+    }
+);
+
+/**
+ * Counter tracking the cumulative number of intervals evaluated by
+ * `businessDaysBetween`. Use this to monitor workload distribution.
+ */
+export const businessDaysBetweenTotal = meter.createCounter(
+    "datetime.business_days_between.total",
+    {
+        description:
+            "Cumulative number of day-intervals evaluated by businessDaysBetween()",
+        unit: "{days}",
+    }
+);
+
+/**
+ * Record a `businessDaysBetween` observation.
+ *
+ * @param count - Number of calendar days evaluated in the call.
+ */
+export function recordBusinessDaysBetween(count: number): void {
+    businessDaysBetweenTotal.add(count);
+}
+
+/**
+ * Record an `expandRecurrence` duration observation.
+ *
+ * @param durationMs - Elapsed milliseconds for the expansion call.
+ */
+export function recordExpandRecurrence(durationMs: number): void {
+    expandRecurrenceDuration.record(durationMs);
+}