Add Grafana Cloud Frontend functionality to the Frontend app.

This will allow the use of a Frontend endpoint to be used,
to use Grafana Frontend functionality in Cloud.

The `mythical-server` service has been updated to provide configuration
for the Faro Web SDK to ensure that either a local instance of
Alloy is used for data collection, or Grafana Cloud Frontend.

Signed-off-by: Heds Simons <hedley.simons@grafana.com>

Author: hedss

README.md

@@ -211,6 +211,14 @@ Note that this service is optional, and is only currently available in the local
 
 Faro is designed to continue to propagate data across frontend sessions to backend server infrastructure, and as such includes the ability to send relevant state information in headers. For traces, this is based open the OpenTelemetry Tracing Specification, and utilises the `tracestate` and `traceparent` headers to propagate data. In the case of this example, this will show traces starting in the `mythical-frontend` service.
 
+The default setup is to send Faro data to the local Alloy instance, which will count it as a propagated trace that will include the `mythical-server` service as part of the trace.
+
+For Grafana Cloud, using the [`docker-compose-cloud.yml`](docker-compose-cloud.yml) manifest, you can instead use Grafana Frontend to show session data, as well as statistics on user browser data such as time to first byte, etc. To do so, change the following environment variables in  the `mythical-server` configuration:
+* `FARO_ENDPOINT` to the URL specified in an initialised Grafana Frontend application project, notably the `url` field in the `Settings -> Web SDK Config` section.
+* `USE_GRAFANA_CLOUD` to `true`.
+This will allow you to send Faro data to Grafana Cloud, and see linked traces and logs as part of Grafana Frontend.
+
+
 ### Beyla
 
 Beyla is an eBPF-based tool for generating metrics and trace data without the need for application instrumentation. For more details about Beyla, read the [documentation](https://grafana.com/docs/grafana-cloud/monitor-applications/beyla/).
@@ -333,6 +341,8 @@ This demo can be run against Grafana Cloud by configuring the `alloy/endpoints-c
 
 The Grafana Alloy will send all the signals to the Grafana Cloud stack specified in the `alloy/endpoints-cloud.json` file.
 
+*Note:* See the [`Faro Web SDK`](#faro-web-sdk) for instructions on how to configure the right URL endpoint to send Faro data to Grafana Frontend. It is *vital* to note that you must configure your browser to disable the same-origin policies to allow the local running of a web-server that will send to Grafana Frontend (and to include `localhost` in your allowed domains). For example, in Chrome you can achieve this with the `--disable-web-security` flag.
+
 ## Using the OpenTelemetry Collector
 
 You can also use an alternative environment that uses the OpenTelemetry Collector in place of Grafana Alloy.

docker-compose-cloud.yml

@@ -11,6 +11,7 @@ services:
     ports:
       - "12347:12345"
       - "12348:12348"
+      - "12350:12350"
       - "6832:6832"
       - "55679:55679"
       - "4317:4317"
@@ -75,6 +76,25 @@ services:
       - OTEL_EXPORTER_OTLP_TRACES_INSECURE=true
       - OTEL_RESOURCE_ATTRIBUTES=ip=1.2.3.4
 
+  # React frontend for the mythical beasts management system
+  mythical-frontend:
+    #build:
+    #  context: ./source/mythical-beasts-frontend
+    #  dockerfile: Dockerfile
+    #  args:
+    #    - REACT_APP_API_URL=/api
+    # By default, this will try and send to Alloy instead of Grafana Cloud Frontend.
+    image: grafana/intro-to-mltp:mythical-beasts-frontend-latest
+    restart: always
+    depends_on:
+      mythical-server:
+        condition: service_started
+      alloy:
+        condition: service_started
+    ports:
+      - "3001:80"
+
+
   # The API server microservice.
   # It writes logs directly to the Loki service, exposes metrics for the Prometheus
   # service and sends traces to the Grafana Alloy instance.
@@ -100,6 +120,11 @@ services:
       - PROFILE_COLLECTOR_PORT=4040
       - OTEL_EXPORTER_OTLP_TRACES_INSECURE=true
       - OTEL_RESOURCE_ATTRIBUTES=ip=1.2.3.5
+      # By default, this will try and send Faro data to the local Alloy instance.
+      # For Grafana Cloud, set FARO_ENDPOINT to your Grafana Cloud Frontend endpoint, and set
+      # USE_GRAFANA_CLOUD to true.
+      - FARO_ENDPOINT=http://localhost:12350/collect
+      - USE_GRAFANA_CLOUD=false
 
   # A microservice that consumes requests from the mythical-queue
   mythical-recorder:

docker-compose.yml

@@ -119,6 +119,11 @@ services:
       - PROFILE_COLLECTOR_PORT=4040
       - OTEL_EXPORTER_OTLP_TRACES_INSECURE=true
       - OTEL_RESOURCE_ATTRIBUTES=ip=1.2.3.5
+      # Faro configuration for the frontend, sends to the local Alloy instance.
+      # You can change this to send to Grafana Cloud, but see the `docker-compose-cloud.yml` compose file instead
+      # to send all data to Grafana Cloud.
+      - FARO_ENDPOINT=http://localhost:12350/collect
+      - USE_GRAFANA_CLOUD=false
 
   # A microservice that consumes requests from the mythical-queue
   mythical-recorder:
@@ -151,7 +156,6 @@ services:
     #  dockerfile: Dockerfile
     #  args:
     #    - REACT_APP_API_URL=/api
-    #    - REACT_APP_ALLOY_ENDPOINT=http://localhost:12350/collect
     image: grafana/intro-to-mltp:mythical-beasts-frontend-latest
     restart: always
     depends_on:

grafana/definitions/traces-in-dashboards.json

@@ -108,7 +108,7 @@
             "uid": "mimir"
           },
           "editorMode": "code",
-          "expr": "sum by (http_method)(rate(traces_spanmetrics_calls_total{service_name=\"mythical-server\",http_method=~\"${httpMethod}\"}[1m]))",
+          "expr": "sum by (http_method)(rate(traces_spanmetrics_calls_total{service=\"mythical-server\",http_method=~\"${httpMethod}\"}[1m]))",
           "legendFormat": "",
           "range": true,
           "refId": "A"

images/Introduction to MLTP Arch Diagram.png

@@ -1,13 +1,11 @@
 # Build stage
 FROM node:18-alpine AS build
 
-# Accept build arguments
+# Accept build arguments (only keep API URL for build-time configuration)
 ARG REACT_APP_API_URL
-ARG REACT_APP_ALLOY_ENDPOINT
 
 # Set as environment variables for the build process
 ENV REACT_APP_API_URL=$REACT_APP_API_URL
-ENV REACT_APP_ALLOY_ENDPOINT=$REACT_APP_ALLOY_ENDPOINT
 
 WORKDIR /app
 

source/mythical-beasts-frontend/Dockerfile

@@ -34,7 +34,6 @@ export default defineConfig({
       source: {
         define: {
           'process.env.REACT_APP_API_URL': JSON.stringify(process.env.REACT_APP_API_URL || '/api'),
-          'process.env.REACT_APP_ALLOY_ENDPOINT': JSON.stringify(process.env.REACT_APP_ALLOY_ENDPOINT || 'http://localhost:12350/collect'),
           'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),
         },
       },

source/mythical-beasts-frontend/rsbuild.config.js

@@ -2,50 +2,94 @@ import { getWebInstrumentations, initializeFaro } from '@grafana/faro-web-sdk';
 import { TracingInstrumentation } from '@grafana/faro-web-tracing';
 
 let faro = null;
+let configPromise = null;
 
-export const initFaro = () => {
+// Fetch configuration from backend API
+const fetchFaroConfig = async () => {
+  try {
+    // Use the same API base URL logic as the rest of the app
+    const isProduction = process.env.NODE_ENV === 'production';
+    const isDockerizedFrontend = window.location.hostname === 'localhost' && window.location.port === '3001';
+
+    let baseUrl;
+    if (isProduction && isDockerizedFrontend) {
+      baseUrl = '/api'; // Use nginx proxy
+    } else {
+      baseUrl = 'http://localhost:4000'; // Direct API access
+    }
+
+    const response = await fetch(`${baseUrl}/config`);
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const config = await response.json();
+    console.log('🔧 Fetched Faro config from backend:', config);
+    return config;
+  } catch (error) {
+    console.warn('⚠️ Failed to fetch Faro config from backend, using defaults:', error);
+    // Return default configuration if API call fails
+    return {
+      faroUrl: 'http://localhost:12350/collect',
+      useGrafanaCloud: false,
+      environment: 'development',
+      version: '1.0.0',
+      appName: 'mythical-frontend'
+    };
+  }
+};
+
+export const initFaro = async () => {
   // Return early if already initialized
   if (faro) {
     return faro;
   }
 
+  // Use cached config promise if available
+  if (!configPromise) {
+    configPromise = fetchFaroConfig();
+  }
+
   try {
-    // Get the Alloy endpoint from environment
-    const alloyEndpoint = process.env.REACT_APP_ALLOY_ENDPOINT || 'http://localhost:12350/collect';
+    // Wait for configuration from backend
+    const config = await configPromise;
 
-    console.log('🔍 Initializing Faro with endpoint:', alloyEndpoint);
+    console.log('🔍 Faro URL:', config.faroUrl);
+    console.log('🔍 Using Grafana Cloud:', config.useGrafanaCloud);
+    console.log('🔍 CORS Proxy:', config.useGrafanaCloud ? 'Enabled (via localhost:8080)' : 'Not needed');
 
-    // Initialisation with a average configuration.
+    // Standard Faro initialization
     faro = initializeFaro({
-      // This is the endpoint to send telemetry to. In this case, we're sending to Alloy.
-      url: alloyEndpoint,
+      url: config.faroUrl,
+
       // The application details will set relevant resources attributes.
       app: {
-        name: 'mythical-frontend',
-        version: '1.0.0',
-        environment: 'development',
+        name: config.appName,
+        version: config.version,
+        environment: config.environment,
       },
 
-      // Basic session tracking
+      // Enhanced session tracking for Grafana Cloud
       sessionTracking: {
         enabled: true,
-        persistent: false, // Simplified to avoid storage issues
+        persistent: config.useGrafanaCloud, // Use persistent sessions for cloud
       },
 
-      // Configure batching with longer timeouts to be a bit more forgiving on slower machines.
+      // Configure batching with appropriate timeouts
       batching: {
         enabled: true,
-        sendTimeout: 5000, // Longer timeout to prevent connection issues
+        sendTimeout: config.useGrafanaCloud ? 10000 : 5000, // Longer timeout for cloud
+        itemLimit: config.useGrafanaCloud ? 50 : 25, // More items per batch for cloud
       },
 
-      // Basic instrumentation.
+      // Enhanced instrumentation for better observability
       instrumentations: [
         ...getWebInstrumentations({
-          captureConsole: false, // Disable console capture to reduce noisey output. Set to true to capture:
-          captureConsoleDisabledLevels: ['debug', 'log'],
+          captureConsole: true,
+          captureConsoleDisabledLevels: ['debug'], // Capture more for cloud
         }),
 
-        // Add tracing instrumentation with simple configuration.
+        // Add tracing instrumentation
         new TracingInstrumentation({
           instrumentationOptions: {
             // Only trace API calls to our backend
@@ -59,7 +103,6 @@ export const initFaro = () => {
 
       // Some basic error handling.
       beforeSend: (event) => {
-        // Simple pass-through with error handling
         try {
           return event;
         } catch (error) {
@@ -74,9 +117,14 @@ export const initFaro = () => {
     // Send a simple test event
     setTimeout(() => {
       try {
-        faro.api.pushLog(['Faro SDK test log'], {
+        faro.api.pushLog(['Faro SDK initialized successfully'], {
           level: 'info',
-          context: { source: 'faro-init' }
+          context: {
+            source: 'faro-init',
+            endpoint: config.faroUrl,
+            useGrafanaCloud: config.useGrafanaCloud,
+            corsProxy: config.useGrafanaCloud ? 'localhost:8080' : 'none'
+          }
         });
       } catch (error) {
         console.warn('Failed to send test log:', error);
@@ -94,13 +142,13 @@ export const initFaro = () => {
         pushLog: () => {},
         pushError: () => {},
         pushMeasurement: (measurement, operation) => {
-          // If there's an operation function, just call it directly
           if (typeof operation === 'function') {
             return operation();
           }
           return Promise.resolve();
         },
         getTraceContext: () => null,
+        getOTEL: () => null,
       }
     };
 

source/mythical-beasts-frontend/src/faro.js

@@ -4,19 +4,23 @@ import './index.css';
 import App from './App';
 import { initFaro } from './faro';
 
-// Always initialise Faro first, to ensure that it is available for the React app.
-console.log('🔍 Initializing Faro SDK before React app...');
-try {
-  initFaro();
-  console.log('✅ Faro SDK initialized successfully');
-} catch (error) {
-  console.warn('⚠️ Faro SDK failed to initialize, continuing without observability:', error);
-}
+// Initialize Faro SDK asynchronously
+const initializeApp = async () => {
+  try {
+    await initFaro();
+    console.log('✅ Faro SDK initialized successfully');
+  } catch (error) {
+    console.warn('⚠️ Faro SDK failed to initialize, continuing without observability:', error);
+  }
 
-// Render the app!
-const root = ReactDOM.createRoot(document.getElementById('root'));
-root.render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
+  // Render the app regardless of Faro initialization status
+  const root = ReactDOM.createRoot(document.getElementById('root'));
+  root.render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+  );
+};
+
+// Start the app
+initializeApp();

source/mythical-beasts-frontend/src/index.js

@@ -126,6 +126,24 @@ const logUtils = require('./logging')('mythical-server', 'server');
         });
     };
 
+    // Configuration endpoint for frontend settings.
+    // This retrieves the correct endpoint to use for Faro data.
+    app.get('/config', async (req, res) => {
+        try {
+            const config = {
+                faroUrl: process.env.FARO_ENDPOINT || 'http://localhost:12350/collect',
+                useGrafanaCloud: process.env.USE_GRAFANA_CLOUD === 'true',
+                environment: process.env.NODE_ENV || 'development',
+                version: '1.0.0',
+                appName: 'mythical-frontend'
+            };
+
+            res.json(config);
+        } catch (error) {
+            res.status(500).json({ error: 'Failed to get configuration' });
+        }
+    });
+
     // Metrics endpoint handler (for Prometheus scraping)
     app.get('/metrics', async (req, res) => {
         res.set('Content-Type', register.contentType);