@aurostack/stacks 0.1.0 → 0.2.0

package/templates/py-worker/files/utils/telemetry.py

@@ -0,0 +1,154 @@
+"""
+OpenTelemetry: traces, logs and metrics over OTLP, built for OpenObserve.
+
+Two ways to connect, in order of precedence:
+- the standard OpenTelemetry variables (OTEL_EXPORTER_OTLP_ENDPOINT and
+  friends), which the exporters read themselves, for any OTLP backend;
+- OPENOBSERVE_URL + OPENOBSERVE_ORG + OPENOBSERVE_TOKEN, from which the
+  OpenObserve endpoints and the org ingestion-token header are built.
+With neither, setup_telemetry() does nothing and job_span() is a no-op.
+"""
+import base64
+import logging
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+
+from opentelemetry import trace
+
+DEFAULT_SERVICE_NAME = "acme-py"
+
+_providers: list = []
+
+
+@dataclass
+class TelemetryConfig:
+    enabled: bool
+    service_name: str
+    environment: str
+    # Signal URLs; empty means the exporters resolve them from OTEL_* vars.
+    urls: dict = field(default_factory=dict)
+    headers: dict = field(default_factory=dict)
+
+
+def resolve_telemetry(env=os.environ) -> TelemetryConfig:
+    service_name = env.get("OTEL_SERVICE_NAME") or DEFAULT_SERVICE_NAME
+    environment = env.get("APP_ENV") or "development"
+    off = TelemetryConfig(False, service_name, environment)
+
+    if env.get("OTEL_SDK_DISABLED") == "true":
+        return off
+    if env.get("OTEL_EXPORTER_OTLP_ENDPOINT"):
+        return TelemetryConfig(True, service_name, environment)
+
+    url, org, token = (
+        env.get("OPENOBSERVE_URL"),
+        env.get("OPENOBSERVE_ORG"),
+        env.get("OPENOBSERVE_TOKEN"),
+    )
+    if not (url and org and token):
+        return off
+
+    # OTLP/HTTP endpoints live under /api/<org>; an org ingestion token
+    # authenticates as `<org>:<token>`. Logs and traces land in the stream
+    # named here, one per service.
+    base = f"{url.rstrip('/')}/api/{org}"
+    credentials = base64.b64encode(f"{org}:{token}".encode()).decode()
+    return TelemetryConfig(
+        True,
+        service_name,
+        environment,
+        urls={
+            "traces": f"{base}/v1/traces",
+            "logs": f"{base}/v1/logs",
+            "metrics": f"{base}/v1/metrics",
+        },
+        headers={
+            "Authorization": f"Basic {credentials}",
+            "stream-name": env.get("OPENOBSERVE_STREAM") or service_name,
+        },
+    )
+
+
+def setup_telemetry() -> bool:
+    """Start exporting, if connection settings are present. Call once, first."""
+    config = resolve_telemetry()
+    if not config.enabled:
+        return False
+
+    # Imported here so a worker without telemetry never loads the SDK.
+    from opentelemetry._logs import set_logger_provider
+    from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+    from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    from opentelemetry.instrumentation.redis import RedisInstrumentor
+    from opentelemetry.metrics import set_meter_provider
+    from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+    from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+    from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    def exporter_args(signal: str) -> dict:
+        if not config.urls:
+            return {}
+        return {"endpoint": config.urls[signal], "headers": config.headers}
+
+    resource = Resource.create(
+        {
+            "service.name": config.service_name,
+            "deployment.environment.name": config.environment,
+        }
+    )
+
+    tracer_provider = TracerProvider(resource=resource)
+    tracer_provider.add_span_processor(
+        BatchSpanProcessor(OTLPSpanExporter(**exporter_args("traces")))
+    )
+    trace.set_tracer_provider(tracer_provider)
+
+    logger_provider = LoggerProvider(resource=resource)
+    logger_provider.add_log_record_processor(
+        BatchLogRecordProcessor(OTLPLogExporter(**exporter_args("logs")))
+    )
+    set_logger_provider(logger_provider)
+    # Every utils.logger.Logger propagates to the root logger.
+    logging.getLogger().addHandler(LoggingHandler(logger_provider=logger_provider))
+
+    meter_provider = MeterProvider(
+        resource=resource,
+        metric_readers=[
+            PeriodicExportingMetricReader(
+                OTLPMetricExporter(**exporter_args("metrics"))
+            )
+        ],
+    )
+    set_meter_provider(meter_provider)
+
+    RedisInstrumentor().instrument()
+    _providers.extend([tracer_provider, logger_provider, meter_provider])
+    return True
+
+
+def shutdown_telemetry() -> None:
+    """Flush whatever is buffered. Safe to call when telemetry is off."""
+    for provider in _providers:
+        provider.shutdown()
+
+
+@contextmanager
+def job_span(queue_name: str, job):
+    """One span per job, so each job is its own trace in OpenObserve."""
+    tracer = trace.get_tracer("worker")
+    with tracer.start_as_current_span(
+        f"process {queue_name}",
+        attributes={"messaging.system": "bullmq", "messaging.destination.name": queue_name, "bullmq.job.id": str(job.id)},
+    ) as span:
+        try:
+            yield span
+        except Exception as error:
+            span.record_exception(error)
+            span.set_status(trace.Status(trace.StatusCode.ERROR, str(error)))
+            raise

package/templates/py-worker/files/utils/temporal.py

@@ -0,0 +1,55 @@
+from temporalio.client import Client, TLSConfig
+from temporalio.worker import Worker
+
+from config import CONFIG, TemporalTLS
+from temporal.activities import greet
+from temporal.workflows import Example
+
+
+def temporal_tls(tls: TemporalTLS) -> TLSConfig | bool:
+    """
+    mTLS settings from PEM strings; none at all means plaintext (False).
+    Escaped \\n are unescaped, so a certificate fits on one line of an env file.
+    """
+    if not (tls.ca or tls.cert or tls.key):
+        return False
+    if not (tls.cert and tls.key):
+        raise ValueError("TEMPORAL_TLS_CERT and TEMPORAL_TLS_KEY must be set together")
+
+    def pem(value: str) -> bytes:
+        return value.replace("\\n", "\n").encode()
+
+    return TLSConfig(
+        server_root_ca_cert=pem(tls.ca) if tls.ca else None,
+        client_cert=pem(tls.cert),
+        client_private_key=pem(tls.key),
+    )
+
+
+async def create_temporal_worker() -> Worker:
+    """
+    Connect to Temporal and build a worker for TEMPORAL_TASK_QUEUE, running the
+    workflows and activities in temporal/. Register new ones in the lists below.
+    """
+    settings = CONFIG.env.temporal
+    interceptors = []
+    # @feature:start telemetry
+    # A span per workflow and activity, continuing the trace of whatever
+    # started the workflow; a no-op while telemetry is off.
+    from temporalio.contrib.opentelemetry import TracingInterceptor
+
+    interceptors.append(TracingInterceptor())
+    # @feature:end
+
+    client = await Client.connect(
+        settings.address,
+        namespace=settings.namespace,
+        tls=temporal_tls(settings.tls),
+        interceptors=interceptors,
+    )
+    return Worker(
+        client,
+        task_queue=settings.task_queue,
+        workflows=[Example],
+        activities=[greet],
+    )

package/templates/py-worker/files/utils/worker.py

@@ -5,6 +5,7 @@ from urllib.parse import urlparse, quote, urlencode
 from config import CONFIG, Redis
 from utils.db import DB
 from utils.logger import Logger
+from utils.telemetry import job_span  # @feature telemetry
 
 
 def build_redis_url(options: Redis):
@@ -39,9 +40,19 @@ def create_worker(queue_name: str, process_function: Callable, concurrency: int
         An instance of BullMQ Worker.
     """
     connection = build_redis_url(CONFIG.env.redis)
+
+    processor = process_function
+    # @feature:start telemetry
+    async def traced(job: Job, token: str):
+        with job_span(queue_name, job):
+            return await process_function(job, token)
+
+    processor = traced
+    # @feature:end
+
     worker = Worker(
         queue_name,
-        process_function,
+        processor,
         {
             "connection": connection,
             "autorun": True,

package/templates/py-worker/files/worker.py

@@ -4,6 +4,8 @@ import asyncio
 import signal
 from utils.logger import Logger
 from utils.worker import create_worker
+from utils.telemetry import setup_telemetry, shutdown_telemetry  # @feature telemetry
+from utils.temporal import create_temporal_worker  # @feature temporal
 
 # import worker processes
 from workers.hello.process import hello_process
@@ -11,6 +13,7 @@ logger = Logger("worker")
 
 
 async def main():
+    setup_telemetry()  # @feature telemetry
     logger.info("Starting Python 3.14 Worker...")
     shutdown_event = asyncio.Event()
     loop = asyncio.get_running_loop()
@@ -27,6 +30,12 @@ async def main():
 
     # Add workers
     hello = create_worker("hello", hello_process)
+    # @feature:start temporal
+    temporal_worker = await create_temporal_worker()
+    temporal_run = asyncio.create_task(temporal_worker.run())
+    # If the Temporal worker stops on its own (a fatal error), stop everything.
+    temporal_run.add_done_callback(lambda _: shutdown_event.set())
+    # @feature:end
 
     logger.info("Workers started and waiting for jobs.")
     try:
@@ -35,7 +44,14 @@ async def main():
         logger.info("Cleaning up workers...")
         # Close workers gracefully
         await hello.close()
+        # @feature:start temporal
+        # Stops polling and waits for running activities to finish.
+        if not temporal_run.done():
+            await temporal_worker.shutdown()
+        await temporal_run
+        # @feature:end
         logger.info("Workers shut down successfully.")
+        shutdown_telemetry()  # @feature telemetry
 
 if __name__ == "__main__":
     asyncio.run(main())

package/templates/py-worker/template.json

@@ -55,6 +55,42 @@
 			"files": [
 				".forgejo/**"
 			]
+		},
+		"telemetry": {
+			"title": "OpenTelemetry → OpenObserve",
+			"description": "Traces, logs and metrics over OTLP (set OPENOBSERVE_URL/ORG/TOKEN, or any OTEL_* backend), with a span per job and Redis instrumentation. Off at runtime until connected.",
+			"default": true,
+			"files": [
+				"utils/telemetry.py"
+			],
+			"requirements": [
+				"googleapis-common-protos",
+				"opentelemetry-api",
+				"opentelemetry-exporter-http-transport",
+				"opentelemetry-exporter-otlp-common",
+				"opentelemetry-exporter-otlp-proto-common",
+				"opentelemetry-exporter-otlp-proto-http",
+				"opentelemetry-instrumentation",
+				"opentelemetry-instrumentation-redis",
+				"opentelemetry-proto",
+				"opentelemetry-sdk",
+				"opentelemetry-semantic-conventions",
+				"protobuf",
+				"wrapt"
+			]
+		},
+		"temporal": {
+			"title": "Temporal worker",
+			"description": "Runs durable workflows and activities from temporal/ (an example of each included) on its own TEMPORAL_TASK_QUEUE, next to the BullMQ consumers, with a span per workflow and activity when telemetry is on. Pair with the API's temporal feature, which starts them.",
+			"files": [
+				"utils/temporal.py",
+				"temporal/**"
+			],
+			"requirements": [
+				"nexus-rpc",
+				"temporalio",
+				"types-protobuf"
+			]
 		}
 	},
 	"hooks": [

package/templates/react-app/derive.sh

@@ -52,7 +52,7 @@ done
 
 echo "==> flattening packages -> src/shared"
 mkdir -p "$DST/src/shared"
-for pkg in ui api auth layouts hooks types; do
+for pkg in ui api auth layouts hooks types telemetry; do
 	cp -r "$SRC/packages/$pkg/src" "$DST/src/shared/$pkg"
 done
 # The brand tokens live in the config package in the monorepo because three
@@ -94,6 +94,7 @@ find "$DST/src" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.css' \) -pr
 		-e "s#@acme/auth#@/shared/auth#g" \
 		-e "s#@acme/layouts#@/shared/layouts#g" \
 		-e "s#@acme/hooks#@/shared/hooks#g" \
+		-e "s#@acme/telemetry#@/shared/telemetry#g" \
 		-e "s#@acme/types#@/shared/types#g"
 
 # The auth screens moved one level deeper than their components and lib, so

package/templates/react-app/files/.env.example

@@ -11,6 +11,17 @@ PORT='3000'
 # Needed when you reach the dev server through a tunnel or a wildcard DNS name.
 VITE_APP_ALLOWED_HOSTS=''
 
+# @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
+
 # @feature:start marketing
 # The canonical public origin — the ONE origin that may be indexed. Must match
 # PRODUCTION_ORIGIN in src/features/seo/routes.ts. Anything else (previews,

package/templates/react-app/files/package.json

@@ -26,6 +26,8 @@
 	},
 	"dependencies": {
 		"@fontsource-variable/inter": "^5.3.0",
+		"@openobserve/browser-logs": "^0.4.3",
+		"@openobserve/browser-rum": "^0.4.3",
 		"@radix-ui/react-label": "^2.1.7",
 		"@radix-ui/react-popover": "^1.1.21",
 		"@radix-ui/react-select": "^2.3.4",

package/templates/react-app/files/src/lib/env.ts

@@ -26,3 +26,13 @@ export const APP_ORIGIN = window.location.origin;
  */
 export const SITE_URL = (env.VITE_APP_SITE_URL as string | undefined) ?? '';
 // @feature:end
+
+// @feature:start telemetry
+/** OpenObserve browser monitoring (see @/shared/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-app/files/src/main.tsx

@@ -1,5 +1,7 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+import { initTelemetry } from '@/shared/telemetry'; // @feature telemetry
+import { API_URL, TELEMETRY } from '@/lib/env'; // @feature telemetry
 import { RouterProvider } from 'react-router';
 import '@/shared/ui/styles/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-app', ...TELEMETRY, apiUrls: [API_URL] }); // @feature telemetry
+
 createRoot(document.getElementById('root')!).render(
 	<StrictMode>
 		<Providers>

package/templates/react-app/files/src/shared/auth/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 '@/shared/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-app/files/src/shared/layouts/error-boundary.tsx

@@ -1,6 +1,7 @@
 import { Component, type ErrorInfo, type ReactNode } from 'react';
 import { Button } from '@/shared/ui';
 import { StateScreen } from './states/state-screen';
+import { reportError } from '@/shared/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-app/files/src/shared/telemetry/index.ts

@@ -0,0 +1,80 @@
+// @/shared/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-app/template.json

@@ -189,6 +189,20 @@
 					"secrets"
 				]
 			}
+		},
+		"telemetry": {
+			"title": "Browser monitoring → OpenObserve",
+			"description": "OpenObserve RUM and logs: 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": [
+				"src/shared/telemetry/**"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@openobserve/browser-logs",
+					"@openobserve/browser-rum"
+				]
+			}
 		}
 	},
 	"hooks": [
@@ -199,7 +213,7 @@
 		},
 		{
 			"title": "yarn install",
-			"run": "yarn install",
+			"run": "yarn install --no-immutable",
 			"optional": true
 		},
 		{

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

@@ -14,3 +14,14 @@ VITE_APP_ADMIN_HOST='http://localhost:3003'
 
 # This app's own dev port.
 PORT='3003'
+
+# @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/admin/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",
 		"lucide-react": "^1.17.0",

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

@@ -10,3 +10,13 @@ export const ADMIN_URL = env.VITE_APP_ADMIN_HOST as string;
 export const CLIENT_URL = env.VITE_APP_CLIENT_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/admin/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-admin', ...TELEMETRY, apiUrls: [API_URL] }); // @feature telemetry
+
 createRoot(document.getElementById('root')!).render(
 	<StrictMode>
 		<Providers>

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

@@ -14,3 +14,14 @@ VITE_APP_ADMIN_HOST='http://localhost:3003'
 
 # This app's own dev port.
 PORT='3001'
+
+# @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/auth/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",
 		"formik": "^2.4.9",

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

@@ -6,3 +6,13 @@ export const API_URL = env.VITE_APP_API_URL;
 /** Terms and Privacy live on the marketing site, which is a different origin. */
 export const LANDING_URL = env.VITE_APP_LANDING;
 export const AUTH_URL = window.location.origin;
+
+// @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/auth/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-auth', ...TELEMETRY, apiUrls: [API_URL] }); // @feature telemetry
+
 createRoot(document.getElementById('root')!).render(
 	<StrictMode>
 		<Providers>