@amiki/metrics

OpenMetrics / Prometheus exporter for amiki-framework — zero external dependencies.

Counter, Gauge, Histogram types with Prometheus exposition format, HTTP metrics server, and built-in process-level collectors.

Installation

bun add @amiki/metrics

Quick Start

import { MetricRegistry, MetricsServer, registerProcessMetrics } from '@amiki/metrics';

// Create registry with prefix and default labels
const registry = new MetricRegistry({
  prefix: 'amiki',
  defaultLabels: {
    service: 'my-bot',
    environment: 'production',
  },
});

// Register process metrics (RSS, heap, event loop lag, CPU, open fds)
registerProcessMetrics(registry);

// Expose /metrics endpoint
const server = new MetricsServer({ port: 9090, registry });
server.start();

// Create and use metrics
const eventsTotal = registry.counter('events_total', 'Total events received');
eventsTotal.inc({ type: 'MESSAGE_CREATE' });
eventsTotal.inc({ type: 'MESSAGE_CREATE' }); // → 2

const latency = registry.histogram('events_latency_ms', 'Event processing latency');
latency.observe(42);
latency.observe(128, { shard_id: '0' });

const connectedShards = registry.gauge('connected_shards', 'Currently connected shards');
connectedShards.set(16);
connectedShards.dec(); // → 15

API

MetricRegistry

const registry = new MetricRegistry({ prefix, defaultLabels });

registry.counter(name, help, labels?): Counter
registry.gauge(name, help, labels?): Gauge
registry.histogram(name, help, labels?, buckets?): Histogram
registry.collectMetrics(): AsyncGenerator<MetricSample>

Counter

Monotonically increasing counter (requests total, events total, errors total).

counter.inc(labels?);
counter.add(value, labels?);
counter.reset();
counter.collect(): CounterSample[];

Gauge

Single numeric value that can go up and down (queue depth, connected shards, memory).

gauge.set(value, labels?);
gauge.inc(labels?);
gauge.dec(labels?);
gauge.add(value, labels?);
gauge.reset();
gauge.collect(): GaugeSample[];

Histogram

Value observations into configurable buckets (latency, payload size, duration).

histogram.observe(value, labels?);
histogram.reset();
histogram.collect(): HistogramSample[];

Default buckets (ms): [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]

MetricsServer

const server = new MetricsServer({
  port: 9090,
  registry,
  host?: '0.0.0.0',        // default: '0.0.0.0'
  path?: '/metrics',        // default: '/metrics'
});

server.start();
server.stop();

Process Metrics

registerProcessMetrics(registry);

Collects: process_rss_bytes, process_heap_bytes, process_event_loop_lag_seconds, process_cpu_seconds_total, process_open_fds.

Output Format

OpenMetrics exposition format (/metrics endpoint):

# HELP amiki_events_total Total events received
# TYPE amiki_events_total counter
amiki_events_total{service="my-bot",environment="production",type="MESSAGE_CREATE"} 2 1234567890

# HELP amiki_events_latency_ms Event processing latency
# TYPE amiki_events_latency_ms histogram
amiki_events_latency_ms_bucket{le="1"} 0
amiki_events_latency_ms_bucket{le="5"} 0
amiki_events_latency_ms_bucket{le="10"} 1
amiki_events_latency_ms_bucket{le="+Inf"} 2
amiki_events_latency_ms_count 2
amiki_events_latency_ms_sum 170
# EOF

Integration with amiki packages

import { GatewayMetrics } from '@amiki/core';
import { ClusterMetrics } from '@amiki/cluster';
import { ProxyMetrics } from '@amiki/gateway-proxy';
import { MetricRegistry } from '@amiki/metrics';

const registry = new MetricRegistry({ prefix: 'amiki' });

// Create cluster-level metrics
const clusterMetrics = new ClusterMetrics(registry);
const gatewayMetrics = new GatewayMetrics(registry);
const proxyMetrics = new ProxyMetrics(registry);

License

GPL-2.0-only — see LICENSE for details.