@plusscommunities/pluss-llm-telemetry-aws 1.0.0

package/README.md

@@ -0,0 +1,32 @@
+# `@plusscommunities/pluss-llm-telemetry-aws`
+
+Dependency-free CommonJS telemetry for Pluss Communities LLM invocations. The package exports:
+
+- `withLlmTelemetry(options)`, which records one JSON-safe `llm.invocation` event while preserving the provider result or thrown-error identity.
+- `GLOBAL_COMMUNITY_ID`, the attribution value for model calls that are not scoped to one community.
+
+The event includes the complete normalized prompt and completion, model and operation identifiers, token usage, latency, pricing evidence, feature/community attribution, trace correlation, and projected provider diagnostics. `usageIncomplete` is `1` when either input or output usage is missing. `telemetryError` distinguishes a success-extraction failure from legitimately absent provider usage. Callers must provide deployment-pinned USD token pricing and may inject extraction, logging, clock, invocation-ID, and `onTelemetryError` functions. Logger failures never replace the provider outcome; without an injected reporter they produce a minimal JSON-safe `llm.telemetry_error` line on stderr.
+
+## Import boundary
+
+Backend extensions must not import this package directly. They must use the stable core facade:
+
+```js
+const {
+  GLOBAL_COMMUNITY_ID,
+  withLlmTelemetry,
+} = require("@plusscommunities/pluss-core-aws/helper/llmTelemetry");
+```
+
+Parent backend services that do not need the legacy core package may depend on this zero-runtime-dependency package directly.
+
+## Release order
+
+Release consumers only in this order:
+
+1. Publish `@plusscommunities/pluss-llm-telemetry-aws@1.0.0`.
+2. Publish `@plusscommunities/pluss-core-aws@2.0.30`, whose facade depends on telemetry `1.0.0`.
+3. Publish every newsletter package variant at `2.0.12`, then update and release the parent `minuss-aws` support-assistant integration.
+4. After committing these extension-repository changes, update the `pluss-extension-aws` gitlink in the real parent `minuss-aws` repository to that extension commit.
+
+Do not publish core or install it in a registry-exact consumer before telemetry `1.0.0` is available.

package/index.js

@@ -0,0 +1,507 @@
+const { randomUUID } = require("node:crypto");
+
+const GLOBAL_COMMUNITY_ID = "urn:pluss:community:global";
+const MAX_JSON_DEPTH = 100;
+const MAX_ERROR_DEPTH = 12;
+const ERROR_SNAPSHOT_FIELDS = [
+	"name",
+	"message",
+	"stack",
+	"code",
+	"statusCode",
+	"httpStatusCode",
+	"requestId",
+	"retryable",
+	"$fault",
+	"$retryable",
+	"$metadata",
+	"originalStatusCode",
+	"resourceName",
+	"originalMessage",
+	"details",
+	"url",
+	"requestBodyValues",
+	"responseHeaders",
+	"responseBody",
+	"isRetryable",
+	"data",
+	"cause",
+	"errors",
+	"reason",
+	"lastError",
+];
+const ERROR_CHAIN_FIELDS = new Set(["cause", "errors", "lastError"]);
+
+const defaultCreateInvocationId = () => `llm_${randomUUID()}`;
+
+const defaultLogger = (event) =>
+	process.stdout.write(`${JSON.stringify(event)}\n`);
+
+const defaultTelemetryErrorReporter = (diagnostic) =>
+	process.stderr.write(`${JSON.stringify(diagnostic)}\n`);
+
+const readProperty = (value, key) => {
+	try {
+		return value?.[key];
+	} catch (_error) {
+		return undefined;
+	}
+};
+
+const toJsonSafe = (
+	value,
+	ancestors = new WeakSet(),
+	depth = 0,
+	includeErrorFields = false,
+	errorDepth = 0,
+) => {
+	if (value === null) return null;
+	if (["string", "boolean"].includes(typeof value)) return value;
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "bigint") return value.toString();
+	if (["undefined", "function", "symbol"].includes(typeof value)) {
+		return undefined;
+	}
+	if (typeof value !== "object") return String(value);
+	if (ancestors.has(value)) return "[Circular]";
+	if (
+		depth >= MAX_JSON_DEPTH ||
+		(includeErrorFields && errorDepth >= MAX_ERROR_DEPTH)
+	) {
+		return "[MaxDepth]";
+	}
+
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			return value.map((item) => {
+				const safeItem = toJsonSafe(
+					item,
+					ancestors,
+					depth + 1,
+					includeErrorFields,
+					errorDepth,
+				);
+				return safeItem === undefined ? null : safeItem;
+			});
+		}
+
+		const safeValue = {};
+		let keys;
+		try {
+			keys = Object.keys(value);
+		} catch (_error) {
+			return "[Unserializable]";
+		}
+		if (includeErrorFields) {
+			for (const key of ERROR_SNAPSHOT_FIELDS) {
+				if (!keys.includes(key) && readProperty(value, key) !== undefined) {
+					keys.push(key);
+				}
+			}
+		}
+		for (const key of keys) {
+			const isErrorChain = includeErrorFields && ERROR_CHAIN_FIELDS.has(key);
+			const safeProperty = toJsonSafe(
+				readProperty(value, key),
+				ancestors,
+				depth + 1,
+				isErrorChain,
+				isErrorChain ? errorDepth + 1 : errorDepth,
+			);
+			if (safeProperty !== undefined) {
+				Object.defineProperty(safeValue, key, {
+					configurable: true,
+					enumerable: true,
+					value: safeProperty,
+					writable: true,
+				});
+			}
+		}
+		return safeValue;
+	} finally {
+		ancestors.delete(value);
+	}
+};
+
+const defaultExtractError = (error) => {
+	const metadata = readProperty(error, "$metadata");
+	const directHttpStatusCode = readProperty(error, "httpStatusCode");
+	const directRequestId = readProperty(error, "requestId");
+	const directRetryable = readProperty(error, "retryable");
+	const projected = {
+		name: readProperty(error, "name"),
+		message: readProperty(error, "message"),
+		stack: readProperty(error, "stack"),
+		code: readProperty(error, "code"),
+		statusCode: readProperty(error, "statusCode"),
+		httpStatusCode:
+			directHttpStatusCode === undefined
+				? readProperty(metadata, "httpStatusCode")
+				: directHttpStatusCode,
+		requestId:
+			directRequestId === undefined
+				? readProperty(metadata, "requestId")
+				: directRequestId,
+		retryable:
+			directRetryable === undefined
+				? readProperty(error, "$retryable")
+				: directRetryable,
+		$fault: readProperty(error, "$fault"),
+		$retryable: readProperty(error, "$retryable"),
+		$metadata: metadata,
+		originalStatusCode: readProperty(error, "originalStatusCode"),
+		resourceName: readProperty(error, "resourceName"),
+		originalMessage: readProperty(error, "originalMessage"),
+		details: readProperty(error, "details"),
+		url: readProperty(error, "url"),
+		requestBodyValues: readProperty(error, "requestBodyValues"),
+		responseHeaders: readProperty(error, "responseHeaders"),
+		responseBody: readProperty(error, "responseBody"),
+		isRetryable: readProperty(error, "isRetryable"),
+		data: readProperty(error, "data"),
+		cause: readProperty(error, "cause"),
+		errors: readProperty(error, "errors"),
+		reason: readProperty(error, "reason"),
+		lastError: readProperty(error, "lastError"),
+	};
+	return projected;
+};
+
+const validatePricing = (pricing) => {
+	if (!pricing || pricing.currency !== "USD") {
+		throw new TypeError("LLM pricing currency must be USD.");
+	}
+	if (
+		!Number.isFinite(pricing.inputUsdPerMillionTokens) ||
+		pricing.inputUsdPerMillionTokens < 0
+	) {
+		throw new TypeError(
+			"LLM input token pricing must be a finite non-negative number.",
+		);
+	}
+	if (
+		!Number.isFinite(pricing.outputUsdPerMillionTokens) ||
+		pricing.outputUsdPerMillionTokens < 0
+	) {
+		throw new TypeError(
+			"LLM output token pricing must be a finite non-negative number.",
+		);
+	}
+	if (typeof pricing.source !== "string" || !pricing.source.trim()) {
+		throw new TypeError("LLM pricing source must be a non-empty string.");
+	}
+	if (typeof pricing.version !== "string" || !pricing.version.trim()) {
+		throw new TypeError("LLM pricing version must be a non-empty string.");
+	}
+};
+
+const normalizeTokenCount = (value) =>
+	Number.isSafeInteger(value) && value >= 0 ? value : null;
+
+const nullSuccessExtraction = (telemetryError) => ({
+	completion: null,
+	inputTokens: null,
+	outputTokens: null,
+	totalTokens: null,
+	stopReason: null,
+	telemetryError,
+});
+
+const isThenable = (value) => {
+	if (value === null || !["object", "function"].includes(typeof value)) {
+		return false;
+	}
+	try {
+		return typeof value.then === "function";
+	} catch (_error) {
+		return true;
+	}
+};
+
+const observeRejectedThenable = (value, onRejected) => {
+	try {
+		const promise = Promise.resolve(value);
+		Promise.prototype.then.call(promise, undefined, (error) => {
+			try {
+				onRejected(error);
+			} catch (_reportingError) {
+				// Detached diagnostics must not create another failure path.
+			}
+		});
+	} catch (error) {
+		try {
+			onRejected(error);
+		} catch (_reportingError) {
+			// Detached diagnostics must not create another failure path.
+		}
+	}
+};
+
+const suppressRejectedThenable = (value) => {
+	if (!isThenable(value)) return false;
+	observeRejectedThenable(value, () => {});
+	return true;
+};
+
+const createErrorSnapshot = (error) => {
+	const snapshot = toJsonSafe(error, new WeakSet(), 0, true);
+	if (
+		snapshot === null ||
+		typeof snapshot !== "object" ||
+		Array.isArray(snapshot)
+	) {
+		return snapshot;
+	}
+
+	for (const key of ERROR_SNAPSHOT_FIELDS) {
+		if (Object.hasOwn(snapshot, key)) continue;
+		const safeProperty = toJsonSafe(readProperty(error, key));
+		if (safeProperty !== undefined) {
+			Object.defineProperty(snapshot, key, {
+				configurable: true,
+				enumerable: true,
+				value: safeProperty,
+				writable: true,
+			});
+		}
+	}
+	return snapshot;
+};
+
+const extractSuccessSafely = (extractSuccess, result, reportTelemetryError) => {
+	try {
+		const extracted = extractSuccess(toJsonSafe(result));
+		if (isThenable(extracted)) {
+			observeRejectedThenable(extracted, (error) =>
+				reportTelemetryError("extractSuccess", error),
+			);
+			const error = new TypeError(
+				"LLM success extractors must return synchronously, not a thenable.",
+			);
+			return nullSuccessExtraction({
+				phase: "extractSuccess",
+				error: createErrorSnapshot(error),
+			});
+		}
+		return {
+			completion: toJsonSafe(extracted?.completion ?? null),
+			inputTokens: normalizeTokenCount(extracted?.inputTokens),
+			outputTokens: normalizeTokenCount(extracted?.outputTokens),
+			totalTokens: normalizeTokenCount(extracted?.totalTokens),
+			stopReason: toJsonSafe(extracted?.stopReason ?? null),
+			telemetryError: null,
+		};
+	} catch (error) {
+		return nullSuccessExtraction({
+			phase: "extractSuccess",
+			error: createErrorSnapshot(error),
+		});
+	}
+};
+
+const extractErrorSafely = (extractError, error) => {
+	const errorSnapshot = createErrorSnapshot(error);
+	const fallback = toJsonSafe(defaultExtractError(errorSnapshot));
+	try {
+		const extracted = extractError(errorSnapshot);
+		if (suppressRejectedThenable(extracted)) return fallback;
+		if (extracted && typeof extracted === "object") {
+			return toJsonSafe(extracted);
+		}
+	} catch (_error) {
+		// Fall through to the default projection captured before extraction.
+	}
+	return fallback;
+};
+
+const readClock = (clock) => {
+	try {
+		const value = clock();
+		if (suppressRejectedThenable(value)) return null;
+		return Number.isFinite(value) ? value : null;
+	} catch (_error) {
+		return null;
+	}
+};
+
+const calculateLatency = (startedAt, endedAt) => {
+	if (startedAt === null || endedAt === null) return null;
+	const latencyMs = endedAt - startedAt;
+	return Number.isFinite(latencyMs) && latencyMs >= 0 ? latencyMs : null;
+};
+
+const createInvocationIdSafely = (createInvocationId) => {
+	try {
+		const invocationId = createInvocationId();
+		if (suppressRejectedThenable(invocationId)) {
+			return defaultCreateInvocationId();
+		}
+		if (typeof invocationId === "string" && invocationId) return invocationId;
+	} catch (_error) {
+		// Fall back to the production identifier generator.
+	}
+	return defaultCreateInvocationId();
+};
+
+const createTelemetryErrorDiagnostic = (context, phase, error) => ({
+	eventType: "llm.telemetry_error",
+	schemaVersion: 1,
+	invocationId: context.invocationId,
+	phase,
+	featureId: context.featureId,
+	modelId: context.modelId,
+	operation: context.operation,
+	region: context.region,
+	communityId: context.communityId,
+	traceId: context.traceId,
+	error: createErrorSnapshot(error),
+});
+
+const reportTelemetryErrorSafely = (reporter, diagnostic) => {
+	try {
+		const reporterResult = reporter(toJsonSafe(diagnostic));
+		suppressRejectedThenable(reporterResult);
+	} catch (_error) {
+		// Reporter failure is terminally suppressed to prevent recursion.
+	}
+};
+
+const emitSafely = (logger, eventFactory, reportTelemetryError) => {
+	try {
+		const loggerResult = logger(toJsonSafe(eventFactory()));
+		if (isThenable(loggerResult)) {
+			observeRejectedThenable(loggerResult, (error) =>
+				reportTelemetryError("logger", error),
+			);
+		}
+	} catch (error) {
+		reportTelemetryError("logger", error);
+	}
+};
+
+/**
+ * Runs one provider invocation and emits a detached structured telemetry event.
+ * @param {object} options Invocation and telemetry configuration.
+ * @returns {Promise<*>} The provider result without changing its identity.
+ */
+const withLlmTelemetry = async ({
+	invoke,
+	operation,
+	modelId,
+	region = null,
+	prompt,
+	featureId,
+	communityId = GLOBAL_COMMUNITY_ID,
+	traceId,
+	pricing,
+	extractSuccess,
+	extractError = defaultExtractError,
+	logger = defaultLogger,
+	onTelemetryError = defaultTelemetryErrorReporter,
+	clock = Date.now,
+	createInvocationId = defaultCreateInvocationId,
+}) => {
+	validatePricing(pricing);
+
+	const invocationId = createInvocationIdSafely(createInvocationId);
+	const resolvedTraceId = traceId === undefined ? invocationId : traceId;
+	const diagnosticContext = {
+		invocationId,
+		featureId,
+		modelId,
+		operation,
+		region,
+		communityId,
+		traceId: resolvedTraceId,
+	};
+	const reportTelemetryError = (phase, error) =>
+		reportTelemetryErrorSafely(
+			onTelemetryError,
+			createTelemetryErrorDiagnostic(diagnosticContext, phase, error),
+		);
+	const startedAt = readClock(clock);
+
+	try {
+		const result = await invoke();
+		const endedAt = readClock(clock);
+		emitSafely(
+			logger,
+			() => {
+				const success = extractSuccessSafely(
+					extractSuccess,
+					result,
+					reportTelemetryError,
+				);
+				return {
+					eventType: "llm.invocation",
+					schemaVersion: 1,
+					invocationId,
+					operation,
+					modelId,
+					region,
+					prompt,
+					completion: success.completion,
+					inputTokens: success.inputTokens,
+					outputTokens: success.outputTokens,
+					totalTokens: success.totalTokens,
+					latencyMs: calculateLatency(startedAt, endedAt),
+					stopReason: success.stopReason,
+					error: null,
+					telemetryError: success.telemetryError,
+					usageIncomplete:
+						success.inputTokens === null || success.outputTokens === null
+							? 1
+							: 0,
+					featureId,
+					communityId,
+					traceId: resolvedTraceId,
+					outcome: "success",
+					pricingCurrency: pricing.currency,
+					inputUsdPerMillionTokens: pricing.inputUsdPerMillionTokens,
+					outputUsdPerMillionTokens: pricing.outputUsdPerMillionTokens,
+					pricingSource: pricing.source,
+					pricingVersion: pricing.version,
+				};
+			},
+			reportTelemetryError,
+		);
+		return result;
+	} catch (error) {
+		const endedAt = readClock(clock);
+		emitSafely(
+			logger,
+			() => ({
+				eventType: "llm.invocation",
+				schemaVersion: 1,
+				invocationId,
+				operation,
+				modelId,
+				region,
+				prompt,
+				completion: null,
+				inputTokens: null,
+				outputTokens: null,
+				totalTokens: null,
+				latencyMs: calculateLatency(startedAt, endedAt),
+				stopReason: null,
+				error: extractErrorSafely(extractError, error),
+				telemetryError: null,
+				usageIncomplete: 1,
+				featureId,
+				communityId,
+				traceId: resolvedTraceId,
+				outcome: "failure",
+				pricingCurrency: pricing.currency,
+				inputUsdPerMillionTokens: pricing.inputUsdPerMillionTokens,
+				outputUsdPerMillionTokens: pricing.outputUsdPerMillionTokens,
+				pricingSource: pricing.source,
+				pricingVersion: pricing.version,
+			}),
+			reportTelemetryError,
+		);
+		throw error;
+	}
+};
+
+module.exports = { GLOBAL_COMMUNITY_ID, withLlmTelemetry };

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@plusscommunities/pluss-llm-telemetry-aws",
+	"version": "1.0.0",
+	"description": "Dependency-free shared LLM invocation telemetry for Pluss Communities AWS services",
+	"main": "index.js",
+	"type": "commonjs",
+	"files": [
+		"index.js",
+		"README.md"
+	],
+	"scripts": {
+		"test": "node --test tests/*.test.js",
+		"betapatch": "npm version prepatch --preid=beta",
+		"patch": "npm version patch",
+		"betaupload": "npm publish --access public --tag beta",
+		"betaupload:p": "npm run betapatch && npm run betaupload",
+		"upload": "npm publish --access public",
+		"upload:p": "npm run patch && npm run upload"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "ISC"
+}