Monitoring & Telemetry

Collect ticks, balances, HTTP timings, and export Prometheus metrics from @qubiq/core.

This module (@qubiq/core/monitoring) keeps production services observable. Use it alongside automation pipelines, connectors, or your own workers.

Tick & Balance Monitors

import { TickMonitor, BalanceMonitor } from "@qubiq/core/monitoring";
import { LiveServiceClient } from "@qubiq/core/clients";

const live = new LiveServiceClient();
const tickMonitor = new TickMonitor({ client: live, pollIntervalMs: 1_000 });
tickMonitor.on("sample", (sample) => console.log(sample.tick.tick));

const balanceMonitor = new BalanceMonitor({
  client: live,
  identity: "SUZ...",
  pollIntervalMs: 5_000,
});
balanceMonitor.on("sample", ({ current, previous }) => {
  console.log("delta", BigInt(current.balance) - BigInt(previous?.balance ?? 0n));
});

Events emitted

sample — contains current reading, previous snapshot (if any), latency metrics, and poll timestamps.
Errors are thrown so you can surface to Sentry or fallbacks.

TelemetryMetricsRegistry

import { TelemetryMetricsRegistry } from "@qubiq/core/monitoring";

const metrics = new TelemetryMetricsRegistry();
metrics.observeTick({ tick: 180_000, epoch: 185, duration: 90 });
metrics.observeBalance({ identity: "SUZ...", balance: "100" });
metrics.recordRequest({ name: "live.getBalance", durationMs: 120, success: true });

Stores the latest tick/balance samples.
Aggregates HTTP timings and error counters.
Feeds Prometheus exposure but can also back Graphite/StatsD bridges.

PrometheusMetricsServer

import { PrometheusMetricsServer } from "@qubiq/core/monitoring";

const server = new PrometheusMetricsServer({ registry: metrics, port: 9301 });
await server.start();
// GET /metrics → tick_gauge{}, balance_gauge{identity="SUZ..."} etc.

Metrics exported

qubiq_tick_info{} — latest tick, epoch, duration.
qubiq_balance{identity} — tracked identities.
qubiq_http_request_duration_seconds_bucket|sum|count.
qubiq_http_request_errors_total{name}.

Request instrumentation

Wrap any async call (HTTP or database) with instrumentRequest:

import { instrumentRequest } from "@qubiq/core/monitoring";

await instrumentRequest(metrics, "live.getBalance", async () => live.getBalance("SUZ..."));

It records duration, success/failure, and optional labels so you can drill down by endpoint or dependency.

Runtime integrations

Automation runtimes (see the automation page) wire monitors automatically.
Wallet watchers emit balanceChanged, but you can also pipe their output into TelemetryMetricsRegistry.
Use TelemetryMetricsRegistry + PrometheusMetricsServer in headless workers, dashboards, or CLI watchers for consistent observability.