@aurostack/stacks 0.1.0 → 0.2.0

package/templates/react-monorepo/files/apps/client/.env.example

@@ -14,3 +14,14 @@ VITE_APP_ADMIN_HOST='http://localhost:3003'
 
 # This app's own dev port.
 PORT='3002'
+
+# @feature:start telemetry
+# OpenObserve browser monitoring (RUM): page views, errors, slow requests, and
+# trace headers on API calls. Leave empty and it stays off. The client token is
+# a RUM token (OpenObserve → Ingestion → RUM): write-only and meant to ship in
+# the bundle — never the backend's ingestion token.
+# The instance must list this app's origin in ZO_CORS_ALLOWED_ORIGINS.
+VITE_OPENOBSERVE_URL='https://o2.aurostack.co'
+VITE_OPENOBSERVE_ORG=''
+VITE_OPENOBSERVE_CLIENT_TOKEN=''
+# @feature:end

package/templates/react-monorepo/files/apps/client/package.json

@@ -15,6 +15,7 @@
 		"@acme/api": "workspace:*",
 		"@acme/auth": "workspace:*",
 		"@acme/layouts": "workspace:*",
+		"@acme/telemetry": "workspace:*",
 		"@acme/ui": "workspace:*",
 		"@reduxjs/toolkit": "^2.12.0",
 		"apexcharts": "^6.5.0",

package/templates/react-monorepo/files/apps/client/src/lib/env.ts

@@ -10,3 +10,13 @@ export const CLIENT_URL = env.VITE_APP_CLIENT_HOST as string;
 export const ADMIN_URL = env.VITE_APP_ADMIN_HOST as string;
 /** The public marketing site (logout destination). */
 export const LANDING_URL = env.VITE_APP_LANDING as string;
+
+// @feature:start telemetry
+/** OpenObserve browser monitoring (see @acme/telemetry); unset keeps it off. */
+export const TELEMETRY = {
+	url: env.VITE_OPENOBSERVE_URL as string | undefined,
+	org: env.VITE_OPENOBSERVE_ORG as string | undefined,
+	clientToken: env.VITE_OPENOBSERVE_CLIENT_TOKEN as string | undefined,
+	environment: env.MODE
+};
+// @feature:end

package/templates/react-monorepo/files/apps/client/src/main.tsx

@@ -1,5 +1,7 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+import { initTelemetry } from '@acme/telemetry'; // @feature telemetry
+import { API_URL, TELEMETRY } from './lib/env'; // @feature telemetry
 import { RouterProvider } from 'react-router';
 import '@acme/ui/globals.css';
 import { Providers } from './app/providers';
@@ -10,6 +12,8 @@ import { router } from './app/router';
 // evaluating and `providers` has already called `configureApi` at module scope,
 // so the fetch races the session check instead of queueing behind it.
 
+initTelemetry({ service: 'acme-client', ...TELEMETRY, apiUrls: [API_URL] }); // @feature telemetry
+
 createRoot(document.getElementById('root')!).render(
 	<StrictMode>
 		<Providers>

package/templates/react-monorepo/files/apps/landing/.env.example

@@ -18,3 +18,14 @@ PORT='3000'
 # Canonical public URL, used for sitemap/robots/OG tags at build time.
 VITE_APP_SITE_URL='http://localhost:3000'
 VITE_APP_SUPPORT_EMAIL='support@example.com'
+
+# @feature:start telemetry
+# OpenObserve browser monitoring (RUM): page views, errors, slow requests, and
+# trace headers on API calls. Leave empty and it stays off. The client token is
+# a RUM token (OpenObserve → Ingestion → RUM): write-only and meant to ship in
+# the bundle — never the backend's ingestion token.
+# The instance must list this app's origin in ZO_CORS_ALLOWED_ORIGINS.
+VITE_OPENOBSERVE_URL='https://o2.aurostack.co'
+VITE_OPENOBSERVE_ORG=''
+VITE_OPENOBSERVE_CLIENT_TOKEN=''
+# @feature:end

package/templates/react-monorepo/files/apps/landing/package.json

@@ -15,6 +15,7 @@
 		"@acme/api": "workspace:*",
 		"@acme/auth": "workspace:*",
 		"@acme/layouts": "workspace:*",
+		"@acme/telemetry": "workspace:*",
 		"@acme/types": "workspace:*",
 		"@acme/ui": "workspace:*",
 		"@reduxjs/toolkit": "^2.12.0",

package/templates/react-monorepo/files/apps/landing/src/lib/env.ts

@@ -8,3 +8,13 @@ export const CLIENT_HOST = env.VITE_APP_CLIENT_HOST;
  *  actually posts. Falsy when the build arg is missing; the UI hides the block
  *  rather than rendering `mailto:undefined`. */
 export const SUPPORT_EMAIL = env.VITE_APP_SUPPORT_EMAIL;
+
+// @feature:start telemetry
+/** OpenObserve browser monitoring (see @acme/telemetry); unset keeps it off. */
+export const TELEMETRY = {
+	url: env.VITE_OPENOBSERVE_URL as string | undefined,
+	org: env.VITE_OPENOBSERVE_ORG as string | undefined,
+	clientToken: env.VITE_OPENOBSERVE_CLIENT_TOKEN as string | undefined,
+	environment: env.MODE
+};
+// @feature:end

package/templates/react-monorepo/files/apps/landing/src/main.tsx

@@ -1,10 +1,14 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+import { initTelemetry } from '@acme/telemetry'; // @feature telemetry
+import { API_URL, TELEMETRY } from './lib/env'; // @feature telemetry
 import { RouterProvider } from 'react-router';
 import '@acme/ui/globals.css';
 import { Providers } from './app/providers';
 import { router } from './app/router';
 
+initTelemetry({ service: 'acme-landing', ...TELEMETRY, apiUrls: [API_URL] }); // @feature telemetry
+
 createRoot(document.getElementById('root')!).render(
 	<StrictMode>
 		<Providers>

package/templates/react-monorepo/files/packages/auth/package.json

@@ -11,6 +11,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
+		"@acme/telemetry": "workspace:*",
 		"better-auth": "^1.6.2"
 	},
 	"peerDependencies": {

package/templates/react-monorepo/files/packages/auth/src/provider.tsx

@@ -3,6 +3,7 @@ import { useDispatch } from 'react-redux';
 import { getAuthClient } from './client';
 import { sessionCleared, sessionLoaded, sessionLoading, type AuthUser } from './slice';
 import { AUTH_BROADCAST_CHANNEL } from './logout';
+import { setTelemetryUser } from '@acme/telemetry'; // @feature telemetry
 
 function toAuthUser(user: Record<string, unknown> | null | undefined): AuthUser | null {
 	if (!user) return null;
@@ -33,6 +34,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
 		}
 		const user = (session.data?.user as Record<string, unknown> | undefined) ?? null;
 		dispatch(sessionLoaded(toAuthUser(user)));
+		setTelemetryUser(user ? { id: String(user.id) } : null); // @feature telemetry
 	}, [session.isPending, session.data, dispatch]);
 
 	useEffect(() => {

package/templates/react-monorepo/files/packages/layouts/package.json

@@ -11,6 +11,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
+		"@acme/telemetry": "workspace:*",
 		"@acme/ui": "workspace:*",
 		"lucide-react": "^1.17.0"
 	},

package/templates/react-monorepo/files/packages/layouts/src/error-boundary.tsx

@@ -1,6 +1,7 @@
 import { Component, type ErrorInfo, type ReactNode } from 'react';
 import { Button } from '@acme/ui';
 import { StateScreen } from './states/state-screen';
+import { reportError } from '@acme/telemetry'; // @feature telemetry
 
 type ErrorBoundaryProps = {
 	children: ReactNode;
@@ -21,6 +22,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 
 	componentDidCatch(error: Error, info: ErrorInfo): void {
 		console.error('ErrorBoundary caught an error', error, info);
+		reportError(error, { componentStack: info.componentStack }); // @feature telemetry
 	}
 
 	render(): ReactNode {

package/templates/react-monorepo/files/packages/telemetry/eslint.config.mjs

@@ -0,0 +1,3 @@
+import config from '@acme/config/eslint';
+
+export default config;

package/templates/react-monorepo/files/packages/telemetry/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "@acme/telemetry",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"lint": "eslint .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@openobserve/browser-logs": "^0.4.3",
+		"@openobserve/browser-rum": "^0.4.3"
+	},
+	"devDependencies": {
+		"@acme/config": "workspace:*"
+	}
+}

package/templates/react-monorepo/files/packages/telemetry/src/index.ts

@@ -0,0 +1,80 @@
+// @acme/telemetry — browser monitoring (RUM) and logs, sent to OpenObserve.
+//
+// Page views, errors, slow resources and user actions, plus console errors as
+// logs. Requests to the app's own API carry a W3C `traceparent` header, so a
+// click links to the backend trace it caused. The SDK finishes starting a
+// moment after init (its session store is async), so the first request or two
+// of a page load (typically the session check) go out without the header.
+// Off until connection settings are passed; everything here is then a no-op.
+import { DefaultPrivacyLevel, openobserveRum } from '@openobserve/browser-rum';
+import { openobserveLogs } from '@openobserve/browser-logs';
+
+export interface TelemetryOptions {
+	/** Service name, e.g. `acme-client` — one per app. */
+	service: string;
+	/** OpenObserve base URL, e.g. `https://o2.example.com`. */
+	url?: string;
+	/** The project's organization identifier. */
+	org?: string;
+	/**
+	 * A RUM client token (Ingestion → RUM). Write-only and built for shipping
+	 * in a bundle — never the backend's ingestion token.
+	 */
+	clientToken?: string;
+	/** `development`, `production`, … — Vite's `import.meta.env.MODE`. */
+	environment?: string;
+	version?: string;
+	/** Backend origin(s) whose requests should carry trace headers. */
+	apiUrls?: string[];
+	/** Share of sessions to record for replay, 0–100. Off by default. */
+	sessionReplaySampleRate?: number;
+}
+
+let started = false;
+
+export function initTelemetry(options: TelemetryOptions): boolean {
+	const { url, org, clientToken } = options;
+	if (started || !url || !org || !clientToken) return false;
+
+	// The SDK takes a bare host (no scheme) plus an explicit plain-HTTP flag.
+	const { host, protocol } = new URL(url);
+	const common = {
+		clientToken,
+		site: host,
+		organizationIdentifier: org,
+		insecureHTTP: protocol === 'http:',
+		service: options.service,
+		env: options.environment,
+		version: options.version
+	};
+
+	openobserveRum.init({
+		...common,
+		applicationId: options.service,
+		sessionSampleRate: 100,
+		sessionReplaySampleRate: options.sessionReplaySampleRate ?? 0,
+		defaultPrivacyLevel: DefaultPrivacyLevel.MASK_USER_INPUT,
+		trackResources: true,
+		trackLongTasks: true,
+		trackUserInteractions: true,
+		allowedTracingUrls: (options.apiUrls ?? []).filter(Boolean).map((match) => ({
+			match,
+			propagatorTypes: ['tracecontext' as const]
+		}))
+	});
+	openobserveLogs.init({ ...common, forwardErrorsToLogs: true });
+	started = true;
+	return true;
+}
+
+/** Report a handled error — e.g. from an error boundary. */
+export function reportError(error: unknown, context?: object): void {
+	if (started) openobserveRum.addError(error, context);
+}
+
+/** Tie the session to a signed-in user (id only), or clear it on logout. */
+export function setTelemetryUser(user: { id: string } | null): void {
+	if (!started) return;
+	if (user) openobserveRum.setUser({ id: user.id });
+	else openobserveRum.clearUser();
+}

package/templates/react-monorepo/files/packages/telemetry/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "@acme/config/tsconfig/react.json",
+	"include": ["src"]
+}

package/templates/react-monorepo/template.json

@@ -81,6 +81,52 @@
 				"packages/types/**"
 			]
 		},
+		"telemetry": {
+			"title": "Browser monitoring → OpenObserve",
+			"description": "The @acme/telemetry package: OpenObserve RUM and logs in every app — page views, errors (including the error boundary's), slow resources, user actions, the signed-in user id, and traceparent headers on API calls so frontend and backend traces link up. Session replay is off unless a project turns it on. Off at runtime until VITE_OPENOBSERVE_* are set.",
+			"default": true,
+			"files": [
+				"packages/telemetry/**"
+			],
+			"packageJson": [
+				{
+					"file": "apps/admin/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "apps/auth/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "apps/client/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "apps/landing/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "packages/layouts/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "packages/auth/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				}
+			]
+		},
 		"app-auth": {
 			"title": "Auth app",
 			"description": "Login, signup, forgot/reset password, email verification. The one app that owns the session; the others redirect here.",
@@ -208,7 +254,7 @@
 		},
 		{
 			"title": "yarn install",
-			"run": "yarn install",
+			"run": "yarn install --no-immutable",
 			"optional": true
 		},
 		{

package/templates/nest-api/files/src/common/controllers/metrics.controller.ts

@@ -1,21 +0,0 @@
-import { Controller, Get, Res } from '@nestjs/common';
-import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
-import { SkipThrottle } from '@nestjs/throttler'; // @feature rate-limit
-import { AllowAnonymous } from '@thallesp/nestjs-better-auth';
-import { PrometheusController } from '@willsoto/nestjs-prometheus';
-import type { Response } from 'express';
-
-@ApiTags('App')
-@Controller()
-// @feature:start rate-limit
-// Scraped on a fixed interval by Prometheus; already gated by basic auth.
-@SkipThrottle()
-// @feature:end
-export class MetricsController extends PrometheusController {
-	@Get()
-	@ApiExcludeEndpoint()
-	@AllowAnonymous()
-	async index(@Res({ passthrough: true }) response: Response): Promise<string> {
-		return super.index(response);
-	}
-}

package/templates/nest-api/files/src/common/interceptors/index.ts

@@ -1 +0,0 @@
-export * from './metrics.interceptor'; // @feature observability

package/templates/nest-api/files/src/common/interceptors/metrics.interceptor.ts

@@ -1,37 +0,0 @@
-import {
-	Injectable,
-	NestInterceptor,
-	ExecutionContext,
-	CallHandler
-} from '@nestjs/common';
-import { InjectMetric } from '@willsoto/nestjs-prometheus';
-import { Histogram } from 'prom-client';
-import { Observable, tap } from 'rxjs';
-
-@Injectable()
-export class MetricsInterceptor implements NestInterceptor {
-	constructor(
-		@InjectMetric('http_request_duration_seconds')
-		private readonly histogram: Histogram<string>
-	) {}
-
-	intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
-		if (context.getType() !== 'http') {
-			return next.handle();
-		}
-
-		const http = context.switchToHttp();
-		const req = http.getRequest();
-		const res = http.getResponse();
-		const stop = this.histogram.startTimer();
-
-		const observe = () =>
-			stop({
-				method: req.method,
-				route: req.route?.path ?? 'unmatched',
-				status: res.statusCode
-			});
-
-		return next.handle().pipe(tap({ next: observe, error: observe }));
-	}
-}

package/templates/nest-api/files/src/common/modules/metrics.module.ts

@@ -1,28 +0,0 @@
-import { Module } from '@nestjs/common';
-import { APP_INTERCEPTOR } from '@nestjs/core';
-import {
-	makeHistogramProvider,
-	PrometheusModule
-} from '@willsoto/nestjs-prometheus';
-import { MetricsController } from '../controllers';
-import { MetricsInterceptor } from '../interceptors';
-
-@Module({
-	imports: [
-		PrometheusModule.register({
-			defaultLabels: { app: 'acme-api' },
-			defaultMetrics: { enabled: true },
-			controller: MetricsController
-		})
-	],
-	providers: [
-		makeHistogramProvider({
-			name: 'http_request_duration_seconds',
-			help: 'Duration of HTTP requests in seconds',
-			labelNames: ['method', 'route', 'status'],
-			buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5]
-		}),
-		{ provide: APP_INTERCEPTOR, useClass: MetricsInterceptor }
-	]
-})
-export class MetricsModule {}