Open Telemetry

.changeset/common-bananas-knock.md

@@ -0,0 +1,5 @@
+---
+"@chialab/sveltekit-utils": patch
+---
+
+Add OpenTelemetry for observability

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 { ATTR_PEER_SERVICE, trace } 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/index.ts

@@ -2,6 +2,7 @@ export * from './cache/index.js';
 export * from './hooks/index.js';
 export * from './session.js';
 export * from './sitemap.js';
+export { traceDecoratorFactory, ATTR_PEER_SERVICE } from './telemetry.js';
 export * from './utils.js';
 
 import type { Session } from './session.js';

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

@@ -0,0 +1,61 @@
+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 traceDecoratorFactory = (name: string, version?: string) => {
+	const tracer = api.trace.getTracer(name, version);
+
+	return <This, Value extends (this: This, ...args: any) => unknown>(options: SpanOptions = {}) =>
+		(target: Value, ctx: ClassMethodDecoratorContext<This, Value>): Value => {
+			type R = ReturnType<Value>;
+
+			return function (this: This, ...args: Parameters<Value>): R {
+				// @ts-expect-error Typing this properly would be cumbersome.
+				const className = ctx.static ? this.name : this.constructor.name;
+
+				return tracer.startActiveSpan([className, ctx.name].filter(Boolean).join('.'), options, (span: Span): R => {
+					try {
+						const result = target.call(this, ...args) as R;
+						if (result && typeof result === 'object' && 'then' in result && typeof result.then === 'function') {
+							return result.then(
+								(result: R) => {
+									span.end();
+
+									return result;
+								},
+								(err: unknown) => {
+									span.setStatus({ code: SpanStatusCode.ERROR });
+									if (err instanceof Error) {
+										span.recordException(err);
+									}
+									span.end();
+
+									throw err;
+								},
+							);
+						}
+
+						return result;
+					} catch (err: unknown) {
+						span.setStatus({ code: SpanStatusCode.ERROR });
+						if (err instanceof Error) {
+							span.recordException(err);
+						}
+
+						throw err;
+					} finally {
+						span.end();
+					}
+				});
+			} as Value;
+		};
+};
+
+/**
+ * Decorator to trace a method or function by wrapping it in a new active span.
+ */
+export const trace = traceDecoratorFactory('@chialab/sveltekit-utils');

packages/utils/tsconfig.json

@@ -9,7 +9,8 @@
 		"resolveJsonModule": true,
 		"skipLibCheck": true,
 		"sourceMap": true,
-		"strict": true
+		"strict": true,
+		"target": "es2022"
 	},
 	"exclude": ["./tests/coverage/**"]
 	// Path aliases are handled by https://kit.svelte.dev/docs/configuration#alias