first commit

docs/foundation/data/validation/src/otel/validation-otel.md

@@ -0,0 +1,83 @@
+# Validation OTel Instrumentation
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`validation-otel.ts` provides OpenTelemetry instrumentation for parse operations in `@suaveplan/validation`. It exposes two counter instruments (`validation.parse.success` and `validation.parse.failure`) and one histogram (`validation.parse.duration_ms`) through the OTel metrics API. All instruments are labelled with a `schema.type` attribute so dashboards can break down metrics per schema class.
+
+Instruments are lazily initialised on first use and cached as module-level singletons, avoiding meter lookup overhead on the hot parse path.
+
+## Features
+
+- Counter `validation.parse.success` incremented per successful parse
+- Counter `validation.parse.failure` incremented per failed parse
+- Histogram `validation.parse.duration_ms` records duration in milliseconds
+- `schema.type` attribute on all instruments for per-schema breakdown
+- `_resetInstruments()` for test isolation
+
+## Usage: Basic Example
+
+```typescript
+import { recordParseSuccess, recordParseFailure } from "@suaveplan/validation";
+
+const start = performance.now();
+const result = mySchema.safeParse(input);
+const duration = performance.now() - start;
+
+if (result.success) {
+  recordParseSuccess({ schemaType: "ObjectSchema" }, duration);
+} else {
+  recordParseFailure({ schemaType: "ObjectSchema" }, duration);
+}
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { recordParseSuccess, recordParseFailure } from "@suaveplan/validation";
+
+// Wrap any schema with automatic OTel instrumentation
+function instrumentedParse<T>(schema: { safeParse: (v: unknown) => { success: boolean; data?: T } }, input: unknown, schemaType: string) {
+  const start = performance.now();
+  const result = schema.safeParse(input);
+  const duration = performance.now() - start;
+
+  if (result.success) {
+    recordParseSuccess({ schemaType }, duration);
+  } else {
+    recordParseFailure({ schemaType }, duration);
+  }
+
+  return result;
+}
+```
+
+## API Reference
+
+### `recordParseSuccess(opts: ParseObservabilityOptions, durationMs: number): void`
+
+Increments the success counter and records the duration histogram.
+
+### `recordParseFailure(opts: ParseObservabilityOptions, durationMs: number): void`
+
+Increments the failure counter and records the duration histogram.
+
+### `_resetInstruments(): void`
+
+Clears cached instrument singletons. For test use only.
+
+### `ParseObservabilityOptions`
+
+```typescript
+interface ParseObservabilityOptions {
+  schemaType: string; // e.g. "ObjectSchema", "StringSchema"
+}
+```
+
+## Implementation Notes
+
+- Instruments are lazily created via `metrics.getMeter()` on first call to either `recordParseSuccess` or `recordParseFailure`. This avoids OTel initialisation at module import time.
+- The OTel `metrics` global (`@opentelemetry/api`) is a no-op by default unless a real metrics provider is configured, so these calls are safe in environments without OTel.
+- `_resetInstruments()` sets all singletons to `undefined`, causing the next call to re-create them — useful for testing multiple instrumentation scenarios in the same process.