Logging & Telemetry

Keyv emits structured telemetry for reads, writes, deletes, and operation errors, and can pipe events through Hookified's eventLogger (Pino, Winston, or any logger with info / warn / error / …).

Table of Contents

• Telemetry events
• eventLogger
• Custom metrics
• Deprecation warnings

Telemetry events

Emitted as KeyvEvents (see Events and Errors):

Batch read, write, and delete methods emit one event per key. Successful has() and hasMany() probes do not emit stat:hit or stat:miss; failures still emit stat:error. A read that fails emits stat:error and no stat:miss.

import Keyv, { KeyvEvents } from "keyv";

const keyv = new Keyv();

keyv.on(KeyvEvents.STAT_HIT, (event) => {
	console.log("hit", event.key, event.namespace, event.timestamp);
});

KeyvStats is a ready-made subscriber for these events. See Statistics.

eventLogger

Keyv extends Hookified, so you can attach a logger. Hookified maps event names to log levels:

import pino from "pino";

const keyv = new Keyv();
keyv.eventLogger = pino({ level: "info" });

keyv.on("error", () => {}); // keep empty-listener throws from firing
await keyv.set("foo", "bar");

The constructor does not take eventLogger; set the property after new Keyv().

Remove it with keyv.eventLogger = undefined.

Custom metrics

Subscribe to stat:* yourself to export Prometheus counters, OpenTelemetry spans, or logs without enabling KeyvStats:

keyv.on("stat:hit", ({ key, namespace }) => {
	metrics.increment("cache_hit", { key, namespace });
});
keyv.on("stat:miss", ({ key }) => {
	metrics.increment("cache_miss", { key });
});

Deprecation warnings

Using v5 hook names (preSet, …) emits 'warn' and, if configured, eventLogger.warn(). Prefer KeyvHooks.BEFORE_* / AFTER_*. See Hooks.