@unhandled/instrumentation-bentocache
v0.1.15
Published
Bentocache tracing for Unhandled
Readme
@unhandled/instrumentation-bentocache
Traces Bentocache operations, including the ones issued through @adonisjs/cache (which drives a BentoCache underneath). Needs bentocache ^1.6.0 installed in your app.
Install
npm i @unhandled/instrumentation-bentocache bentocacheRegister
With the Unhandled AdonisJS agent:
import { bentocache } from '@unhandled/instrumentation-bentocache/integration'
export default defineConfig({
integrations: [bentocache()],
})Installing the package does nothing until the integration is registered. Leave it out, or pass bentocache({ enabled: false }), to turn it off. If bentocache cannot be resolved, setup throws a BentocacheNotInstalledError.
Standalone, register the instrumentation yourself and import bentocache after it (ESM needs the import-in-the-middle loader hook for the internal-span suppression below):
import { BentocacheInstrumentation } from '@unhandled/instrumentation-bentocache'
registerInstrumentations({ instrumentations: [new BentocacheInstrumentation()] })If your module hooks miss bentocache, call instrumentation.patch(await import('bentocache')) yourself.
Options
| Option | Default | Effect |
| ------------------- | ------- | ----------------------------------------------------------------------- |
| enabled | true | Integration only. false skips the integration. |
| requireParentSpan | false | Only create spans when a span is already active. |
| includeKeys | true | false leaves cache.key and cache.keys off every span. |
| keySanitizer | masks ids | (key) => string \| undefined. Replaces the default sanitizer entirely. |
The default sanitizer splits the key on : and replaces every UUID, all-digit and hex-id (8+ hex characters) segment with *, so bentocache:users:123 becomes bentocache:users:*. Bentocache reports the key with its configured prefix.
Bentocache's own L2 (Redis, database) and bus calls run with tracing suppressed, so they do not produce spans of their own. This relies on wrapping the BentoCache constructor; it is skipped, with a diagnostics warning, if the module namespace is read-only.
Spans
One INTERNAL span per operation, named cache.<operation>: cache.get, cache.set, cache.getOrSet, cache.factory, cache.delete, cache.deleteMany, cache.clear, cache.expire. Spans started while another cache operation is running (the factory and write of a getOrSet) are children of it. Failures record the exception and set ERROR status.
| Attribute | When |
| ----------------- | -------------------------------------------------------------- |
| cache.operation | always |
| cache.store | always |
| cache.key | includeKeys and the operation has a key |
| cache.keys | includeKeys and the operation has several keys (deleteMany) |
| cache.hit | get and getOrSet |
| cache.tier | get hits: l1 or l2 |
| cache.graced | get hits: whether the value came from the grace period |
For AI agents
A coding agent can install this package, check that its data arrives and fix the errors it reports through the Unhandled MCP server at https://unhandled.net/mcp. In Claude Code, the Unhandled plugin adds that server plus skills for instrumenting a service, fixing a production error with a failing test first and verifying a deploy:
claude plugin marketplace add treboryx/unhandled
claude plugin install unhandled@unhandledCodex, Cursor, Gemini CLI and other agents connect to the same URL. Coding agents has the setup for each one and an AGENTS.md section to add to your repository.
