Monitoring Adapters

Built-in and custom adapters for sending monitoring events to different destinations.

Adapters are the output layer of the monitoring system: each one receives batches of MonitoringEvent objects and forwards them somewhere — console, remote API, localStorage. A RilayMonitor can have several adapters at once.

The MonitoringAdapter Interface

interface MonitoringAdapter {
  readonly name: string;
  readonly version?: string;
  send(events: MonitoringEvent[]): Promise<void>;
  flush?(): Promise<void>;
  configure?(config: Record<string, any>): void;
}

Member	Required	Description
`name`	Yes	Unique identifier, used by `removeAdapter()`.
`send(events)`	Yes	Receives each batch at the flush interval.
`flush()`	No	Called by `monitor.destroy()` on shutdown to force-send any events the adapter buffers internally. `monitor.flush()` only calls `send()`.
`configure(config)`	No	Runtime reconfiguration.

Built-in Adapters

ConsoleAdapter

Logs events via console.error/warn/info according to severity.

import { ConsoleAdapter } from '@rilaykit/core';

monitor.addAdapter(new ConsoleAdapter('info'));

Parameter	Type	Default	Description
`logLevel`	`'debug' \| 'info' \| 'warn' \| 'error'`	`'info'`	Minimum level; events below it are ignored.

RemoteAdapter

POSTs events to an HTTP endpoint, batched and retried with exponential backoff (4xx responses are not retried). Use this in production.

import { RemoteAdapter } from '@rilaykit/core';

monitor.addAdapter(new RemoteAdapter({
  endpoint: 'https://analytics.example.com/events',
  apiKey: 'your-api-key',
  headers: { 'X-App': 'my-app' },
  batchSize: 50,
  retryAttempts: 3,
}));

Option	Type	Default	Description
`endpoint`	`string`	—	URL to POST to. Required.
`apiKey`	`string`	—	Sent as `Authorization: Bearer <apiKey>`.
`headers`	`Record<string, string>`	`{}`	Extra headers on every request.
`batchSize`	`number`	`50`	Max events per request.
`retryAttempts`	`number`	`3`	Attempts before the batch is dropped.

The request body is JSON: { events, timestamp, source }. Respond with a 2xx status to acknowledge receipt.

LocalStorageMonitoringAdapter

Buffers events in localStorage — useful offline or across page reloads. For long-term persistence, forward events to a RemoteAdapter instead.

import { LocalStorageMonitoringAdapter } from '@rilaykit/core';

const adapter = new LocalStorageMonitoringAdapter(1000); // maxEvents; oldest discarded first
monitor.addAdapter(adapter);

adapter.getStoredEvents();  // MonitoringEvent[]
adapter.getEventCount();
adapter.clearStoredEvents();

DevelopmentAdapter

A ConsoleAdapter('debug') plus grouped summaries printed with each batch: average/max durations per event type and error counts per source. Zero configuration — use it locally, swap for RemoteAdapter in production.

import { DevelopmentAdapter } from '@rilaykit/core';

monitor.addAdapter(new DevelopmentAdapter());

Creating a Custom Adapter

Implement MonitoringAdapter to integrate any third-party service (Sentry, Datadog, Mixpanel, …):

lib/sentry-adapter.ts

import type { MonitoringAdapter, MonitoringEvent } from '@rilaykit/core';
import * as Sentry from '@sentry/browser';

class SentryAdapter implements MonitoringAdapter {
  name = 'sentry';

  async send(events: MonitoringEvent[]): Promise<void> {
    for (const event of events) {
      if (event.severity === 'critical' || event.severity === 'high') {
        Sentry.captureEvent({
          message: `[${event.type}] ${event.source}`,
          level: event.severity === 'critical' ? 'fatal' : 'error',
          extra: { data: event.data, metrics: event.metrics },
          tags: { source: event.source, eventType: event.type },
        });
      }
    }
  }

  async flush(): Promise<void> {
    await Sentry.flush(2000);
  }
}

Managing Adapters at Runtime

import { getGlobalMonitor } from '@rilaykit/core';

const monitor = getGlobalMonitor();
monitor?.addAdapter(new SentryAdapter());
monitor?.addAdapter(new ConsoleAdapter('debug'));
monitor?.removeAdapter('console'); // by name

Useful for enabling verbose logging from a debug panel or temporarily buffering a bug reproduction with LocalStorageMonitoringAdapter.

Monitoring Adapters

On this page