feat(instrumentation): instrument cache lifecycle with OTEL (renovatebot#41922)

* fix(cache): instrument repository cache load and save

Wrap repository cache `load()` and `save()` calls with the existing
`instrument()` helper to create OpenTelemetry spans for cache lifecycle
operations. This gives operators visibility into repository cache
performance, especially useful with S3 backends.

Refs renovatebot#41760

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cache): instrument package cache init and destroy

Wrap package cache `init()` and `destroy()` with `instrument()` to
create OpenTelemetry spans, matching the repository cache instrumentation
from the previous commit. Covers redis, sqlite, and file backends.

Refs renovatebot#41760

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: document cache lifecycle tracing in OpenTelemetry guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Move destroy() outside init instrument span

Avoids nesting the package-cache.destroy span inside
package-cache.init, making them sibling spans instead.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Use 'verb NounClass' span naming convention

Rename instrument span names from dot-notation (e.g.
'package-cache.init') to 'verb NounClass' pattern (e.g.
'init PackageCache') per reviewer feedback.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ZackKanter

docs/usage/opentelemetry.md

@@ -77,6 +77,7 @@ Renovate provides instrumentation through traces for (non-exhaustively):
 - Any Git operations
 - Per-manager traces when performing the `lookup` and `extract` splits
 - Per-branch traces when performing the `update` split
+- Cache lifecycle operations (repository cache load/save, package cache init/destroy)
 - Important functions (more instrumentation be added)
 
 As well as following [OpenTelemetry's semantic conventions](https://opentelemetry.io/docs/specs/semconv/) where possible, Renovate defines several Custom Attributes, which can be found in [`lib/instrumentation/types.ts`](https://github.com/renovatebot/renovate/blob/main/lib/instrumentation/types.ts).

lib/util/cache/package/backend.ts

@@ -1,4 +1,5 @@
 import type { AllConfig } from '../../../config/types.ts';
+import { instrument } from '../../../instrumentation/index.ts';
 import { getEnv } from '../../env.ts';
 import type { PackageCacheBase } from './impl/base.ts';
 import { PackageCacheFile } from './impl/file.ts';
@@ -15,27 +16,28 @@ export function getCacheType(): typeof cacheType {
 
 export async function init(config: AllConfig): Promise<void> {
   await destroy();
+  await instrument('init PackageCache', async () => {
+    if (config.redisUrl) {
+      cacheProxy = await PackageCacheRedis.create(
+        config.redisUrl,
+        config.redisPrefix,
+      );
+      cacheType = 'redis';
+      return;
+    }
 
-  if (config.redisUrl) {
-    cacheProxy = await PackageCacheRedis.create(
-      config.redisUrl,
-      config.redisPrefix,
-    );
-    cacheType = 'redis';
-    return;
-  }
+    if (getEnv().RENOVATE_X_SQLITE_PACKAGE_CACHE && config.cacheDir) {
+      cacheProxy = await PackageCacheSqlite.create(config.cacheDir);
+      cacheType = 'sqlite';
+      return;
+    }
 
-  if (getEnv().RENOVATE_X_SQLITE_PACKAGE_CACHE && config.cacheDir) {
-    cacheProxy = await PackageCacheSqlite.create(config.cacheDir);
-    cacheType = 'sqlite';
-    return;
-  }
-
-  if (config.cacheDir) {
-    cacheProxy = PackageCacheFile.create(config.cacheDir);
-    cacheType = 'file';
-    return;
-  }
+    if (config.cacheDir) {
+      cacheProxy = PackageCacheFile.create(config.cacheDir);
+      cacheType = 'file';
+      return;
+    }
+  });
 }
 
 export async function get<T = unknown>(
@@ -55,10 +57,12 @@ export async function set(
 }
 
 export async function destroy(): Promise<void> {
-  cacheType = undefined;
-  try {
-    await cacheProxy?.destroy();
-  } finally {
-    cacheProxy = undefined;
-  }
+  await instrument('destroy PackageCache', async () => {
+    cacheType = undefined;
+    try {
+      await cacheProxy?.destroy();
+    } finally {
+      cacheProxy = undefined;
+    }
+  });
 }

lib/util/cache/repository/index.ts

@@ -1,4 +1,5 @@
 import { GlobalConfig } from '../../../config/global.ts';
+import { instrument } from '../../../instrumentation/index.ts';
 import { logger } from '../../../logger/index.ts';
 import { RepoCacheNull } from './impl/null.ts';
 import type { RepoCache, RepoCacheData } from './types.ts';
@@ -23,7 +24,7 @@ export async function saveCache(): Promise<void> {
   if (GlobalConfig.get('dryRun')) {
     logger.info(`DRY-RUN: Would save repository cache.`);
   } else {
-    await repoCache.save();
+    await instrument('save RepoCache', () => repoCache.save());
   }
 }
 

lib/util/cache/repository/init.ts

@@ -1,3 +1,4 @@
+import { instrument } from '../../../instrumentation/index.ts';
 import { CacheFactory } from './impl/cache-factory.ts';
 import { RepoCacheNull } from './impl/null.ts';
 import { resetCache, setCache } from './index.ts';
@@ -23,14 +24,14 @@ export async function initRepoCache(config: RepoCacheConfig): Promise<void> {
 
   if (repositoryCache === 'enabled') {
     const cache = CacheFactory.get(repository!, repoFingerprint, type);
-    await cache.load();
+    await instrument('load RepoCache', () => cache.load());
     setCache(cache);
     return;
   }
 
   if (repositoryCache === 'reset') {
     const cache = CacheFactory.get(repository!, repoFingerprint, type);
-    await cache.save();
+    await instrument('save RepoCache', () => cache.save());
     setCache(cache);
     return;
   }