API reference#

import {
  initObservability,
  installErrorCapture,
  toError,
  createHttpSink,
  Memory,
} from '@sigx/lynx-observability';
import type {
  ObservabilityOptions,
  ErrorCaptureOptions,
  HttpSink,
  HttpSinkOptions,
  MemoryCollectionStatus,
  MemoryInstanceUsage,
  MemoryQueryOptions,
  MemoryReportingOptions,
  MemoryUsageSnapshot,
} from '@sigx/lynx-observability';

export function initObservability(opts?: ObservabilityOptions): void

export function installErrorCapture(opts?: ErrorCaptureOptions): () => void

export function toError(input: unknown): Error

export function createHttpSink(opts: HttpSinkOptions): HttpSink

const Memory: {
  query(options?: MemoryQueryOptions): Promise<MemoryUsageSnapshot>;
  startReporting(options?: MemoryReportingOptions): () => void;
  isAvailable(): boolean;
};

query(options?: MemoryQueryOptions): Promise<MemoryUsageSnapshot>

startReporting(options?: MemoryReportingOptions): () => void

isAvailable(): boolean

export interface ObservabilityOptions {
  /** Override the global log level (e.g. 'warn' in production). */
  level?: LogLevelName;
  /** Remote sink to forward records to. Omit for error-capture only. */
  sink?: HttpSinkOptions;
  /** Capture uncaught errors / unhandled rejections. Default true. */
  captureErrors?: boolean;
  /** Options for installErrorCapture (e.g. an extra onError hook). */
  errorCapture?: ErrorCaptureOptions;
  /** Periodic engine memory readings. Presence enables it — `{}` is "on, with the defaults". */
  memory?: MemoryReportingOptions;
}

export interface ErrorCaptureOptions {
  /** Extra callback invoked with the normalized Error for each captured error. */
  onError?: (error: Error) => void;
}

export interface HttpSinkOptions {
  /** Endpoint that receives POST { records: WireRecord[] }. */
  url: string;
  /** Extra headers (e.g. auth). content-type: application/json is set for you. */
  headers?: Record<string, string>;
  /** Flush once the buffer reaches this many records. Default 20. */
  batchSize?: number;
  /** Flush at most this often (ms) while records trickle in. Default 5000. */
  flushIntervalMs?: number;
  /** Keep this fraction (0–1) of non-error records; errors are always kept. Default 1. */
  sampleRate?: number;
  /** Only send records at or above this level. Default 'info'. */
  minLevel?: LogLevelName;
  /** Namespaces to drop. Default ['http'] (prevents the sink's own POSTs feeding back). */
  excludeNamespaces?: string[];
}

export type HttpSink = LogTransport & { flush(): void };

export interface MemoryQueryOptions {
  /** How long the engine waits for every instance to report, in ms. Omit or <= 0 for the engine default (2000). */
  timeoutMs?: number;
}

export interface MemoryReportingOptions extends MemoryQueryOptions {
  /** Gap between the END of one reading and the start of the next, in ms. Default 60000. */
  intervalMs?: number;
  /** Level the reading is logged at. Default 'info'. */
  level?: Exclude<LogLevelName, 'silent'>;
  /** Take a reading straight away rather than waiting one interval. Default true. */
  immediate?: boolean;
  /** How many per-instance rows ride along in the record. Default 5; 0 omits them. */
  maxInstances?: number;
  /** Extra callback per reading (analytics, a HUD, …). Throwing won't stop the loop. */
  onReading?: (snapshot: MemoryUsageSnapshot) => void;
}

export interface MemoryUsageSnapshot {
  /** 'timeout' means every aggregate below is a PARTIAL sum over completedInstanceCount of expectedInstanceCount. */
  collectionStatus: MemoryCollectionStatus;
  /** Wall-clock start of the collection, in ms. */
  collectionStartMs: number;
  /** How long the collection actually took, in ms. */
  collectionDurationMs: number;
  /** The timeout the engine applied, in ms. */
  collectionTimeoutMs: number;
  /** Live instances snapshotted when the request started. */
  expectedInstanceCount: number;
  /** Instances that reported in time and are included below. */
  completedInstanceCount: number;
  /** Lynx-attributed total. Excludes appBytes; shared runtimes counted once. */
  totalBytes: number;
  /** The app's whole physical footprint when the result was built. */
  appBytes: number;
  /** totalBytes / appBytes, or 0 when the engine couldn't sample appBytes. */
  ratioToApp: number;
  /** Element-tree bytes summed over completed instances. */
  elementBytes: number;
  /** Element nodes summed over completed instances. */
  elementNodeCount: number;
  /** Platform UI bytes summed over completed instances. */
  viewBytes: number;
  /** Main-thread runtime heap summed over completed instances. */
  mainThreadRuntimeBytes: number;
  /** Background runtime heap, with shared runtime groups deduplicated. */
  backgroundThreadRuntimeBytes: number;
  /** Completed instances, sorted by totalBytes descending. */
  instances: MemoryInstanceUsage[];
}

export type MemoryCollectionStatus = 'completed' | 'timeout' | 'unknown';

export interface MemoryInstanceUsage {
  /** null when the instance was never fully attached (native reports -1). */
  instanceId: number | null;
  /** Engine-side page identity — a debugging label, not a key. */
  pageId: string;
  /** Template URL captured when this instance's fetcher completed. */
  url: string;
  /** elementBytes + viewBytes + both runtime figures, for this instance. */
  totalBytes: number;
  /** Element-tree memory from the native element manager. */
  elementBytes: number;
  /** Element node count — the context that makes elementBytes readable. */
  elementNodeCount: number;
  /** Platform UI memory (LynxUIOwner on iOS, the UI owner on Android). */
  viewBytes: number;
  /** Main-thread runtime heap. */
  mainThreadRuntimeBytes: number;
  /** Background-thread runtime heap. */
  backgroundThreadRuntimeBytes: number;
  /** Background runtime group. Instances sharing a non-empty group share one runtime. */
  btsRuntimeGroupId: string;
}