enhancement(env): add metrics configuration and validation

Author: AlexandrNel

.env.example

@@ -6,6 +6,7 @@ NEXT_PUBLIC_FARO_APP_NAME=next-frontend
 NEXT_PUBLIC_FARO_APP_NAMESPACE=nextjs-example
 NEXT_PUBLIC_FARO_APP_VERSION=1.0.0
 NEXT_PUBLIC_APP_ENV=development
+NEXT_PUBLIC_METRICS_ENABLED=false
 
 # Next App BACKEND Instrumentation
 ## Example assumes that the collector is running on the same machine

.env.production

@@ -0,0 +1,24 @@
+NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/v1
+PORT=3000
+# Next App FRONTEND Instrumentation
+NEXT_PUBLIC_FARO_URL=http://localhost:12347/collect
+NEXT_PUBLIC_FARO_APP_NAME=ttopen-frontend
+NEXT_PUBLIC_FARO_APP_NAMESPACE=ttopen-front
+NEXT_PUBLIC_FARO_APP_VERSION=1.0.0
+NEXT_PUBLIC_APP_ENV=development
+NEXT_PUBLIC_METRICS_ENABLED=true
+
+# Next App BACKEND Instrumentation
+## Example assumes that the collector is running on the same machine
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+## Force protobuf
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+## Set Backend service name
+OTEL_SERVICE_NAME=next-backend
+## Customize resource attributes, namespace is a recommended attribute
+OTEL_RESOURCE_ATTRIBUTES=service.namespace=nextjs-ttopen
+
+# OTel collector
+GRAFANA_CLOUD_USERNAME=
+GRAFANA_CLOUD_API_KEY=
+GRAFANA_CLOUD_ENDPOINT=

Dockerfile.prod

@@ -20,6 +20,7 @@ ARG NEXT_PUBLIC_API_BASE_URL
 ARG NEXT_PUBLIC_FARO_URL
 ARG NEXT_PUBLIC_FARO_APP_VERSION
 ARG NEXT_PUBLIC_APP_ENV
+ARG NEXT_PUBLIC_METRICS_ENABLED
 ARG SKIP_ENV_VALIDATION=false
 
 ENV NEXT_PUBLIC_API_BASE_URL=$NEXT_PUBLIC_API_BASE_URL \
@@ -29,7 +30,8 @@ ENV NEXT_PUBLIC_API_BASE_URL=$NEXT_PUBLIC_API_BASE_URL \
     NEXT_PUBLIC_FARO_APP_VERSION=$NEXT_PUBLIC_FARO_APP_VERSION \
     NEXT_PUBLIC_APP_ENV=$NEXT_PUBLIC_APP_ENV \
     SKIP_ENV_VALIDATION=$SKIP_ENV_VALIDATION \
-    NEXT_TELEMETRY_DISABLED=1
+    NEXT_TELEMETRY_DISABLED=1 \
+    NEXT_PUBLIC_METRICS_ENABLED=$NEXT_PUBLIC_METRICS_ENABLED
 
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .

src/shared/config/env.client.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod/v4';
+
+export const envSchemaClient = z.object({
+  NEXT_PUBLIC_API_BASE_URL: z.url('NEXT_PUBLIC_API_BASE_URL должен быть валидным URL'),
+  NEXT_PUBLIC_FARO_URL: z.url(
+    'NEXT_PUBLIC_FARO_URL должен быть валидным URL (например, http://alloy:12347/collect)'
+  ),
+  NEXT_PUBLIC_FARO_APP_NAME: z
+    .string({
+      error: 'Имя приложения для Faro обязательно',
+    })
+    .min(1, 'Имя приложения не может быть пустым'),
+  NEXT_PUBLIC_FARO_APP_NAMESPACE: z
+    .string({
+      error: 'Namespace приложения обязателен',
+    })
+    .min(1, 'Namespace не может быть пустым'),
+  NEXT_PUBLIC_FARO_APP_VERSION: z.string().default('1.0.0'),
+  NEXT_PUBLIC_APP_ENV: z
+    .string({
+      error: 'Окружение (APP_ENV) обязательно',
+    })
+    .min(1, 'Окружение не может быть пустым'),
+  NEXT_PUBLIC_METRICS_ENABLED: z
+    .enum(['true', 'false'], {
+      error: 'NEXT_PUBLIC_METRICS_ENABLED - обязателен',
+    })
+    .transform((v) => v === 'true'),
+});
+
+const _env = envSchemaClient.safeParse({
+  NEXT_PUBLIC_API_BASE_URL: process.env.NEXT_PUBLIC_API_BASE_URL,
+  NEXT_PUBLIC_FARO_URL: process.env.NEXT_PUBLIC_FARO_URL,
+  NEXT_PUBLIC_FARO_APP_NAME: process.env.NEXT_PUBLIC_FARO_APP_NAME,
+  NEXT_PUBLIC_FARO_APP_NAMESPACE: process.env.NEXT_PUBLIC_FARO_APP_NAMESPACE,
+  NEXT_PUBLIC_FARO_APP_VERSION: process.env.NEXT_PUBLIC_FARO_APP_VERSION,
+  NEXT_PUBLIC_APP_ENV: process.env.NEXT_PUBLIC_APP_ENV,
+  NEXT_PUBLIC_METRICS_ENABLED: process.env.NEXT_PUBLIC_METRICS_ENABLED,
+});
+
+if (!_env.success) {
+  console.error('❌ [ENV VALIDATION ERROR]:', z.treeifyError(_env.error).properties);
+  if (typeof window === 'undefined') {
+    throw new Error('Client env validation failed on server-side rendering');
+  }
+}
+
+export type ClientEnv = z.infer<typeof envSchemaClient>;
+
+export const env: ClientEnv = _env.success ? _env.data : ({} as ClientEnv);

src/shared/config/env.ts

@@ -3,6 +3,10 @@ import { z } from 'zod/v4';
 const isServer = typeof window === 'undefined';
 const isBuild = process.env.SKIP_ENV_VALIDATION === 'true';
 
+const metricEnabledSchema = z.enum(['true', 'false'], {
+  error: 'NEXT_PUBLIC_METRICS_ENABLED - обязателен',
+});
+
 const envSchemaServer = z.object({
   NODE_ENV: z
     .enum(['development', 'production', 'test'], {
@@ -35,11 +39,7 @@ const envSchemaServer = z.object({
 });
 
 const envSchemaClient = z.object({
-  NEXT_PUBLIC_API_BASE_URL: z
-    .string({
-      error: 'API Base URL обязателен',
-    })
-    .url('NEXT_PUBLIC_API_BASE_URL должен быть валидным URL'),
+  NEXT_PUBLIC_API_BASE_URL: z.url('NEXT_PUBLIC_API_BASE_URL должен быть валидным URL'),
   NEXT_PUBLIC_FARO_URL: z
     .string({
       error: 'URL для Faro (Alloy) обязателен',
@@ -61,6 +61,10 @@ const envSchemaClient = z.object({
       error: 'Окружение (APP_ENV) обязательно',
     })
     .min(1, 'Окружение не может быть пустым'),
+  NEXT_PUBLIC_METRICS_ENABLED:
+    process.env.NODE_ENV === 'development'
+      ? metricEnabledSchema.default('false').transform((v) => v === 'true')
+      : metricEnabledSchema.transform((v) => v === 'true'),
 });
 
 const envSchema = envSchemaClient.extend(envSchemaServer.shape);

src/shared/config/metrics/FrontendObservability.tsx

@@ -3,11 +3,13 @@
 import { useEffect } from 'react';
 import { faro, getWebInstrumentations, initializeFaro } from '@grafana/faro-web-sdk';
 import { TracingInstrumentation } from '@grafana/faro-web-tracing';
+import { env } from '../env.client';
 
 let isFaroInitialized = false;
 
 export default function FrontendObservability() {
   useEffect(() => {
+    if (!env.NEXT_PUBLIC_METRICS_ENABLED) return;
     const initializeWhenIdle = () => {
       if (isFaroInitialized || faro.api) {
         return;