@tramvai/module-application-monitoring

Tramvai module for collecting and sending application health monitoring events throughout the application lifecycle.

Overview

Tramvai application's health and performance monitoring. It monitors critical lifecycle events from HTML parsing through app initialization and rendering, capturing errors and performance metrics along the way.

Monitored Events

| Event | Description | Trigger Point | | --- | --- | --- | | html-opened | HTML document parsed and ready | Document parse complete | | assets-loaded | All critical assets loaded successfully | Window load event | | assets-load-failed | One or more critical assets failed to load | Window load event (with errors) | | app:initialized | Application initialization complete | After 'init' command line | | app:initialize-failed | Application failed to initialize | App init error | | app:rendered | Application rendered successfully | After successful app render | | app:render-failed | Application rendering failed | Error boundary or renderer callback | | react:render | React rendered successfully | After successful react render | | react:error | React rendered with error | The error occure while react hydration, it can be uncaughtError,caughtError or recoverableError | | app:render-failed | Application rendering failed | Error boundary or renderer callback |

| unhandled-error | Unhandled promise rejection | Global unhandledrejection event |

Installation

npm install @tramvai/module-application-monitoring

Or with yarn:

yarn add @tramvai/module-application-monitoring

Basic Usage

1. Register the Module

Add the module to your Tramvai application:

import { createApp } from '@tramvai/core';
import { ApplicationMonitoringModule } from '@tramvai/module-application-monitoring';

createApp({
  name: 'my-app',
  modules: [ApplicationMonitoringModule],
});

2. Provide an Inline Reporter Factory

Inline reporter are used to capture lifecycle events and send them to a monitoring service (like an analytics tool or error logger). Inline reporters are injected into the HTML during server-side rendering. This allows to detect errors and performance issues early, even before the app is fully up and running.

Key Events Sent Through Inline Reporters:

• HTML Opened (html-opened): Tracks when the HTML is parsed and ready.
• Assets Loaded (assets-loaded) / Assets Load Failed (**assets-load-failed**): Tracks the success/failure of loading assets (JS, CSS, etc.).
• App Start Failed (app-start-failed): Tracks initialization errors.
• Unhandled Errors (unhandled-error): Tracks unhandled errors or promise rejections.

The module requires an inline reporter factory to send events to your monitoring service. To do this provide INLINE_REPORTER_FACTORY_SCRIPT_TOKEN using inline script or object

import { provide } from '@tramvai/core';
import { INLINE_REPORTER_FACTORY_SCRIPT_TOKEN } from '@tramvai/module-application-monitoring';

const providers = [
  provide({
    provide: INLINE_REPORTER_FACTORY_SCRIPT_TOKEN,
    useValue: (parameters) => {
      return {
        send(eventName, payload) {
          fetch('/api/monitoring', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              event: eventName,
              ...parameters,
              ...payload,
              timestamp: Date.now(),
            }),
          });
        },
      };
    },
  }),
];

import { provide } from '@tramvai/core';
import { INLINE_REPORTER_FACTORY_SCRIPT_TOKEN } from '@tramvai/module-application-monitoring';
import { inlineReporterFactoryScript } from './inlineReporter.inline';

const providers = [
  provide({
    provide: INLINE_REPORTER_FACTORY_SCRIPT_TOKEN,
    useFactory: () => {
      return inlineReporterFactoryScript;
    },
  }),
];

Configuration

Tokens

INLINE_REPORTER_PARAMETERS_TOKEN

Example: Adding Custom Parameters

import { provide } from '@tramvai/core';
import { INLINE_REPORTER_PARAMETERS_TOKEN } from '@tramvai/module-application-monitoring';

provide({
  provide: INLINE_REPORTER_PARAMETERS_TOKEN,
  useFactory: ({ appInfo, envManager }) => {
    return {
      appName: appInfo.appName,
      appRelease: envManager.get('APP_RELEASE'),
      appVersion: envManager.get('APP_VERSION'),
      environment: envManager.get('NODE_ENV'),
      region: envManager.get('DEPLOY_REGION'),
    };
  },
  deps: {
    envManager: ENV_MANAGER_TOKEN,
    appInfo: APP_INFO_TOKEN,
  },
});

How to configure monitoring for main Tramvai events

There is a possibility to monitor the main events that occur while the Tramvai application is being initialized. Here is a list of these events:

• app:initialized
• app:initialize-failed
• app:rendered
• app:render-failed
• react:render
• react:error

When you are using ApplicationMonitoringModule, these events are sent to your remote logger by default. But in some cases, you will need custom metrics. Here is an example of how to do this:

import { provide } from '@tramvai/core';
import { TRAMVAI_HOOKS_TOKEN, commandLineListTokens } from '@tramvai/core';

const providers = [
  provide({
    provide: commandLineListTokens.init,
    useFactory: ({ tramvaiHooks }) => {
      hooks['app:initialized'].tap('app-init', () => {
        fetch('/api/monitoring', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            event: 'app-initialized',
            ...parameters,
            ...payload,
            timestamp: Date.now(),
          }),
        });
      });
      hooks['app:initialize-failed'].tap('app-init-failed', (_, { error }) => {
        fetch('/api/monitoring', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            event: 'app-initialize-failed',
            ...error,
            ...parameters,
            ...payload,
            timestamp: Date.now(),
          }),
        });
      });
      hooks['app:rendered'].tap('app-rendered', () => {
        fetch('/api/monitoring', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            event: 'app-rendered',
            ...parameters,
            ...payload,
            timestamp: Date.now(),
          }),
        });
        s;
      });
      hooks['app:render-failed'].tap('app-render-failed', (_, { error }) => {
        fetch('/api/monitoring', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            event: 'app-render-failed',
            error,
            ...parameters,
            ...payload,
            timestamp: Date.now(),
          }),
        });
        s;
      });

      hooks['react:render'].tap('react-render', () => {
        fetch('/api/monitoring', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            event: eventName,
            ...parameters,
            ...payload,
            timestamp: Date.now(),
          }),
        });
      });

      hooks['react:error'].tap('react-error', (_, { error }) => {
        fetch('/api/monitoring', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            error,
            event: 'react-error',
            ...parameters,
            ...payload,
            timestamp: Date.now(),
          }),
        });
      });
    },
    deps: {
      tramvaiHooks: TRAMVAI_HOOKS_TOKEN,
    },
  }),
];

How It Works

Server-Side

1. Inline Scripts Injection: The module injects monitoring scripts into the HTML <head> during server-side rendering
2. Early Monitoring: Scripts execute immediately to catch early errors and events
3. Reporter Initialization: The inline reporter factory creates a global reporter instance
4. Hook Registration: Server-side hooks are registered to track initialization events

Client-Side

1. HTML Opened: First script executes when HTML is parsed
2. Asset Monitoring: Error listeners track script/link loading failures
3. App Creation: Monitors unhandled errors during app bootstrap
4. Initialization: Tracks when app completes initialization
5. Rendering: Integrates with error boundaries and renderer callbacks

Event Flow

HTML Parse → html-opened
    ↓
Asset Loading → assets-loaded / assets-load-failed
    ↓
App Bootstrap → app-start-failed (on error)
    ↓
App Init → app-initialized
    ↓
App Render → app-rendered / app-render-failed
    ↓
Runtime → unhandled-error (if occurs)