feat: add Datadog metrics adapter

[lan17]

Summary

Closes #54.

This adds a first-party Datadog DogStatsD adapter while preserving DialCache's backend-neutral root package and caller-owned client lifecycle.

Architecture and dependency boundary

The new stable dialcache/datadog subpath contains the adapter and its structural client contract. Published code does not import hot-shots, and hot-shots is neither a runtime dependency nor a peer dependency. Applications install it separately, construct the client, and pass it into the adapter.

The adapter uses only:

• increment(name, value, tags)
• histogram(name, value, tags)
• distribution(name, value, tags)

It never creates transport, flushes buffers, closes sockets, or owns client retries/error handling. The existing DialCache safe metrics boundary continues to isolate synchronous client failures.

Public API

dialcache/datadog exports:

• DatadogDialCacheMetrics
• createDatadogDialCacheMetrics
• DatadogMetricsOptions
• DatadogDogStatsDClient
• DatadogObservationMetricType

observationMetricType is a required "histogram" | "distribution" choice. The documented recommendation is distribution for globally aggregated latency and size percentiles; histogram remains available for intentional Agent-local workflows.

The namespace defaults to dialcache. Construction rejects unsupported modes, missing client methods, invalid namespaces, and any namespace that would make a final adapter metric name exceed Datadog's 200-character limit. Values are never silently sanitized.

Metric contract

All ten current backend-neutral events have exact DogStatsD mappings, including request-local activity and both coalescing scopes. Counters always call increment(name, 1, tags); observations preserve seconds and bytes. Histogram and distribution modes use identical names, values, and tags through their respective client methods.

The adapter preserves the bounded error taxonomy and emits no cache IDs, arguments, Redis keys, raw errors, or messages. End-to-end adversarial coverage verifies those values never reach recorded Datadog calls.

Packaging and ergonomics

Packed-consumer tests now prove:

• root and dialcache/datadog ESM/CJS imports work before hot-shots exists;
• root TypeScript consumers can use the structural client contract without hot-shots types;
• hot-shots is not installed or resolved transitively;
• after a separate hot-shots install, its StatsD instance is directly assignable in ESM and CommonJS TypeScript consumers.

The README covers installation, global tags and client prefixes, client ownership, distribution percentile/billing implications, namespace migration, failure handling, and shutdown.

Validation

Run on Node 22.22.0:

• pnpm check
  • typecheck
  • 159 unit tests with coverage
  • ESM/CJS build and declarations
  • packed ESM/CJS/TypeScript consumers
• pnpm test:integration: 46 tests passed across the existing Redis/Valkey integration suites
• pnpm audit --prod: no known vulnerabilities
• git diff --check
• real hot-shots mock-mode datagram coverage for both distribution and histogram

Instrumentation overhead

Directional one-argument process-local-hit measurements were run against the concern tracked in #43. Each number is the median of seven fresh Node 22.22.0 processes, with 100,000 measured hits after 20,000 warm-up hits on the same build:

Configuration	Median ops/s	Overhead vs disabled
Metrics disabled	532,576	—
Datadog adapter + no-op structural client	516,315	3.1%
Datadog adapter + hot-shots mock encoding/buffering	261,339	50.9%

These are informational rather than a regression threshold. They separate the adapter's mapping cost from real-client DogStatsD formatting/buffering work; issue 43 remains the place to establish the repository-wide benchmark budget and optimize shared hot-path instrumentation.