@humanode-hyperlane/metrics 0.0.0-stage → 0.2.8

package/src/gauges.ts

@@ -0,0 +1,136 @@
+import { Gauge, type Registry } from 'prom-client';
+
+import type {
+  WarpRouteMetricLabels,
+  WarpRouteValueAtRiskMetricLabels,
+} from './types.js';
+
+/**
+ * Label names for warp route metrics.
+ */
+export const warpRouteMetricLabels: (keyof WarpRouteMetricLabels)[] = [
+  'chain_name',
+  'token_address',
+  'token_name',
+  'wallet_address',
+  'token_standard',
+  'warp_route_id',
+  'related_chain_names',
+];
+
+/**
+ * Label names for value at risk metrics.
+ */
+export const warpRouteValueAtRiskMetricLabels: (keyof WarpRouteValueAtRiskMetricLabels)[] =
+  [
+    'chain_name',
+    'collateral_chain_name',
+    'token_address',
+    'token_name',
+    'collateral_token_standard',
+    'warp_route_id',
+  ];
+
+/**
+ * Wallet balance metric label names.
+ */
+export const walletBalanceMetricLabels = [
+  'chain',
+  'wallet_address',
+  'wallet_name',
+  'token_address',
+  'token_symbol',
+  'token_name',
+] as const;
+
+/**
+ * xERC20 limits metric label names.
+ */
+export const xERC20LimitsMetricLabels = [
+  'chain_name',
+  'limit_type',
+  'token_name',
+  'bridge_address',
+  'token_address',
+  'bridge_label',
+] as const;
+
+/**
+ * Collection of warp route Prometheus gauges.
+ */
+export interface WarpMetricsGauges {
+  warpRouteTokenBalance: Gauge<string>;
+  warpRouteCollateralValue: Gauge<string>;
+  warpRouteValueAtRisk: Gauge<string>;
+  walletBalanceGauge: Gauge<string>;
+  xERC20LimitsGauge: Gauge<string>;
+}
+
+/**
+ * Creates a new wallet balance gauge with optional additional labels.
+ */
+export function createWalletBalanceGauge(
+  registry: Registry,
+  additionalLabels: string[] = [],
+): Gauge<string> {
+  return new Gauge({
+    // Mirror the rust/main/ethers-prometheus `wallet_balance` gauge metric.
+    name: 'hyperlane_wallet_balance',
+    help: 'Current balance of a wallet for a token',
+    registers: [registry],
+    labelNames: [...walletBalanceMetricLabels, ...additionalLabels],
+  });
+}
+
+/**
+ * Creates all warp route metric gauges and registers them with the provided registry.
+ *
+ * @param registry - The Prometheus registry to register the gauges with
+ * @param walletBalanceAdditionalLabels - Optional additional labels for the wallet balance gauge
+ * @returns Collection of warp metric gauges
+ */
+export function createWarpMetricsGauges(
+  registry: Registry,
+  walletBalanceAdditionalLabels: string[] = [],
+): WarpMetricsGauges {
+  const warpRouteTokenBalance = new Gauge({
+    name: 'hyperlane_warp_route_token_balance',
+    help: 'HypERC20 token balance of a Warp Route',
+    registers: [registry],
+    labelNames: warpRouteMetricLabels,
+  });
+
+  const warpRouteCollateralValue = new Gauge({
+    name: 'hyperlane_warp_route_collateral_value',
+    help: 'Total value of collateral held in a HypERC20Collateral or HypNative contract of a Warp Route',
+    registers: [registry],
+    labelNames: warpRouteMetricLabels,
+  });
+
+  const warpRouteValueAtRisk = new Gauge({
+    name: 'hyperlane_warp_route_value_at_risk',
+    help: 'Value at risk on chain for a given Warp Route',
+    registers: [registry],
+    labelNames: warpRouteValueAtRiskMetricLabels,
+  });
+
+  const walletBalanceGauge = createWalletBalanceGauge(
+    registry,
+    walletBalanceAdditionalLabels,
+  );
+
+  const xERC20LimitsGauge = new Gauge({
+    name: 'hyperlane_xerc20_limits',
+    help: 'Current minting and burning limits of xERC20 tokens',
+    registers: [registry],
+    labelNames: xERC20LimitsMetricLabels,
+  });
+
+  return {
+    warpRouteTokenBalance,
+    warpRouteCollateralValue,
+    warpRouteValueAtRisk,
+    walletBalanceGauge,
+    xERC20LimitsGauge,
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,52 @@
+import { expect } from 'chai';
+import { Registry } from 'prom-client';
+
+import { createWarpMetricsGauges } from './gauges.js';
+
+describe('Warp Metrics', () => {
+  describe('createWarpMetricsGauges', () => {
+    it('should create all required gauges', () => {
+      const registry = new Registry();
+      const gauges = createWarpMetricsGauges(registry);
+
+      expect(gauges).to.have.property('warpRouteTokenBalance');
+      expect(gauges).to.have.property('warpRouteCollateralValue');
+      expect(gauges).to.have.property('warpRouteValueAtRisk');
+      expect(gauges).to.have.property('walletBalanceGauge');
+      expect(gauges).to.have.property('xERC20LimitsGauge');
+    });
+
+    it('should register gauges with the provided registry', async () => {
+      const registry = new Registry();
+      createWarpMetricsGauges(registry);
+
+      const metrics = await registry.metrics();
+      expect(metrics).to.include('hyperlane_warp_route_token_balance');
+      expect(metrics).to.include('hyperlane_warp_route_collateral_value');
+      expect(metrics).to.include('hyperlane_warp_route_value_at_risk');
+      expect(metrics).to.include('hyperlane_wallet_balance');
+      expect(metrics).to.include('hyperlane_xerc20_limits');
+    });
+
+    it('should support additional wallet balance labels', async () => {
+      const registry = new Registry();
+      const gauges = createWarpMetricsGauges(registry, ['warp_route_id']);
+
+      // Set a value to verify the label is accepted
+      gauges.walletBalanceGauge
+        .labels({
+          chain: 'ethereum',
+          wallet_address: '0x123',
+          wallet_name: 'test',
+          token_address: 'native',
+          token_symbol: 'ETH',
+          token_name: 'Ether',
+          warp_route_id: 'test-route',
+        })
+        .set(1.5);
+
+      const metrics = await registry.metrics();
+      expect(metrics).to.include('warp_route_id="test-route"');
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,53 @@
+// Types
+export {
+  type BaseWarpRouteMetricLabels,
+  type NativeWalletBalance,
+  type SupportedTokenStandards,
+  type WarpRouteBalance,
+  type WarpRouteMetricLabels,
+  type WarpRouteValueAtRiskMetricLabels,
+  type XERC20Info,
+  type XERC20Limit,
+} from './types.js';
+
+// Gauges and factory
+export {
+  createWalletBalanceGauge,
+  createWarpMetricsGauges,
+  type WarpMetricsGauges,
+  walletBalanceMetricLabels,
+  warpRouteMetricLabels,
+  warpRouteValueAtRiskMetricLabels,
+  xERC20LimitsMetricLabels,
+} from './gauges.js';
+
+// Metric update functions
+export {
+  updateManagedLockboxBalanceMetrics,
+  updateNativeWalletBalanceMetrics,
+  updateTokenBalanceMetrics,
+  updateXERC20LimitsMetrics,
+} from './update.js';
+
+// Balance utilities
+export {
+  getExtraLockboxBalance,
+  getExtraLockboxInfo,
+  getManagedLockBox,
+  getManagedLockBoxCollateralInfo,
+  getSealevelAtaPayerBalance,
+  getTokenBridgedBalance,
+  getXERC20Info,
+  getXERC20Limit,
+  MANAGED_LOCKBOX_MINIMAL_ABI,
+  type TokenPriceGetter,
+} from './balance.js';
+
+// Utilities
+export { formatBigInt } from './utils.js';
+
+// Server
+export { startMetricsServer } from './server.js';
+
+// Push Gateway
+export { getPushGateway, submitMetrics } from './pushgateway.js';

package/src/pushgateway.ts

@@ -0,0 +1,66 @@
+import type { Logger } from 'pino';
+import { Pushgateway, type Registry } from 'prom-client';
+import { format } from 'util';
+
+import { rootLogger } from '@humanode-hyperlane/utils';
+
+/**
+ * Gets the push gateway if PROMETHEUS_PUSH_GATEWAY environment variable is set.
+ *
+ * @param register - The Prometheus registry
+ * @param logger - Optional logger instance
+ * @returns The Pushgateway instance or null if not configured
+ */
+export function getPushGateway(
+  register: Registry,
+  logger?: Logger,
+): Pushgateway | null {
+  const log = logger ?? rootLogger.child({ module: 'metrics' });
+  const gatewayAddr = process.env['PROMETHEUS_PUSH_GATEWAY'];
+  if (gatewayAddr) {
+    return new Pushgateway(gatewayAddr, [], register);
+  } else {
+    log.warn(
+      'Prometheus push gateway address was not defined; not publishing metrics.',
+    );
+    return null;
+  }
+}
+
+/**
+ * Submits metrics to a Prometheus push gateway.
+ *
+ * @param register - The Prometheus registry to submit
+ * @param jobName - The job name for the metrics
+ * @param options - Optional configuration
+ * @param options.overwriteAllMetrics - If true, overwrites all metrics instead of adding
+ * @param logger - Optional logger instance
+ */
+export async function submitMetrics(
+  register: Registry,
+  jobName: string,
+  options?: { overwriteAllMetrics?: boolean },
+  logger?: Logger,
+): Promise<void> {
+  const log = logger ?? rootLogger.child({ module: 'metrics' });
+  const gateway = getPushGateway(register, log);
+  if (!gateway) return;
+
+  let resp;
+  try {
+    if (options?.overwriteAllMetrics) {
+      resp = (await gateway.push({ jobName })).resp;
+    } else {
+      resp = (await gateway.pushAdd({ jobName })).resp;
+    }
+  } catch (e) {
+    log.error('Error when pushing metrics', { error: format(e) });
+    return;
+  }
+
+  const statusCode =
+    typeof resp == 'object' && resp != null && 'statusCode' in resp
+      ? (resp as any).statusCode
+      : 'unknown';
+  log.info('Prometheus metrics pushed to PushGateway', { statusCode });
+}

package/src/server.test.ts

@@ -0,0 +1,32 @@
+import { expect } from 'chai';
+import { Registry } from 'prom-client';
+
+import { startMetricsServer } from './server.js';
+
+describe('startMetricsServer', () => {
+  const originalPort = process.env['PROMETHEUS_PORT'];
+
+  afterEach(() => {
+    if (originalPort === undefined) {
+      delete process.env['PROMETHEUS_PORT'];
+    } else {
+      process.env['PROMETHEUS_PORT'] = originalPort;
+    }
+  });
+
+  it('throws for non-numeric PROMETHEUS_PORT values', () => {
+    process.env['PROMETHEUS_PORT'] = '';
+
+    expect(() => startMetricsServer(new Registry())).to.throw(
+      /PROMETHEUS_PORT must contain only digits/i,
+    );
+  });
+
+  it('throws for out-of-range PROMETHEUS_PORT values', () => {
+    process.env['PROMETHEUS_PORT'] = '70000';
+
+    expect(() => startMetricsServer(new Registry())).to.throw(
+      /PROMETHEUS_PORT must be between 1 and 65535/i,
+    );
+  });
+});

package/src/server.ts

@@ -0,0 +1,76 @@
+import http from 'http';
+import type { Logger } from 'pino';
+import type { Registry } from 'prom-client';
+
+/**
+ * Start a simple HTTP server to host metrics. This takes the registry and dumps the text
+ * string to people who request `GET /metrics`.
+ *
+ * PROMETHEUS_PORT env var is used to determine what port to host on, defaults to 9090.
+ *
+ * @param register - The Prometheus registry to serve metrics from
+ * @param logger - Optional logger instance for error logging
+ * @returns The HTTP server instance
+ */
+export function startMetricsServer(
+  register: Registry,
+  logger?: Logger,
+): http.Server {
+  const configuredPort = process.env['PROMETHEUS_PORT'];
+  const portString = configuredPort ?? '9090';
+
+  if (!/^\d+$/.test(portString)) {
+    const message =
+      'PROMETHEUS_PORT must contain only digits and be between 1 and 65535';
+    logger?.error({ port: configuredPort }, message);
+    throw new Error(message);
+  }
+
+  const port = Number(portString);
+
+  if (port < 1 || port > 65535) {
+    const message = 'PROMETHEUS_PORT must be between 1 and 65535';
+    logger?.error({ port }, message);
+    throw new Error(message);
+  }
+
+  const server = http
+    .createServer((req, res) => {
+      if (req.url !== '/metrics') {
+        res.writeHead(404, 'Invalid url').end();
+        return;
+      }
+      if (req.method !== 'GET') {
+        res.writeHead(405, 'Invalid method').end();
+        return;
+      }
+
+      register
+        .metrics()
+        .then((metricsStr) => {
+          res
+            .writeHead(200, { 'Content-Type': register.contentType })
+            .end(metricsStr);
+        })
+        .catch((err) => {
+          if (logger) {
+            logger.error(err, 'Failed to collect metrics');
+          }
+          res
+            .writeHead(500, { 'Content-Type': 'text/plain' })
+            .end('Internal Server Error');
+        });
+    })
+    .on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE') {
+        logger?.error(
+          `Metrics server port ${port} already in use. Set PROMETHEUS_PORT to use a different port.`,
+        );
+      } else {
+        logger?.error(err, 'Metrics server error');
+      }
+    })
+    .listen(port);
+
+  return server;
+}

package/src/types.ts

@@ -0,0 +1,74 @@
+import type { ChainName, TokenStandard } from '@humanode-hyperlane/sdk';
+import type { Address } from '@humanode-hyperlane/utils';
+
+/**
+ * xERC20 minting and burning limits for a token.
+ */
+export interface XERC20Limit {
+  mint: number;
+  burn: number;
+  mintMax: number;
+  burnMax: number;
+}
+
+/**
+ * xERC20 information including limits and the xERC20 token address.
+ */
+export interface XERC20Info {
+  limits: XERC20Limit;
+  xERC20Address: Address;
+}
+
+/**
+ * Balance information for a warp route token.
+ */
+export interface WarpRouteBalance {
+  balance: number;
+  valueUSD?: number;
+  tokenAddress: Address;
+}
+
+/**
+ * Native wallet balance information.
+ */
+export interface NativeWalletBalance {
+  chain: ChainName;
+  walletAddress: Address;
+  walletName: string;
+  balance: number;
+}
+
+/**
+ * Token standards supported by warp metrics, including pseudo-standards.
+ */
+export type SupportedTokenStandards =
+  | TokenStandard
+  | 'EvmManagedLockbox'
+  | 'xERC20';
+
+/**
+ * Base metric labels common to all warp route metrics.
+ */
+export interface BaseWarpRouteMetricLabels {
+  chain_name: ChainName;
+  token_address: string;
+  token_name: string;
+  warp_route_id: string;
+}
+
+/**
+ * Full warp route metric labels including wallet and token standard info.
+ */
+export interface WarpRouteMetricLabels extends BaseWarpRouteMetricLabels {
+  wallet_address: string;
+  token_standard: SupportedTokenStandards;
+  related_chain_names: string;
+}
+
+/**
+ * Value at risk metric labels.
+ */
+export interface WarpRouteValueAtRiskMetricLabels extends BaseWarpRouteMetricLabels {
+  collateral_chain_name: ChainName;
+  collateral_token_standard: SupportedTokenStandards;
+}