telemetry/meters

(no submodules)

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

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

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

2.4 KiB Raw Blame History