# 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.