feat: add OpenTelemetry and cache tracing

Author: le0m

packages/utils/package.json

@@ -49,6 +49,8 @@
 		"@aws-sdk/client-s3": "^3.828.0",
 		"@chialab/isomorphic-dom": "workspace:*",
 		"@heyputer/kv.js": "fquffio/kv.js#fix/strict-mode",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/semantic-conventions": "^1.36.0",
 		"cookie": "^1.0.2",
 		"html-entities": "^2.6.0",
 		"pino": "^9.5.0",

packages/utils/src/lib/server/cache/base.ts

@@ -1,5 +1,7 @@
 import type { JitterFn, JitterMode } from '../../utils/misc.js';
 import type { StorageReadWriter } from '../storage.js';
+import { trace, ATTR_PEER_SERVICE } from '../telemetry.js';
+import { SpanKind } from '@opentelemetry/api';
 
 /**
  * Base class for caching.
@@ -75,6 +77,7 @@ export abstract class BaseCache<V> implements StorageReadWriter<V> {
 		ttl?: number | undefined,
 		jitter?: JitterMode | JitterFn | undefined,
 	): Promise<V | undefined>;
+	@trace({ kind: SpanKind.CLIENT, attributes: { [ATTR_PEER_SERVICE]: 'cache' } })
 	public async remember(
 		key: string,
 		callback: () => PromiseLike<V | undefined>,

packages/utils/src/lib/server/telemetry.ts

@@ -0,0 +1,41 @@
+import api, { type Span, type SpanOptions, SpanStatusCode } from '@opentelemetry/api';
+
+/**
+ * Replaces deprecated SEMATTRS_PEER_SERVICE attribute.
+ * See {@link https://github.com/open-telemetry/opentelemetry-js/blob/main/semantic-conventions/README.md#unstable-semconv}.
+ */
+export const ATTR_PEER_SERVICE = 'peer.service' as const;
+
+export const tracer = api.trace.getTracer('@chialab/sveltekit-utils');
+
+/**
+ * Decorator to trace a method or function by wrapping it in a new active span.
+ *
+ * @param options Span options
+ */
+export const trace =
+	(options: SpanOptions = {}) =>
+	(_: any, method: PropertyKey, descriptor: PropertyDescriptor) => ({
+		...descriptor,
+		value(...args: any[]) {
+			return tracer.startActiveSpan(
+				[this?.constructor?.name, method].filter(Boolean).join('.'),
+				options,
+				async (span: Span) => {
+					try {
+						// Wait for the wrapped function to end before closing the span and returning
+						return await descriptor.value.call(this, ...args);
+					} catch (e) {
+						span.setStatus({ code: SpanStatusCode.ERROR });
+						if (e instanceof Error) {
+							span.recordException(e);
+						}
+
+						throw e;
+					} finally {
+						span.end();
+					}
+				},
+			);
+		},
+	});

packages/utils/tsconfig.json

@@ -4,6 +4,7 @@
 		"allowJs": true,
 		"checkJs": true,
 		"esModuleInterop": true,
+		"experimentalDecorators": true,
 		"forceConsistentCasingInFileNames": true,
 		"moduleResolution": "Bundler",
 		"resolveJsonModule": true,