Yet Another Vigil Reporter

An alternative to node-vigil-reporter.

"Vigil is an open-source Status Page you can host on your infrastructure, used to monitor all your servers and apps, and visible to your users (on a domain of your > choice, eg. status.example.com)." https://github.com/valeriansaliou/vigil

≠ Notable differences with node-vigil-reporter

• ya-vigil-reporter does not start automatically. You must call the start method.
• An end (callback way) method exists, but I don't recommend using it; use stop (Promise way) instead.
• You can call the report method manually.
• CPU usage is calculated differently (compatible with Windows OS).
• Use native fetch method.

💾 Installation

yarn add @aegenet/ya-vigil-reporter@~1
# or
npm i @aegenet/ya-vigil-reporter@~1

📝 Usage

Classic

import { YaVigilReporter } from '@aegenet/ya-vigil-reporter';

const vigilReporter = new YaVigilReporter({
  url: "https://status.example.com",
  token: "...",
  probe_id: "api",
  node_id: "my-backend", 
  replica_id: "the-one",
  interval: 30,
  // logger: console,
});

await vigilReporter.start();

/* ... */
// stop the reporter
await vigilReporter.stop();

// or specify the flush options to teardown the replica
await vigilReporter.stop({ flush: true });

📝 Custom fetch

import { YaVigilReporter } from '@aegenet/ya-vigil-reporter';
import { bFetch, type bFetchOptions } from '@aegenet/belt-fetch';

// Async DNS & cache 1mn
const bFetchOpts: bFetchOptions = {
  dnsCacheTTL: 60000,
};

const vigilReporter = new YaVigilReporter({
  url: "https://status.example.com",
  token: "...",
  probe_id: "api",
  node_id: "my-backend", 
  replica_id: "the-one",
  interval: 30,
  // logger: console,
  fetch(input, init) {
    return bFetch(input, init, bFetchOpts);
  },
});

await vigilReporter.start();

/* ... */
// stop the reporter
await vigilReporter.stop();

// or specify the flush options to teardown the replica
await vigilReporter.stop({ flush: true });

🖹 API

/**
 * Yet Another Vigil Reporter
 */
export interface IYaVigilReporter {
  /** Start the Vigil Reporter */
  start(args?: { ensure?: boolean }): Promise<void>;

  /** Stop the Vigil Reporter */
  stop(args?: { flush?: boolean }): Promise<void>;

  /** Stop the Vigil Reporter (legacy way) */
  end(args?: { flush?: boolean; done?: (error?: Error) => void }): Promise<void>;

  /** Cron is running ? */
  get isRunning(): boolean;

  /** Report the replica */
  report(args?: { /** @default true */ reThrow?: boolean }): Promise<YaVigilReportResult>;

  /** Flush the replica */
  flush(args?: { /** @default true */ reThrow?: boolean; timeout?: number }): Promise<{
    error?: Error;
  }>;
}

export interface YaVigilReporterOptions {
  /** `page_url` from Vigil `config.cfg` */
  url: string;

  /** `reporter_token` from Vigil `config.cfg` */
  token: string;

  /** The parent node of the reporting replica */
  node_id: string;

  /** The parent probe of the node */
  probe_id: string;

  /** The replica unique identifier (eg. the server LAN IP) */
  replica_id: string;

  /**
   * Reporting interval in seconds
   *
   * @default 30
   *
   */
  interval?: number;

  /**
   * Overwrite logger
   *
   * Set to `null` (and not `undefined`) to disabled the logger
   *
   * @default console
   */
  logger?: YaVigilReporterLogger | undefined | null;

  /** (legacy) Alias of `logger` options */
  console?: YaVigilReporterLogger | undefined | null;

  /** On Tick */
  onTick?: (data: YaVigilReportResult) => void;

  /** On Report Error */
  onReportError?: (error: unknown) => void;

  /** On Fetch Error */
  onFlushError?: (error: unknown) => void;

  /** Format the fetch error message */
  formatFetchError?: (resp: Response) => Promise<string> | string;

  /**
   * fetch function
   *
   * @default globalThis.fetch
   */
  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
}

Vigil HTTP API Specifications

• Vigil Reporter HTTP API protocol specifications.
• Vigil Manager HTTP API protocol specifications.

Coverage

📝 License

The MIT License - Copyright © 2023 Alexandre Genet.