Events & Metrics

runicRPC emits events for comprehensive observability and exports Prometheus metrics for monitoring.

Event Types

Endpoint Events

rpc.on('endpoint:healthy', (event) => {
  console.log(`${event.endpoint} is now healthy`);
});

rpc.on('endpoint:unhealthy', (event) => {
  console.log(`${event.endpoint} is unhealthy: ${event.reason}`);
});

rpc.on('endpoint:selected', (event) => {
  console.log(`Selected endpoint: ${event.endpoint}`);
});

Request Events

rpc.on('request:start', (event) => {
  console.log(`Starting ${event.method}`);
});

rpc.on('request:success', (event) => {
  console.log(`${event.method} completed in ${event.duration}ms`);
});

rpc.on('request:error', (event) => {
  console.error(`${event.method} failed:`, event.error);
});

rpc.on('request:retry', (event) => {
  console.log(`Retrying ${event.method}, attempt ${event.attempt}`);
});

Cache Events

rpc.on('cache:hit', (event) => {
  console.log(`Cache hit for ${event.method}`);
});

rpc.on('cache:miss', (event) => {
  console.log(`Cache miss for ${event.method}`);
});

Batch Events

rpc.on('batch:start', (event) => {
  console.log(`Batch request started with ${event.count} requests`);
});

rpc.on('batch:complete', (event) => {
  console.log(`Batch completed: ${event.count} requests in ${event.duration}ms`);
});

Deduplication Events

rpc.on('request:deduplicated', (event) => {
  console.log(`Request deduplicated: ${event.method}`);
});

Circuit Breaker Events

rpc.on('circuit:open', (event) => {
  console.warn(`Circuit opened for ${event.endpoint}`);
});

rpc.on('circuit:halfOpen', (event) => {
  console.log(`Circuit half-open for ${event.endpoint}`);
});

rpc.on('circuit:closed', (event) => {
  console.log(`Circuit closed for ${event.endpoint}`);
});

WebSocket Events

rpc.on('ws:reconnect', (event) => {
  console.log(`Reconnecting to ${event.endpoint}, attempt ${event.attempt}`);
});

Complete Example

const rpc = RunicRPC.create({
  providers: {
    helius: { apiKey: 'your-key' }
  }
});

// Monitor all events
rpc.on('endpoint:unhealthy', (event) => {
  // Alert your team
  sendAlert(`Endpoint ${event.endpoint} is down: ${event.reason}`);
});

rpc.on('circuit:open', (event) => {
  // Log to monitoring system
  logger.error('Circuit breaker opened', { endpoint: event.endpoint });
});

rpc.on('request:retry', (event) => {
  // Track retry metrics
  metrics.increment('rpc.retries', { method: event.method });
});

Removing Event Listeners

const handler = (event) => {
  console.log('Event:', event);
};

// Add listener
rpc.on('request:success', handler);

// Remove listener
rpc.off('request:success', handler);

Prometheus Metrics

runicRPC exports enhanced Prometheus metrics for comprehensive observability.

Exporting Metrics

import express from 'express';

const app = express();

app.get('/metrics', (req, res) => {
  res.set('Content-Type', 'text/plain');
  res.send(rpc.exportPrometheusMetrics());
});

app.listen(9090);

Available Metrics

Request Metrics

# Request latency with quantiles
runic_rpc_endpoint_latency_ms{endpoint="helius",quantile="p50"} 45
runic_rpc_endpoint_latency_ms{endpoint="helius",quantile="p95"} 120
runic_rpc_endpoint_latency_ms{endpoint="helius",quantile="p99"} 250
runic_rpc_endpoint_latency_ms{endpoint="helius",quantile="avg"} 52

# Request counts
runic_rpc_endpoint_requests_total{endpoint="helius"} 15420
runic_rpc_endpoint_errors_total{endpoint="helius"} 12

# Success rate
runic_rpc_endpoint_success_rate{endpoint="helius"} 0.9992

Cache Metrics

# Cache statistics
runic_rpc_cache_hits_total 8542
runic_rpc_cache_misses_total 2341
runic_rpc_cache_hit_rate 0.785

# Deduplication
runic_rpc_deduplication_count 156

Circuit Breaker Metrics

# Circuit breaker state (0=closed, 1=half-open, 2=open)
runic_rpc_circuit_breaker_state{endpoint="helius"} 0
runic_rpc_circuit_breaker_state{endpoint="alchemy"} 0

Health Check Metrics

# Health status (1=healthy, 0=unhealthy)
runic_rpc_endpoint_healthy{endpoint="helius"} 1
runic_rpc_endpoint_healthy{endpoint="alchemy"} 1

Grafana Dashboard

Example Grafana queries:

# Request rate by endpoint
rate(runic_rpc_endpoint_requests_total[5m])

# Error rate
rate(runic_rpc_endpoint_errors_total[5m]) / rate(runic_rpc_endpoint_requests_total[5m])

# P95 latency over time
runic_rpc_endpoint_latency_ms{quantile="p95"}

# Cache hit rate
runic_rpc_cache_hit_rate