metrics

Metrics - Complete API Reference

Monitor system health, track performance metrics, and analyze telemetry data.

---

Chat Commands

System Metrics

/metrics                               Show current metrics
/metrics system                        CPU, memory, latency
/metrics api                           API performance stats
/metrics ws                            WebSocket health

Trading Metrics

/metrics trades                        Trade execution stats
/metrics fills                         Fill rate metrics
/metrics latency                       Order latency stats
/metrics errors                        Error rates

Custom Metrics

/metrics track <name> <value>          Track custom metric
/metrics query <name>                  Query metric history
/metrics alert <name> > 100            Set metric alert

Export & Reports

/metrics export csv                    Export to CSV
/metrics report daily                  Generate daily report
/metrics dashboard                     Open metrics dashboard

---

TypeScript API Reference

Create Metrics Service

import { createMetricsService } from 'clodds/metrics';

const metrics = createMetricsService({
  // Collection
  collectInterval: 5000,  // ms
  retention: '30d',

  // Storage
  storage: 'sqlite',
  dbPath: './metrics.db',

  // Export
  enablePrometheus: true,
  prometheusPort: 9090,
});

// Start collection
await metrics.start();

System Metrics

const system = await metrics.getSystemMetrics();

console.log('=== System Health ===');
console.log(`CPU Usage: ${system.cpuUsage}%`);
console.log(`Memory: ${system.memoryUsed}MB / ${system.memoryTotal}MB`);
console.log(`Uptime: ${system.uptimeHours}h`);
console.log(`Active connections: ${system.activeConnections}`);
console.log(`Event loop lag: ${system.eventLoopLag}ms`);

API Metrics

const api = await metrics.getApiMetrics();

console.log('=== API Performance ===');
console.log(`Total requests: ${api.totalRequests}`);
console.log(`Requests/sec: ${api.requestsPerSecond}`);
console.log(`Avg latency: ${api.avgLatency}ms`);
console.log(`P50 latency: ${api.p50Latency}ms`);
console.log(`P95 latency: ${api.p95Latency}ms`);
console.log(`P99 latency: ${api.p99Latency}ms`);
console.log(`Error rate: ${api.errorRate}%`);

console.log('\nBy Endpoint:');
for (const endpoint of api.byEndpoint) {
  console.log(`  ${endpoint.path}: ${endpoint.avgLatency}ms (${endpoint.calls} calls)`);
}

WebSocket Metrics

const ws = await metrics.getWebSocketMetrics();

console.log('=== WebSocket Health ===');
console.log(`Active connections: ${ws.activeConnections}`);
console.log(`Messages/sec: ${ws.messagesPerSecond}`);
console.log(`Avg message size: ${ws.avgMessageSize} bytes`);
console.log(`Reconnections: ${ws.reconnections}`);
console.log(`Dropped messages: ${ws.droppedMessages}`);

console.log('\nBy Feed:');
for (const feed of ws.byFeed) {
  console.log(`  ${feed.name}: ${feed.messagesPerSecond}/s, ${feed.latency}ms lag`);
}

Trade Execution Metrics

const trades = await metrics.getTradeMetrics();

console.log('=== Trade Execution ===');
console.log(`Total orders: ${trades.totalOrders}`);
console.log(`Fill rate: ${trades.fillRate}%`);
console.log(`Partial fills: ${trades.partialFillRate}%`);
console.log(`Rejections: ${trades.rejectionRate}%`);
console.log(`Avg fill time: ${trades.avgFillTime}ms`);
console.log(`Avg slippage: ${trades.avgSlippage}%`);

console.log('\nBy Platform:');
for (const platform of trades.byPlatform) {
  console.log(`  ${platform.name}:`);
  console.log(`    Fill rate: ${platform.fillRate}%`);
  console.log(`    Avg latency: ${platform.avgLatency}ms`);
}

Latency Breakdown

const latency = await metrics.getLatencyBreakdown();

console.log('=== Latency Breakdown ===');
console.log(`Total order latency: ${latency.total}ms`);
console.log(`  Signal processing: ${latency.signalProcessing}ms`);
console.log(`  Order construction: ${latency.orderConstruction}ms`);
console.log(`  Network round-trip: ${latency.networkRoundTrip}ms`);
console.log(`  Exchange processing: ${latency.exchangeProcessing}ms`);
console.log(`  Confirmation: ${latency.confirmation}ms`);

Error Metrics

const errors = await metrics.getErrorMetrics();

console.log('=== Error Rates ===');
console.log(`Total errors: ${errors.totalErrors}`);
console.log(`Error rate: ${errors.errorRate}%`);
console.log(`Errors/hour: ${errors.errorsPerHour}`);

console.log('\nBy Type:');
for (const type of errors.byType) {
  console.log(`  ${type.name}: ${type.count} (${type.percentage}%)`);
}

console.log('\nBy Platform:');
for (const platform of errors.byPlatform) {
  console.log(`  ${platform.name}: ${platform.errorRate}%`);
}

Custom Metrics

// Track custom metric
metrics.track('edge_detected', 1, {
  market: 'trump-2028',
  edgeSize: 0.05,
});

// Increment counter
metrics.increment('trades_executed');

// Set gauge
metrics.gauge('active_positions', 5);

// Record timing
const timer = metrics.startTimer('order_execution');
// ... execute order ...
timer.end();

// Histogram
metrics.histogram('slippage', 0.003, {
  platform: 'polymarket',
});

Query Metrics

const query = await metrics.query({
  metric: 'edge_detected',
  period: '7d',
  aggregation: 'sum',
  groupBy: 'market',
});

console.log('Edge Detection by Market:');
for (const row of query.results) {
  console.log(`  ${row.market}: ${row.value} detections`);
}

Metric Alerts

// Set alert threshold
metrics.setAlert({
  metric: 'error_rate',
  condition: '>',
  threshold: 5,  // > 5% error rate
  window: '5m',
  action: 'notify',
});

metrics.setAlert({
  metric: 'latency_p99',
  condition: '>',
  threshold: 1000,  // > 1000ms
  window: '1m',
  action: 'escalate',
});

// Alert handlers
metrics.on('alert', (alert) => {
  console.log(`🚨 Alert: ${alert.metric} ${alert.condition} ${alert.threshold}`);
  console.log(`  Current value: ${alert.currentValue}`);
});

Export Metrics

// Export to CSV
await metrics.export({
  format: 'csv',
  metrics: ['api_latency', 'trade_fill_rate', 'error_rate'],
  period: '30d',
  outputPath: './metrics-export.csv',
});

// Export to Prometheus
const prometheusFormat = metrics.toPrometheus();

// Export to JSON
const jsonMetrics = await metrics.toJSON({
  period: '24h',
});

Generate Reports

const report = await metrics.generateReport({
  type: 'daily',
  include: ['summary', 'api', 'trades', 'errors'],
});

console.log('=== Daily Metrics Report ===');
console.log(`Date: ${report.date}`);
console.log(`\nSummary:`);
console.log(`  Uptime: ${report.summary.uptime}%`);
console.log(`  Total requests: ${report.summary.totalRequests}`);
console.log(`  Total trades: ${report.summary.totalTrades}`);
console.log(`  Error rate: ${report.summary.errorRate}%`);
console.log(`\nHighlights:`);
for (const highlight of report.highlights) {
  console.log(`  - ${highlight}`);
}

Real-time Streaming

// Stream metrics in real-time
const stream = metrics.stream(['cpu', 'memory', 'latency']);

stream.on('data', (data) => {
  console.log(`CPU: ${data.cpu}%, Memory: ${data.memory}MB, Latency: ${data.latency}ms`);
});

// Stop streaming
stream.stop();

---

Metric Types

Type	Description	Example
Counter	Monotonic increasing	trades_total
Gauge	Point-in-time value	active_positions
Histogram	Distribution	latency_ms
Timer	Duration measurement	order_execution_time

---

Built-in Metrics

Category	Metrics
System	cpu_usage, memory_used, uptime, connections
API	request_count, latency_p50/p95/p99, error_rate
WebSocket	messages_per_sec, lag, reconnections
Trades	orders_total, fill_rate, slippage, execution_time
Errors	error_count, error_rate_by_type

---

Best Practices

1. Monitor latency percentiles — P99 matters more than average
2. Set alerts proactively — Catch issues before users notice
3. Track custom metrics — Business-specific KPIs
4. Review daily reports — Spot trends early
5. Export for analysis — Use external tools for deep dives