@bentocache/otel 0.1.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @bentocache/otel
+
+Official OpenTelemetry instrumentation for Bentocache.
+
+## Install
+
+```bash
+pnpm add @bentocache/otel
+```
+
+## Usage
+
+```ts
+import { BentoCacheInstrumentation } from '@bentocache/otel'
+
+const instrumentation = new BentoCacheInstrumentation({
+  requireParentSpan: true,
+  includeKeys: false,
+  suppressInternalOperations: true,
+})
+```
+
+### Options
+
+- `requireParentSpan` (default: `true`) Only create spans when a parent span exists
+- `includeKeys` (default: `false`) Include cache keys in span attributes
+- `keySanitizer` Sanitize keys before adding them as attributes
+- `spanName` Custom span name factory
+- `spanNamePrefix` (default: `cache`) Prefix for default span names
+- `suppressInternalOperations` (default: `true`) Suppress internal L2/bus operations

package/build/index.d.ts

@@ -0,0 +1,38 @@
+import { Span } from '@opentelemetry/api';
+import { CacheOperationMessage } from 'bentocache';
+import { TracingChannelSubscribers } from 'node:diagnostics_channel';
+import { InstrumentationBase, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
+import { BentoCacheInstrumentationConfig, BentoCacheModuleExports } from './src/types.js';
+
+declare class BentoCacheInstrumentation extends InstrumentationBase<BentoCacheInstrumentationConfig> {
+    #private;
+    protected subscribed: boolean;
+    protected spans: WeakMap<object, Span>;
+    protected handlers?: TracingChannelSubscribers<CacheOperationMessage>;
+    /**
+     * Creates a new instrumentation instance with default and user config merged.
+     */
+    constructor(config?: BentoCacheInstrumentationConfig);
+    /**
+     * Applies runtime config updates while preserving default values.
+     */
+    setConfig(config?: BentoCacheInstrumentationConfig): void;
+    /**
+     * Declares the module patching lifecycle for bentocache instrumentation.
+     */
+    protected init(): InstrumentationNodeModuleDefinition[];
+    /**
+     * Enables instrumentation and subscribes to diagnostics channels when possible.
+     */
+    enable(): void;
+    /**
+     * Disables instrumentation and cleans up subscribed channel handlers.
+     */
+    disable(): void;
+    /**
+     * Registers channel hooks manually when module interception is not available.
+     */
+    manuallyRegister(moduleExports: BentoCacheModuleExports): void;
+}
+
+export { BentoCacheInstrumentation, BentoCacheInstrumentationConfig };

package/build/index.js

@@ -0,0 +1,261 @@
+// src/instrumentation.ts
+import { suppressTracing } from "@opentelemetry/core";
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import {
+  InstrumentationBase,
+  InstrumentationNodeModuleDefinition
+} from "@opentelemetry/instrumentation";
+var DEFAULT_CONFIG = {
+  requireParentSpan: true,
+  includeKeys: false,
+  spanNamePrefix: "cache",
+  suppressInternalOperations: true
+};
+var BentoCacheInstrumentation = class extends InstrumentationBase {
+  subscribed = false;
+  spans = /* @__PURE__ */ new WeakMap();
+  handlers;
+  /**
+   * Tracks active getOrSet contexts so child operations (factory, set)
+   * can be parented to the getOrSet span. Keyed by `store:key`.
+   */
+  #activeContexts = /* @__PURE__ */ new Map();
+  #cacheOperation;
+  #originalBentoCache;
+  /**
+   * Resolves CJS and ESM exports to a stable module shape.
+   */
+  #getModuleExports(moduleExports) {
+    if (!moduleExports) return;
+    if (moduleExports[Symbol.toStringTag] === "Module") {
+      return moduleExports.default ?? moduleExports;
+    }
+    return moduleExports;
+  }
+  /**
+   * Replaces BentoCache constructor to inject instrumentation config wrappers.
+   */
+  #patchBentoCache(moduleExports) {
+    if (!moduleExports.BentoCache) return;
+    if (!this.#originalBentoCache) {
+      this.#originalBentoCache = moduleExports.BentoCache;
+    }
+    if (moduleExports.BentoCache !== this.#originalBentoCache) return;
+    const original = this.#originalBentoCache;
+    const instrumentation = this;
+    const BentoCachePatched = class BentoCachePatched extends original {
+      /**
+       * Wraps user config before delegating to the original BentoCache constructor.
+       */
+      constructor(config) {
+        super(instrumentation.#patchConfig(config));
+      }
+    };
+    Object.setPrototypeOf(BentoCachePatched, original);
+    try {
+      moduleExports.BentoCache = BentoCachePatched;
+    } catch {
+      return;
+    }
+  }
+  /**
+   * Restores the original BentoCache constructor when instrumentation is removed.
+   */
+  #unpatchBentoCache(moduleExports) {
+    if (!this.#originalBentoCache) return;
+    if (!moduleExports.BentoCache) return;
+    moduleExports.BentoCache = this.#originalBentoCache;
+  }
+  /**
+   * Adds internal operation suppression to BentoCache config when enabled.
+   */
+  #patchConfig(config) {
+    if (!config || typeof config !== "object") return config;
+    const instrumentationConfig = this.getConfig();
+    if (instrumentationConfig.suppressInternalOperations !== true) return config;
+    const wrappedConfig = { ...config };
+    const suppressWrapper = (fn) => context.with(suppressTracing(context.active()), fn);
+    if (wrappedConfig.internalOperationWrapper) {
+      const userWrapper = wrappedConfig.internalOperationWrapper;
+      wrappedConfig.internalOperationWrapper = (fn) => userWrapper(() => suppressWrapper(fn));
+    } else {
+      wrappedConfig.internalOperationWrapper = suppressWrapper;
+    }
+    return wrappedConfig;
+  }
+  /**
+   * Subscribes handlers to the cache operation channel when instrumentation is active.
+   */
+  #subscribeIfEnabled() {
+    if (!this.isEnabled()) return;
+    if (this.subscribed) return;
+    if (!this.#cacheOperation) return;
+    this.subscribed = true;
+    this.handlers = {
+      start: (message) => this.#handleStart(message),
+      end: () => {
+      },
+      asyncStart: () => {
+      },
+      asyncEnd: (message) => this.#handleAsyncEnd(message),
+      error: (message) => this.#handleError(message)
+    };
+    this.#cacheOperation.subscribe(this.handlers);
+  }
+  /**
+   * Unsubscribes handlers and clears runtime state tied to active spans.
+   */
+  #unsubscribe() {
+    if (!this.subscribed || !this.handlers || !this.#cacheOperation) return;
+    this.#cacheOperation.unsubscribe(this.handlers);
+    this.subscribed = false;
+    this.handlers = void 0;
+    this.spans = /* @__PURE__ */ new WeakMap();
+    this.#activeContexts.clear();
+  }
+  /**
+   * Starts a span for each cache operation event and tracks getOrSet parent contexts.
+   */
+  #handleStart(message) {
+    const config = this.getConfig();
+    const contextKey = `${message.store}:${message.key}`;
+    const parentContext = this.#activeContexts.get(contextKey) ?? context.active();
+    const parentSpan = trace.getSpan(parentContext);
+    if (config.requireParentSpan && !parentSpan) return;
+    const spanName = this.#getSpanName(message);
+    const span = this.tracer.startSpan(
+      spanName,
+      {
+        kind: SpanKind.INTERNAL,
+        attributes: this.#getStartAttributes(message)
+      },
+      parentContext
+    );
+    this.spans.set(message, span);
+    if (message.operation === "getOrSet") {
+      this.#activeContexts.set(contextKey, trace.setSpan(parentContext, span));
+    }
+  }
+  /**
+   * Finalizes successful async spans and records result attributes.
+   */
+  #handleAsyncEnd(message) {
+    const span = this.spans.get(message);
+    if (!span) return;
+    if (message.hit !== void 0) span.setAttribute("cache.hit", message.hit);
+    if (message.tier) span.setAttribute("cache.tier", message.tier);
+    if (message.graced !== void 0) span.setAttribute("cache.graced", message.graced);
+    span.end();
+    this.spans.delete(message);
+    if (message.operation === "getOrSet") {
+      this.#activeContexts.delete(`${message.store}:${message.key}`);
+    }
+  }
+  /**
+   * Finalizes failed spans and records exception details when available.
+   */
+  #handleError(message) {
+    const span = this.spans.get(message);
+    if (!span) return;
+    if (message.error instanceof Error) {
+      span.recordException(message.error);
+      span.setStatus({ code: SpanStatusCode.ERROR, message: message.error.message });
+    }
+    span.end();
+    this.spans.delete(message);
+    if (message.operation === "getOrSet") {
+      this.#activeContexts.delete(`${message.store}:${message.key}`);
+    }
+  }
+  /**
+   * Builds the final span name using custom naming or the configured prefix.
+   */
+  #getSpanName(message) {
+    const config = this.getConfig();
+    if (config.spanName) return config.spanName(message);
+    const prefix = config.spanNamePrefix ?? DEFAULT_CONFIG.spanNamePrefix;
+    return `${prefix}.${message.operation}`;
+  }
+  /**
+   * Builds initial attributes attached to spans at operation start.
+   */
+  #getStartAttributes(message) {
+    const config = this.getConfig();
+    const attributes = {
+      "cache.operation": message.operation,
+      "cache.store": message.store
+    };
+    if (config.includeKeys) {
+      if (message.key) {
+        const key = config.keySanitizer ? config.keySanitizer(message.key) : message.key;
+        if (key) attributes["cache.key"] = key;
+      }
+      if (message.keys?.length) {
+        const keys = config.keySanitizer ? message.keys.map((key) => config.keySanitizer?.(key)).filter((key) => !!key) : message.keys;
+        if (keys.length) attributes["cache.keys"] = keys;
+      }
+    }
+    return attributes;
+  }
+  /**
+   * Creates a new instrumentation instance with default and user config merged.
+   */
+  constructor(config = {}) {
+    super("@bentocache/otel", "0.1.0", { ...DEFAULT_CONFIG, ...config });
+  }
+  /**
+   * Applies runtime config updates while preserving default values.
+   */
+  setConfig(config = {}) {
+    super.setConfig({ ...DEFAULT_CONFIG, ...config });
+  }
+  /**
+   * Declares the module patching lifecycle for bentocache instrumentation.
+   */
+  init() {
+    return [
+      new InstrumentationNodeModuleDefinition(
+        "bentocache",
+        [">=1.6.0"],
+        (moduleExports) => {
+          const exports = this.#getModuleExports(moduleExports);
+          if (!exports) return moduleExports;
+          this.#patchBentoCache(exports);
+          this.#cacheOperation = exports.tracingChannels?.cacheOperation;
+          this.#subscribeIfEnabled();
+          return moduleExports;
+        },
+        (moduleExports) => {
+          const exports = this.#getModuleExports(moduleExports);
+          if (!exports) return;
+          this.#unpatchBentoCache(exports);
+        }
+      )
+    ];
+  }
+  /**
+   * Enables instrumentation and subscribes to diagnostics channels when possible.
+   */
+  enable() {
+    super.enable();
+    if (this.subscribed !== void 0) this.#subscribeIfEnabled();
+  }
+  /**
+   * Disables instrumentation and cleans up subscribed channel handlers.
+   */
+  disable() {
+    if (this.subscribed !== void 0) this.#unsubscribe();
+    super.disable();
+  }
+  /**
+   * Registers channel hooks manually when module interception is not available.
+   */
+  manuallyRegister(moduleExports) {
+    this.#cacheOperation = moduleExports.tracingChannels?.cacheOperation;
+    this.#patchBentoCache(moduleExports);
+    this.#subscribeIfEnabled();
+  }
+};
+export {
+  BentoCacheInstrumentation
+};

package/build/src/types.d.ts

@@ -0,0 +1,48 @@
+import { CacheOperationMessage } from 'bentocache';
+import { TracingChannelSubscribers } from 'node:diagnostics_channel';
+import { InstrumentationConfig } from '@opentelemetry/instrumentation';
+
+type CacheOperationChannel = {
+    subscribe: (subscribers: TracingChannelSubscribers<CacheOperationMessage>) => void;
+    unsubscribe: (subscribers: TracingChannelSubscribers<CacheOperationMessage>) => void;
+};
+type BentoCacheModuleExports = {
+    BentoCache?: new (...args: any[]) => any;
+    tracingChannels?: {
+        cacheOperation?: CacheOperationChannel;
+    };
+};
+type CacheKeySanitizer = (key?: string) => string | undefined;
+type SpanNameFactory = (message: CacheOperationMessage) => string;
+interface BentoCacheInstrumentationConfig extends InstrumentationConfig {
+    /**
+     * Only create spans when a parent span exists
+     * @default true
+     */
+    requireParentSpan?: boolean;
+    /**
+     * Include cache keys in span attributes
+     * @default false
+     */
+    includeKeys?: boolean;
+    /**
+     * Sanitize cache keys before adding them as attributes
+     */
+    keySanitizer?: CacheKeySanitizer;
+    /**
+     * Custom span name factory
+     */
+    spanName?: SpanNameFactory;
+    /**
+     * Prefix used when building the default span name
+     * @default 'cache'
+     */
+    spanNamePrefix?: string;
+    /**
+     * Suppress internal Bentocache operations (L2 + bus)
+     * @default true
+     */
+    suppressInternalOperations?: boolean;
+}
+
+export type { BentoCacheInstrumentationConfig, BentoCacheModuleExports, CacheKeySanitizer, CacheOperationChannel, SpanNameFactory };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@bentocache/otel",
+  "type": "module",
+  "version": "0.1.1",
+  "description": "OpenTelemetry instrumentation for Bentocache",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "license": "MIT",
+  "keywords": [
+    "bentocache",
+    "opentelemetry",
+    "otel",
+    "instrumentation",
+    "tracing"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./types": "./build/src/types.js"
+  },
+  "main": "build/index.js",
+  "files": [
+    "build"
+  ],
+  "peerDependencies": {
+    "bentocache": "^1.6.0"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.9.0",
+    "@opentelemetry/instrumentation": "^0.57.0"
+  },
+  "devDependencies": {
+    "@julr/utils": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.9.0",
+    "bentocache": "1.6.1"
+  },
+  "tsup": {
+    "entry": [
+      "./index.ts",
+      "./src/types.ts"
+    ],
+    "outDir": "./build",
+    "clean": true,
+    "format": "esm",
+    "dts": true,
+    "target": "esnext"
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "html"
+    ],
+    "exclude": [
+      "bin",
+      "tests/**",
+      "test_helpers/**",
+      "factories/**"
+    ]
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore(release): @bentocache/otel@${version}",
+      "tagAnnotation": "release ${version}",
+      "tagName": "@bentocache/otel@${version}"
+    },
+    "github": {
+      "release": true,
+      "releaseName": "@bentocache/otel@${version}",
+      "web": true
+    }
+  },
+  "scripts": {
+    "test": "c8 pnpm quick:test",
+    "quick:test": "cross-env NODE_NO_WARNINGS=1 node --enable-source-maps --loader=ts-node/esm bin/test.ts",
+    "build": "tsup-node",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "release": "pnpm build && pnpm release-it",
+    "checks": "pnpm lint && pnpm typecheck"
+  }
+}