Initial Commit

packages/communication/emails/campaigns/src/telemetry/telemetry.md

@@ -0,0 +1,58 @@
+# telemetry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+OTel self-telemetry for `@suaveplan/campaigns`. Exposes a small set of counters and histograms that are emitted from every meaningful operation in the package — campaign creation, lifecycle transitions, send dispatches, batch planning, and failures. The instruments resolve against the globally registered `MeterProvider` via `@opentelemetry/api`; when no provider is registered, the OTel API returns no-op meters, so importing this module is always safe in production code that has not opted into telemetry.
+
+Centralising the meter and record helpers in one module keeps the instrumentation surface explicit and prevents feature modules from drifting into ad-hoc, untagged metrics.
+
+## Features
+
+- Five counters: `campaigns_created_total`, `campaigns_transitions_total`, `campaigns_sends_total`, `campaigns_batches_planned_total`, `campaigns_failures_total`.
+- Two histograms: `campaigns_batch_plan_size` (recipient count per plan) and `campaigns_send_duration_ms` (estimated total send-window duration in ms).
+- Record helpers (`recordCampaignCreated`, `recordTransition`, `recordSend`, `recordBatchesPlanned`, `recordFailure`, `recordBatchPlanSize`, `recordSendDuration`) so call sites stay readable.
+- Lazy meter resolution via `metrics.getMeter("@suaveplan/campaigns")` so the module has zero side effects beyond the OTel API itself.
+- Per-instrument descriptions and units (`ms`, `{contact}`) so dashboards can label axes correctly.
+
+## Usage: Basic
+
+```ts
+import { recordCampaignCreated, recordSend } from "@suaveplan/campaigns";
+
+recordCampaignCreated("broadcast", "email");
+recordSend("email");
+```
+
+## Usage: Advanced
+
+Pair the histogram with the planner output for percentile dashboards:
+
+```ts
+import {
+    BatchPlanner,
+    recordBatchPlanSize,
+    recordSendDuration,
+} from "@suaveplan/campaigns";
+
+const planner = new BatchPlanner();
+const contacts = await audience.resolve(campaign.audienceConfig);
+const batches = planner.planBatches(contacts, { batchSize: 250 });
+// planBatches() already records both metrics; helpers are exported so
+// callers can mirror the recording from custom dispatch loops too.
+recordBatchPlanSize(contacts.length);
+recordSendDuration(planner.calculateTotalDuration(contacts.length));
+```
+
+## API Reference
+
+- `campaignsCreatedCounter`, `campaignTransitionsCounter`, `campaignSendsCounter`, `batchesPlannedCounter`, `campaignFailuresCounter` — OTel `Counter` instances.
+- `batchPlanSizeHistogram`, `sendDurationHistogram` — OTel `Histogram` instances.
+- `recordCampaignCreated(type, channel)`, `recordTransition(from, to, event)`, `recordSend(channel)`, `recordBatchesPlanned(count)`, `recordFailure(channel)`, `recordBatchPlanSize(count)`, `recordSendDuration(ms)` — record helpers.
+
+## Implementation Notes
+
+The meter is acquired once at module load time. Because `getMeter` is idempotent and the OTel API guarantees safe no-op behaviour when no provider is registered, the helpers can be called unconditionally from hot paths. Counters carry low-cardinality labels (`type`, `channel`, `from`, `to`, `event`) — never per-tenant or per-campaign identifiers, which would explode metric series. Add such labels via downstream OTel views if needed.