Fusion Framework #3496

[odinr]

After months of meticulous development, we are delighted to deliver the comprehensive telemetry functionality that fulfills our primary objective in issue #3482. Fusion Framework applications can now seamlessly transmit telemetry data to Application Insights with minimal configuration overhead.

The Big Picture

Portal teams now gain comprehensive observability without the console log inundation. We've engineered a complete telemetry system that automatically monitors query operations, cache performance, module lifecycle, and key performance metrics—while preserving zero breaking changes.

For local development, structured console logging with configurable verbosity replaces traditional debugging uncertainty.

Quick Start for Portal Teams

Deploy this release and telemetry activates immediately. For production monitoring, configure your Application Insights instrumentation key. Your portal will instantly begin transmitting structured telemetry data.

Quick Start for Application Developers

Create a dev-server.config.ts file in your project root with this configuration:

import { defineDevServerConfig } from '@equinor/fusion-framework-cli';

export default defineDevServerConfig(() => ({
  spa: {
    templateEnv: {
      telemetry: {
        consoleLevel: 1 // 0=Debug, 1=Info (recommended), 2=Warning, 3=Error, 4=Critical
      }
    }
  }
}));

When you run your development server, you'll observe clean, structured telemetry logs instead of typical console disorder.

---

Technical Implementation

After months of systematic development, we constructed this comprehensive solution from the foundation up:

Telemetry Engine
A new @equinor/fusion-framework-module-telemetry package that orchestrates all telemetry operations, featuring intelligent adapters for Application Insights or console logging.

Framework Integration
Enhanced the core framework and query system to automatically emit telemetry signals, eliminating the need for application code modifications.

Ecosystem Adoption
From the development portal to the CLI and SPA bootstrapping, the entire platform now supports telemetry seamlessly.

Quality Enhancements
Strengthened code quality through stricter linting rules, enhanced TypeScript safety, and accessibility improvements.

Portal Configuration

For portal environments, the system operates automatically with zero configuration required. The framework intelligently detects portal contexts and commences telemetry collection immediately.

For specialized requirements, manual configuration remains available:

import { enableTelemetry, ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry';

const configure = (configurator) => {
  enableTelemetry(configurator, (builder) => {
    builder.setAdapter(new ApplicationInsightsAdapter({
      instrumentationKey: 'your-instrumentation-key'
    }));
  });
};

The system captures all critical elements: user interactions, navigation patterns, performance metrics, and error conditions. Portal metadata encompassing name, version, and environment is incorporated automatically.

For Application Developers

During local development, telemetry manifests as clean, structured console logs rather than typical disorganized output. Control verbosity with a simple dev-server.config.ts:

import { defineDevServerConfig } from '@equinor/fusion-framework-cli';

export default defineDevServerConfig(() => ({
  spa: {
    templateEnv: {
      telemetry: {
        consoleLevel: 1 // Try 0 for everything, 1 for normal dev work, 2+ for quieter logs
      }
    }
  }
}));

This replaces console.log disorder with organized telemetry that delivers genuine insight into application behavior.

---

Telemetry Coverage

The telemetry system automatically monitors your application comprehensively:

• Data Operations - Every API call is tracked from initiation through completion or failure
• Cache Performance - Monitors cache additions, removals, and operational efficiency
• Module Lifecycle - Tracks component loading, initialization, and error conditions
• Performance Metrics - Bootstrap times, service worker activity, network requests, and user interactions
• Error Handling - Exceptions are captured with complete context for effective debugging

You can also add custom telemetry events if you need to track something specific:

import { useTelemetry } from '@equinor/fusion-framework-module-telemetry';

const MyComponent = () => {
  const telemetry = useTelemetry();

  const handleClick = () => {
    telemetry.measure('user_action', {
      action: 'button_click',
      component: 'MyComponent'
    });
  };

  return <button onClick={handleClick}>Click</button>;
};

Configuration Levels

🔵 0 (Debug): Comprehensive logging including internal framework details

🟢 1 (Info): Standard operational messages—optimal for development workflows

🟡 2 (Warning): Warnings and above only

🔴 3 (Error): Errors and critical issues exclusively

💀 4 (Critical): Critical failures only

Production environments leverage Application Insights; development environments utilize console logging.

Zero Breaking Changes

The most compelling aspect of this release is the complete absence of breaking changes. Portal teams can deploy immediately—telemetry activates seamlessly.

For production monitoring, simply configure your Application Insights instrumentation key. Development environments receive console logging automatically.

Application Monitoring

Once Application Insights is configured, you will observe comprehensive telemetry data including:

📊 Requests - Page loads, API calls, and user navigation patterns

🔗 Dependencies - External services, module loading, and asset requests

🚨 Exceptions - Structured errors with complete context and stack traces

🔍 Traces - Detailed execution flows and performance bottlenecks

🎯 Custom Events - Application-specific interactions and features

In development environments, structured console logging with timestamps dramatically improves debugging clarity.

Additional Enhancements

While prioritizing telemetry implementation, we addressed several complementary improvements that benefit the entire ecosystem:

✅ Enhanced Code Quality
Stricter linting rules, accessibility improvements, refined TypeScript types, and 30+ unit tests specifically for telemetry functionality.

💻 Improved CLI Experience
Enhanced validation before application publishing, clearer error messaging, and proper handling of deleted applications.

🛡️ Strengthened Framework Reliability
Resolved HTTP method crashes and enhanced schema validation robustness.

Documentation and Support

We remain committed to your success with comprehensive documentation featuring detailed guides, practical examples, and complete setup instructions.

Visit the telemetry documentation for in-depth guidance, or submit an issue if you encounter any challenges.

Dependency Updates

We also ensured system stability by updating critical dependencies:

• zod received a major upgrade to v4.1.11 with significantly enhanced validation capabilities
• vite v7.1.9 provides important stability improvements for smoother development workflows
• dotenv v17.2.3 offers enhanced TypeScript support for better development experience

Complete Issue Resolution

We addressed 24 issues across the entire framework to ensure comprehensive functionality. Here's what was accomplished:

🎯 Core Telemetry Features

• #3482 - Front-End Telemetry for Fusion Framework (EPIC)
• #3483 - Core Telemetry Module Implementation
• #3488 - Add new telemetry module
• #3491 - Framework Configurator Telemetry

🏗️ Framework Integration

• #3490 - Remove explicit logger initialization
• #3492 - Integrate telemetry module into framework core
• #3493 - Add telemetry integration to app configurator

🖥️ Portal & Platform

• #3485 - Add Telemetry to Development Portal
• #3486 - Add Telemetry to Service Discovery
• #3487 - Telemetry Integration in SPA Bootstrap
• #3521 - Add comprehensive telemetry integration to SPA bootstrap and service worker

🛠️ Developer Tools

• #3512 - Enhanced app management commands
• #3397 - App existence validation before publishing/uploading
• #3534 - Enhanced dev-server documentation
• #3523 - Documentation updates needed

🧹 Code Quality

• #3515 - Global Biome Configuration Modernization
• #3494 - Remove Biome rule overrides to use default best practices
• #3495 - Enable strict error rules

🔧 System Enhancements

• #3537 - Added comprehensive event system for enhanced observability
• #3489 - Module event system
• #3541 - Fixed capitalizeRequestMethodOperator

📦 Dependencies

• #3500 - Update zod dependency
• #3479 - Bump dotenv from 17.2.2 to 17.2.3
• #3532 - Bump vite from 7.1.8 to 7.1.9

Acknowledgments

This release represents the culmination of dedicated effort from our exceptional team:

• @odinr - Telemetry architect who designed the comprehensive system and portal integration
• @eikeland - CLI specialist who enhanced deployment and management workflows
• Framework Team - Quality assurance experts who ensured robust functionality

Future Roadmap

We are eager to incorporate your feedback from this initial portal implementation. Future releases may include:

• Extended telemetry capabilities for Fusion applications beyond portals
• Advanced analytics dashboards with comprehensive visualization
• Additional monitoring and observability features

We Value Your Feedback

This represents our inaugural telemetry implementation—we would greatly appreciate your experience report. Is the logging verbosity appropriate? Are there missing details? Any performance considerations? Please share your insights in the comments below.

---

This release was generated from PR #3496 - 🤖 Bip Bop - Fusion Framework Release