first commit

docs/foundation/data/mime/src/telemetry/meters.md

@@ -0,0 +1,61 @@
+# telemetry/meters
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Initializes OpenTelemetry metrics instruments for `@suaveplan/mime`. Provides counters and histograms for tracking MIME detection operations, cache hits, and processing durations. Callers supply their own `Meter` instance so this module has no direct dependency on any specific OTel SDK implementation.
+
+## Features
+
+- Lazy initialization — instruments are created once on first `initMeters` call
+- Idempotent — subsequent `initMeters` calls after the first are no-ops
+- Counters: detection calls by source, detection failures, charset sniff operations
+- Histograms: detection latency, stream read bytes
+- No OTel SDK dependency — accepts any `Meter`-compatible interface
+- Zero-cost no-op path when telemetry is not initialized
+
+## Usage: Basic Example
+
+```typescript
+import { initMeters } from "@suaveplan/mime/telemetry/meters";
+import { metrics } from "@opentelemetry/api";
+
+// Call once at application startup
+const meter = metrics.getMeter("@suaveplan/mime");
+initMeters(meter);
+
+// All subsequent MIME operations will record metrics automatically
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { initMeters, getMimeMeters } from "@suaveplan/mime/telemetry/meters";
+import { metrics } from "@opentelemetry/api";
+
+// Initialize with a named meter for better grouping in dashboards
+initMeters(metrics.getMeter("@suaveplan/mime", "1.0.0"));
+
+// Access instruments directly for custom recording
+const meters = getMimeMeters();
+meters?.detectionCounter.add(1, {
+    source: "magic-bytes",
+    mime: "image/png",
+});
+```
+
+## API Reference
+
+### `initMeters(meter: Meter): void`
+
+Initializes the metric instruments using the provided OTel `Meter`. Idempotent — only the first call has effect.
+
+### `getMimeMeters(): MimeMeters | undefined`
+
+Returns the initialized meters object, or `undefined` if `initMeters` has not been called.
+
+## Implementation Notes
+
+The idempotency guard uses a module-level `let meters: MimeMeters | undefined` variable checked at the top of `initMeters`. This avoids re-creating instruments if `initMeters` is accidentally called multiple times (e.g., from multiple entry points in a large application). The no-op fallback (`getMimeMeters()` returning `undefined`) means callers can use optional chaining without any conditional initialization checks: `getMimeMeters()?.detectionCounter.add(1, attrs)`.