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