@equinor/fusion-framework-module-telemetry

Unified telemetry module for the Fusion Framework. Provides a consistent API for tracking events, exceptions, metrics, and custom telemetry data while supporting pluggable adapters for different backends.

Features

For framework, app and widget lifecycle diagnostics, routing guarantees, safe metadata, optional HTTP/query integration, and migration guidance, see Operational telemetry.

Framework modules obtain a connected handle with telemetry.scope('app') and implement the TelemetryConnectable provider contract. The shared handle supports primitive summary properties, bounded measured operations, observable measurement and owned child scopes. Closing a scope cancels its in-flight operations exactly once and prevents late reporting. For custom providers without scope, modules lazily load createOperationalTelemetry from the /utils entry point; no runtime telemetry import is needed for built-in providers.

• Adapter-based architecture — ship with Console and Application Insights adapters, or build your own by extending BaseTelemetryAdapter.
• Hierarchical providers — child providers relay telemetry to a parent, with automatic metadata merging.
• Zod-validated schemas — every telemetry item is parsed and validated at runtime.
• Performance measurements — Measurement utility tracks elapsed time with using / Symbol.dispose support.
• Framework event integration — emits onTelemetry and onTelemetryError events via the Fusion event system.
• Configurable filtering — per-adapter and per-relay filter functions control which items are processed.
• Metadata extractors — attach dynamic metadata (sync, async, or observable) to every telemetry item.

Installation

pnpm add @equinor/fusion-framework-module-telemetry

Usage

Enabling telemetry in a Fusion app

import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';

const configure = (configurator) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true,
    configure: (builder) => {
      builder.setAdapter(ConsoleAdapter.Identifier, new ConsoleAdapter({ title: 'MyApp' }));
      builder.setMetadata(() => ({ appVersion: '2.0.0' }));
      builder.setDefaultScope(['application']);
    },
  });
};

Tracking events, exceptions, and metrics

import { TelemetryType, TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';

const provider = modules.telemetry;

// Track a generic item
provider.track({
  type: TelemetryType.Event,
  name: 'page_view',
  level: TelemetryLevel.Information,
  properties: { page: '/dashboard' },
});

// Shorthand helpers
provider.trackEvent({ name: 'button_click', properties: { id: 'save' } });
provider.trackException({ name: 'api_error', exception: new Error('Not found') });
provider.trackMetric({ name: 'response_time', value: 230 });
provider.trackCustom({ name: 'feature_flag', properties: { flag: 'dark-mode' } });

Measuring performance

// Manual measurement
const measurement = provider.measure({ name: 'data_load' });
await fetchData();
measurement.measure({ properties: { rows: 100 } }, { markAsMeasured: true });

// Automatic measurement with `using` (explicit resource management)
{
  using m = provider.measure({ name: 'render_time' });
  renderComponent();
} // duration tracked automatically on scope exit

// Promise-based measurement
const result = await provider.measure({ name: 'api_call' }).resolve(fetch('/api/data'));

Application Insights adapter

import { ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry/application-insights-adapter';

enableTelemetry(configurator, {
  configure: (builder) => {
    builder.setAdapter(
      ApplicationInsightsAdapter.Identifier,
      new ApplicationInsightsAdapter({
        snippet: { config: { connectionString: '...' } },
        prefix: 'myApp',
      }),
    );
  },
});

API Reference

OTLP/HTTP adapter

OtlpAdapter exports Fusion events, exceptions, metrics (as log records), and custom telemetry using the standard OpenTelemetry HTTP log exporter. It attaches app-key and source attributes and uses the active OpenTelemetry trace context for log correlation. It does not register a global logger or tracer provider.

OpenTelemetry packages are optional peer dependencies: ordinary telemetry and the console or Application Insights adapters do not require them. Install them only when importing @equinor/fusion-framework-module-telemetry/otlp-adapter directly:

pnpm add @opentelemetry/api-logs@^0.222.0 @opentelemetry/exporter-logs-otlp-http@^0.222.0 @opentelemetry/resources@^2.11.0 @opentelemetry/sdk-logs@^0.222.0

The dev-server SPA bundle includes the OTLP implementation, so environment-only dev-server usage does not require adding these peers to app repositories.

import { OtlpAdapter } from '@equinor/fusion-framework-module-telemetry/otlp-adapter';

enableTelemetry(configurator, {
  configure: (builder) => {
    builder.setAdapter('otlp', new OtlpAdapter({
      url: 'http://localhost:4318/v1/logs',
      serviceName: 'my-app',
    }));
  },
});

url is the full logs signal URL. serviceName defaults to fusion.telemetry; fallback defaults to false. Initialization makes no collector request. Export failures are reported once and remain best effort. The telemetry module's disposal hook awaits TelemetryProvider.dispose(), which stops subscriptions and waits for every adapter's shutdown() to flush and release the exporter. Repeated provider disposal joins the same shutdown promise. Failures are reported through the framework's module-disposal error event after all adapters have been attempted. Standalone provider consumers should await provider.dispose(); standalone adapter consumers should await adapter.shutdown().

OtlpAdapter buffers records with BatchLogRecordProcessor: up to 128 records per export, a 2,048-record queue, and a one-second scheduled export delay. Startup bursts share a request instead of exhausting the exporter's concurrency limit. Call await adapter.forceFlush() at explicit lifecycle boundaries or in tests to export pending records immediately. Telemetry is best effort: a full queue or an abrupt browser close can lose records.

For environment-only development configuration, use FUSION_DEV_SERVER_OTLP_ENDPOINT instead of changing app code. The dev server configures this same public adapter as a fallback.

Fallback adapters and app precedence

An ITelemetryAdapter can set readonly fallback = true. A parent provider skips that adapter for records relayed from a child that already has an explicitly configured non-fallback adapter. Other parent adapters, telemetry events, metadata merging, and relay filters continue to work. The decision propagates through nested providers, including asynchronous metadata resolution.

This supports environment-enabled development exporters without configuring an app twice. Apps that only configure metadata, scopes, or filters still use the parent fallback. Adapters without the optional fallback property retain their existing behavior.

Core exports (@equinor/fusion-framework-module-telemetry)

Operational helpers are not re-exported from the root; import them from the /utils, /schemas and /integrations sub-paths below.

Sub-path exports

Testing

Import from @equinor/fusion-framework-module-telemetry/mock to record telemetry in-process while retaining the real telemetry provider, validation, metadata, scopes, filters, and event integration.

Defaults

TelemetryMockConfigurator registers one fresh, empty MockTelemetryAdapter under the mock adapter id. Nothing is exported to a backend unless the test registers another adapter. Each configurator owns its recorder, so recorded items are not shared across test instances.

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

let recorder;
enableTelemetryMock(configurator, (builder) => {
  recorder = builder.adapter;
});

const item = await recorder.waitForItem('button-click');
expect(item.properties?.section).toBe('header');

MockTelemetryAdapter.getItems(matcher?) returns recorded items synchronously. waitForItem(matcher, options?) waits for an existing or future match and accepts a timeout or AbortSignal. TelemetryMockConfigurator and telemetryMockModule are also exported for manual composition.

Configuration

The telemetry module is configured through ITelemetryConfigurator, which provides a fluent builder API:

Telemetry Levels

Telemetry items can have different severity levels:

• Verbose (0): Detailed information, typically for debugging
• Debug (1): Debugging information
• Information (2): General information about the system's operation
• Warning (3): Indicates a potential issue that is not critical
• Error (4): Represents an error that has occurred, but the system can continue running
• Critical (5): A severe error that may cause the system to stop functioning

By default, if no level is specified, the Information level is used.

Measurements

The telemetry module provides a Measurement class that helps you track the duration of operations in your code.

Basic Measurement

// Create a measurement
const measurement = modules.telemetry.measure({ name: 'MyMeasurement' });

// Perform some operation
// ...

// Record the measurement
measurement.measure(); // Tracks the time since the measurement was created

Resolving Measurements

You can resolve measurements with promises to track asynchronous operations:

const measurement = modules.telemetry.measure({ name: 'AsyncOperation' });

// Track the time it takes to resolve the promise
const result = await measurement.resolve(
  new Promise<string>((resolve) => {
    setTimeout(() => resolve('result'), 1000);
  }),
  {
    // Additional data to include in the measurement
    data: (result) => ({ properties: { result } })
  }
);

Executing Measurements

You can execute a function and measure its execution time:

const measurement = modules.telemetry.measure({ name: 'FunctionExecution' });

// Execute and measure the function
const result = await measurement.exec(() => {
  // Simulate some work
  return new Promise<string>((resolve) => setTimeout(() => resolve('result'), 1000));
});

Cloning Measurements

You can clone measurements to create new instances with the same initial state:

const measurement = modules.telemetry.measure({ name: 'CloneExample' });

for (let i = 0; i < 5; i++) {
  const clonedMeasurement = measurement.clone({ preserveStartTime: true });
  await clonedMeasurement.resolve(
    new Promise((resolve) => setTimeout(() => resolve('result'), 1000))
  );
}

// Measure the total time taken by all cloned measurements
measurement.measure(); 

Using Statement

You can use the using statement to automatically dispose of measurements when they go out of scope:

const job = async() => {
  using measurement = modules.telemetry.measure({ name: 'UsingExample' });
  // Perform some operation
  // The measurement will be automatically tracked when the function completes
}

[!CAUTION] The using statement is a TypeScript feature that is still in proposal stage and may not be available in all environments. To use this feature, you need to enable it in your TypeScript configuration:

{
  "compilerOptions": {
    "target": "es2022",
    "module": "NodeNext",
    "useDefineForClassFields": true
  }
}

Adapters

Adapters are responsible for processing and sending telemetry data to their respective destinations. All adapters support asynchronous initialization and will be automatically initialized when the telemetry provider initializes.

Using setAdapter and configureAdapter

The TelemetryConfigurator provides two methods for adding adapters: setAdapter for pre-instantiated adapters and configureAdapter for dynamic creation using initialization arguments.

Simple setAdapter Example

import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    configure: (builder) => {
      const consoleAdapter = new ConsoleAdapter({ title: 'MyApp' });
      builder.setAdapter('console', consoleAdapter);
    }
  });
};

Multiple Adapters with Different Identifiers

You can configure multiple adapters with different identifiers to handle different types of telemetry data. This allows for flexible routing and filtering of telemetry items.

import { enableTelemetry, TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';
import { ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry/application-insights-adapter';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    configure: (builder) => {
      // Standard console logger for general information
      const standardConsole = new ConsoleAdapter({
        title: 'Standard',
        filter: (item) =>
          item.level >= TelemetryLevel.Information && item.level < TelemetryLevel.Error
      });
      builder.setAdapter('console-standard', standardConsole);

      // Error console logger for errors and critical issues
      const errorConsole = new ConsoleAdapter({
        title: 'Errors',
        filter: (item) => item.level >= TelemetryLevel.Error
      });
      builder.setAdapter('console-error', errorConsole);

      // Application Insights for production telemetry
      const appInsights = new ApplicationInsightsAdapter({
        snippet: {
          config: {
            instrumentationKey: 'production-instrumentation-key'
          }
        },
        filter: (item) => item.level >= TelemetryLevel.Warning
      });
      builder.setAdapter('app-insights-prod', appInsights);
    }
  });
};

This setup allows you to:

• Route general information to the standard console logger
• Send errors to a dedicated error console logger
• Forward warnings and above to Application Insights for production monitoring

configureAdapter with requireInstance Example

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

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    configure: async (builder, ref) => {
      builder.configureAdapter('application-insights', async ({ requireInstance }) => {
        const auth = await requireInstance('auth');
        const adapter = new ApplicationInsightsAdapter({
          snippet: {
            config: {
              instrumentationKey: 'app-instrumentation-key'
            }
          },
          filter: (item) => item.level >= TelemetryLevel.Information,
        });
        if (auth.account?.localAccountId) {
          adapter.setAuthenticatedUserContext(auth.account.localAccountId);
        }
        return adapter;
      });
    }
  });
};

Application Insights Adapter

The Application Insights adapter allows you to send telemetry data to Microsoft Application Insights. It supports asynchronous initialization for setting up the Application Insights client and plugins.

Installation

To use the Application Insights adapter, you need to install the @microsoft/applicationinsights-web package:

pnpm add @microsoft/applicationinsights-web

Configuration

The Application Insights adapter supports the following configuration options:

• snippet: The Application Insights configuration object (required)
• plugins: Optional array of plugins to extend Application Insights functionality
• identifier: Optional unique identifier for the client instance (defaults to 'application-insights')
• filter: Optional filter function to determine if a telemetry item should be processed
• prefix: Optional prefix to prepend to telemetry item names

Example

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

// bootstrap - initialization on server which loads the portal
const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true, // Track module configurator events
    configure: async (builder, ref) => {
      const adapter = new ApplicationInsightsAdapter({
        snippet: {
          config: {
            instrumentationKey: 'portal-instrumentation-key'
          }
        },
        // filter log level by FUSION_TELEMETRY_LEVEL environment variable
        filter: (item) =>
          item.level >= (process.env.FUSION_TELEMETRY_LEVEL
            ? parseInt(process.env.FUSION_TELEMETRY_LEVEL)
            : TelemetryLevel.Information),
      });

      builder.setAdapter('application-insights', adapter);
      ref.requireInstance('auth').then((auth) => {
        if (auth.account?.localAccountId) {
          adapter.setAuthenticatedUserContext(auth.account.localAccountId);
        }
      });
    }
  });
};

// portal - framework
const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true,
    configure: async (args) => {
    // reuse the Application Insights adapter from bootstrap
    const aiAdapter = args.ref.modules.telemetry.getAdapter(ApplicationInsightsAdapter.Identifier);
    if (aiAdapter) {
      args.config.setAdapter('application-insights', aiAdapter);
    }
    args.config.setMetadata({
      portal: {
        name: 'Fusion Portal',
        version: '1.0.0',
      }
    });
    args.config.setDefaultScope(['portal']);
    }
  });
};

// app - application
const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true,
    configure: async (args) => {
    args.config.setMetadata({
      app: {
        name: 'My App',
        version: '1.0.0',
      }
    });
    args.config.setDefaultScope(['app']);
    args.config.setParent(args.ref.modules.telemetry);
    const appAppInsightsAdapter = new ApplicationInsightsAdapter({
      snippet: {
        config: {
          instrumentationKey: 'app-instrumentation-key'
        }
      },
      // only log events with a specific scope
      filter: (item) => item.scope.includes('custom-event'),
    });
    args.config.setAdapter('application-insights-app', appAppInsightsAdapter);
    }
  });
};

// app - custom event
modules.telemetry.trackEvent({
  name: 'CustomEvent',
  type: TelemetryType.Event,
  level: TelemetryLevel.Information,
  properties: {
    customProperty: 'value'
  },
  scope: ['custom-event', 'ag-grid']
});

Console Adapter

The Console adapter provides a simple way to log telemetry data to the console, useful for development and debugging.

Installation

The Console adapter is included with the telemetry module and doesn't require additional installation.

Configuration

The Console adapter supports the following configuration options:

• identifier: Optional unique identifier for the adapter (defaults to 'console-adapter')
• filter: Optional filter function to determine if a telemetry item should be processed
• title: Optional title to display in the console output (defaults to 'Fusion')

Example

import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';
import { TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    // Create a console adapter for development
    const consoleAdapter = new ConsoleAdapter({
      title: 'MyApp',
      // Only log information and above
      filter: (item) => item.level >= TelemetryLevel.Information
    });
    
    builder.setAdapter('console', consoleAdapter);
  });
};

Creating Custom Adapters

You can create custom telemetry adapters by extending the BaseTelemetryAdapter class. Adapters can optionally implement asynchronous initialization:

import type { TelemetryItem } from '@equinor/fusion-framework-module-telemetry';
import { BaseTelemetryAdapter } from '@equinor/fusion-framework-module-telemetry/adapter';

class CustomAdapter extends BaseTelemetryAdapter {
  constructor() {
    super('custom-adapter');
  }

  protected async _initialize(): Promise<void> {
    // Perform async setup here (e.g., establish connections, load configurations)
    await this.setupConnection();
  }

  protected _processItem(item: TelemetryItem): void {
    // Process and send telemetry items
    this.sendToCustomBackend(item);
  }

  private async setupConnection(): Promise<void> {
    // Implementation for setting up the connection
  }

  private sendToCustomBackend(item: TelemetryItem): void {
    // Implementation for sending data to your backend
  }
}

To use your custom adapter:

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

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    const customAdapter = new CustomAdapter();
    builder.setAdapter('custom', customAdapter);
  });
};

Advanced Features

Metadata Extractors

Metadata extractors allow you to dynamically add metadata to telemetry items before they are processed. This can be useful for adding context information to all telemetry items.

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

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    // Add metadata to all telemetry items
    builder.setMetadata(({ modules, item }) => {
      return {
        ...item,
        properties: {
          ...item.properties,
          // Add user information if available
          user: modules?.auth?.account?.username,
          // Add application version
          version: '1.0.0',
        }
      };
    });
  });
};

Filter Functions

Filter functions allow you to control which telemetry items are processed by an adapter. This can be useful for filtering out unwanted telemetry or directing different types of telemetry to different adapters.

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

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    // Only process errors and critical events in production
    const isProd = process.env.NODE_ENV === 'production';
    
    const appInsightsAdapter = new ApplicationInsightsAdapter({
      snippet: { /* ... */ },
      // In production, only send errors and critical events
      // In development, send all events
      filter: (item) => isProd 
        ? item.level >= TelemetryLevel.Error 
        : true
    });
    
    builder.setAdapter('application-insights', appInsightsAdapter);
  });
};

Architecture

The telemetry module follows a hierarchical architecture that allows for flexible configuration and data flow. The diagram below shows how different components interact:

classDiagram
  class Bootstrap {
      Application Insight Adapter
      filter(item)
  }
  class Portal {
      Dev Tool Adapter
      Application Insight Adapter
      IndexDB Adapter
      filter(item)
  }
  class App {
      Application Insight Adapter
      App Telemetry Events
      filter(item)
  }

  Bootstrap --> Portal
  Portal --> App
  App ..> Portal : App Telemetry Events

Performance Considerations

When implementing telemetry, consider the following performance best practices:

1. Filter Early: Apply filters as early as possible to avoid processing unnecessary telemetry data.
2. Batch Operations: Use measurements to track operations in batches rather than tracking individual events.
3. Sampling: In high-volume scenarios, consider implementing sampling to reduce the amount of telemetry data.
4. Async Processing: Use the telemetry module's asynchronous methods to avoid blocking the main thread.
5. Selective Telemetry: Be selective about what you track in production to avoid overwhelming your telemetry backend.

Troubleshooting

Common issues and their solutions:

1. No Telemetry Data:

   • Check that adapters are properly configured and added to the telemetry configurator
   • Verify that filter functions aren't excluding all telemetry items
   • Ensure network connectivity to the telemetry backend

2. Missing Context Information:

   • Check that metadata extractors are configured correctly
   • Verify that required modules are available when extracting metadata

3. Performance Issues:

   • Check for excessive telemetry events being generated
   • Consider implementing sampling or more selective filtering
   • Review adapter processing times