Bentocache

This guide explains how to:

Install and enable the cache integration
Customize key sanitization
Suppress internal cache operations

Overview

The explicit integration traces Bentocache operations, including caches used through @adonisjs/cache, using your agent’s OpenTelemetry provider. See the Cache dashboard for the attributes it uses.

This integration requires AdonisJS agent 2.x. To replace the 1.x top-level cache option, follow the migration guide.

Installation

Install the integration and declare Bentocache in your application. The integration supports Bentocache ^1.6.0.

Terminal

npm install @monocle.sh/instrumentation-bentocache bentocache

With the AdonisJS agent

Register bentocache() in config/monocle.ts. Keep otel.ts first in your application entry points so hooks initialize before application modules load.

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import { bentocache } from "@monocle.sh/instrumentation-bentocache/integration";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  integrations: [bentocache()],
});

Omit the integration or use bentocache({ enabled: false }) to disable it. Installing the package alone does not activate tracing.

Configuration

The default options preserve the agent’s previous cache behavior: keys are captured and sanitized, parent spans are not required, and internal Redis/L2 operations are suppressed. Override key handling or require a parent span through the factory.

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import { bentocache } from "@monocle.sh/instrumentation-bentocache/integration";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  integrations: [bentocache({
    requireParentSpan: true,
    includeKeys: true,
    keySanitizer: (key) => key?.replace(/session:.+/, "session:*"),
  })],
});

Key sanitization

The default sanitizer replaces UUIDs, numeric IDs, and hexadecimal identifiers with *. For example, users:123 becomes users:*. A custom keySanitizer replaces this default. Set includeKeys: false to omit keys.

Internal operation suppression

The Monocle integration suppresses internal Redis, L2, and bus spans so traces show high-level cache operations. This retains the previous Adonis agent behavior.

Without the AdonisJS agent

For a standalone OpenTelemetry setup, use BentoCacheInstrumentation from @bentocache/otel directly. Its defaults differ from the Monocle wrapper. Initialize your SDK and module hooks before loading your application, and include the instrumentation in your existing SDK setup.

instrumentation.ts

import { BentoCacheInstrumentation } from "@bentocache/otel";

export const cacheInstrumentation = new BentoCacheInstrumentation({
  requireParentSpan: false,
  includeKeys: true,
  suppressInternalOperations: true,
});

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Migrations

Other

Overview

Installation

With the AdonisJS agent

Configuration

Key sanitization

Internal operation suppression

Without the AdonisJS agent

​Overview

​Installation

​With the AdonisJS agent

​Configuration

​Key sanitization

​Internal operation suppression

​Without the AdonisJS agent

Overview

Installation

With the AdonisJS agent

Configuration

Key sanitization

Internal operation suppression

Without the AdonisJS agent