Design and Architecture of a Multi‑Environment Frontend Monitoring SDK

Abstract

ByteDance’s internal monitoring environment spans Web apps, mini‑programs, Electron, and cross‑platform applications. The SDK must reuse core logic, decouple upper‑level concerns, stay flexible for numerous monitoring needs, support pluginization, allow business‑driven extensions, handle massive QPS, and guarantee stability.

Logic Decoupling

Because frontend monitoring must work across vastly different runtimes, the SDK cannot be a monolithic bundle. Instead, a single design template assembles environment‑specific SDKs by separating concerns into five roles that each implement a defined interface.

Monitor – Collects raw data in a given environment and emits platform‑agnostic events.

Builder – Transforms those events into the format required by the target platform, adding context such as page URL, network status, and timestamps.

Sender – Handles the actual transmission, supporting batching, retries, and edge cases like using sendBeacon on page unload.

ConfigManager – Merges default and user configurations, fetches remote settings, and notifies subscribers when the configuration becomes ready.

Client – Orchestrates the whole flow, exposing lifecycle hooks for extensions.

Below is a TypeScript definition of the configuration manager:

export interface ConfigManager<Config> {
  setConfig: (c: Partial<Config>) => Config;
  getConfig: () => Config;
  onChange: (fn: () => void) => void;
  onReady: (fn: () => void) => void;
}

And a simplified client factory:

export const createClient = ({ configManager, builder, sender }) => {
  let inited = false;
  let started = false;
  let preStartQueue = [];
  const client = {
    init: (config) => {
      configManager.setConfig(config);
      configManager.onReady(() => {
        preStartQueue.forEach(e => this.report(e));
        started = true;
      });
      inited = true;
    },
    report: (data) => {
      if (!started) {
        preStartQueue.push(data);
      } else {
        const builderData = builder.build(data);
        builderData && sender.send(builderData);
      }
    }
  };
  return client;
};
const client = createClient({ configManager, builder, sender });
monitors.forEach(e => e(client));

Rich Lifecycle

The SDK models the monitoring pipeline as init → collect → build → send → destroy. Six lifecycle stages are exposed, each with callback‑type hooks (e.g., init, start) and processing‑type hooks (e.g., beforeBuild, beforeSend) that can modify or abort the flow.

Pluginization

Plugins hook into these lifecycles. For example, a plugin that injects environment information can listen to the report event and return a modified event:

export const InjectEnvPlugin = (client) => {
  client('on', 'report', (ev) => {
    return addEnvToSendEvent(ev);
  });
};
InjectEnvPlugin(client);

Another plugin can start data collection after the client becomes ready:

export const MonitorXXPlugin = (client) => {
  client('on', 'init', () => {
    const data = listenXX();
    client('report', data);
  });
};

Business‑Driven Extension

Simple extensions use lifecycle hooks directly, such as filtering out requests whose URL contains /test:

client('on', 'beforeSend', (ev) => {
  if (ev.common.url.includes('/test')) {
    return false;
  }
  return ev;
});

For reusable plugins, the SDK defines an Integration interface that supplies setup and optional tearDown methods, allowing any client type (WebClient, ElectronClient, etc.) to consume the plugin.

export interface Integration<T extends AnyClient> {
  name: string;
  setup: (client: T) => void;
  tearDown?: () => void;
}

Consumers can pass an array of integrations during initialization:

import client from '@apmplus/web';
import CustomPlugin from 'xxx';
client('init', {
  // ...other options
  integrations: [CustomPlugin({ config: {} })]
});

On‑Demand Loading

The full SDK bundles every monitor, but many projects only need a subset (e.g., JavaScript errors). A minimal client exports only core utilities; developers add required monitors via the integrations array.

import { createMinimalBrowserClient } from '@apmplus/web';
import { jsErrorPlugin } from '@apmplus/integrations';
const client = createMinimalBrowserClient();
client('init', {
  // ...other options
  integrations: [jsErrorPlugin()]
});

Ensuring Business Correctness

The SDK wraps any code that could affect the host application in try…catch blocks, protecting both sensitive hooks (e.g., XHR, fetch) and its own critical paths. An ObserveSelfErrorPlugin captures SDK‑generated errors for separate reporting.

Minimizing Business Impact

Performance is a first‑class requirement: the SDK avoids increasing first‑paint time by loading high‑priority monitors early and deferring low‑priority ones. Each plugin’s execution cost is benchmarked, and a continuous performance testing pipeline prevents regressions before release.

Early Listening

For ultra‑early events like JavaScript errors, a tiny inline script creates a global stub that records calls and page context until the full SDK loads, then replays the queued actions.

window[globalName] = function(m) {
  const onceArguments = [].slice.call(arguments);
  onceArguments.push(Date.now(), location.href);
  window[globalName].precolletArguments.push(onceArguments);
};
window[globalName].precolletArguments = [];

Quality Assurance

Given the SDK handles nearly ten million QPS, it enforces strict quality controls: comprehensive unit tests for every plugin and method, extensive automated integration tests covering all configuration permutations, pre‑release validation, optional gray‑release with partner sites, and post‑release traffic monitoring.

Getting Started

The monitoring service is now available on Volcano Engine. By integrating the SDK, developers can obtain real‑time performance data, alerts, clustering analysis, and detailed diagnostics for Web applications, helping to resolve white‑screen issues, performance bottlenecks, and slow queries.