> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lasso.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics API

> Retrieve detailed performance metrics for blockchain chains

## Overview

The metrics API provides comprehensive performance data for a specific blockchain chain, including provider statistics, RPC method performance, and system resource usage.

## Endpoint

```
GET /api/metrics/:chain
```

### Path Parameters

<ParamField path="chain" type="string" required>
  The chain identifier (e.g., `ethereum`, `polygon`, `arbitrum`)
</ParamField>

## Response

<ResponseField name="chain" type="string" required>
  The chain identifier
</ResponseField>

<ResponseField name="chain_id" type="integer" required>
  The numeric chain ID (e.g., 1 for Ethereum)
</ResponseField>

<ResponseField name="timestamp" type="integer" required>
  Unix timestamp in milliseconds when metrics were collected
</ResponseField>

<ResponseField name="system_metrics" type="object" required>
  VM and system resource utilization

  <Expandable title="system_metrics properties">
    <ResponseField name="memory_mb" type="number">
      Total memory usage in megabytes
    </ResponseField>

    <ResponseField name="cpu_percent" type="number">
      CPU utilization percentage
    </ResponseField>

    <ResponseField name="process_count" type="integer">
      Number of active Erlang processes
    </ResponseField>

    <ResponseField name="run_queue" type="integer">
      Number of processes waiting to run
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chain_performance" type="object" required>
  Aggregated performance metrics for the chain

  <Expandable title="chain_performance properties">
    <ResponseField name="total_calls" type="integer">
      Total number of RPC calls processed
    </ResponseField>

    <ResponseField name="success_rate" type="number">
      Success rate percentage (0-100)
    </ResponseField>

    <ResponseField name="p50_latency" type="number">
      50th percentile latency in milliseconds
    </ResponseField>

    <ResponseField name="p95_latency" type="number">
      95th percentile latency in milliseconds
    </ResponseField>

    <ResponseField name="failovers_last_minute" type="integer">
      Number of failover events in the last minute
    </ResponseField>

    <ResponseField name="connected_providers" type="integer">
      Number of providers currently connected and healthy
    </ResponseField>

    <ResponseField name="total_providers" type="integer">
      Total number of configured providers for this chain
    </ResponseField>

    <ResponseField name="recent_activity" type="integer">
      Number of recent RPC calls in the activity buffer
    </ResponseField>

    <ResponseField name="rpc_calls_per_second" type="number">
      Current RPC request rate
    </ResponseField>

    <ResponseField name="error_rate_percent" type="number">
      Error rate percentage (0-100)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="providers" type="array" required>
  Performance metrics for each provider

  <Expandable title="provider properties">
    <ResponseField name="id" type="string">
      Provider identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable provider name
    </ResponseField>

    <ResponseField name="score" type="number">
      Provider performance score (0-100)
    </ResponseField>

    <ResponseField name="success_rate" type="number">
      Success rate percentage for this provider
    </ResponseField>

    <ResponseField name="total_calls" type="integer">
      Total calls routed to this provider
    </ResponseField>

    <ResponseField name="avg_latency_ms" type="number">
      Average response latency in milliseconds
    </ResponseField>

    <ResponseField name="calls_last_minute" type="integer">
      Number of calls in the last minute
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rpc_methods" type="array" required>
  List of RPC methods that have been called on this chain
</ResponseField>

<ResponseField name="rpc_performance_by_provider" type="array">
  Detailed RPC method performance organized by provider

  <Expandable title="structure">
    <ResponseField name="provider_id" type="string">
      Provider identifier
    </ResponseField>

    <ResponseField name="provider_name" type="string">
      Provider name
    </ResponseField>

    <ResponseField name="methods" type="array">
      Performance data for each RPC method on this provider

      <Expandable title="method properties">
        <ResponseField name="method" type="string">
          RPC method name (e.g., `eth_blockNumber`)
        </ResponseField>

        <ResponseField name="avg_latency_ms" type="number">
          Average latency in milliseconds
        </ResponseField>

        <ResponseField name="p50_latency_ms" type="number">
          50th percentile latency
        </ResponseField>

        <ResponseField name="p90_latency_ms" type="number">
          90th percentile latency
        </ResponseField>

        <ResponseField name="p95_latency_ms" type="number">
          95th percentile latency
        </ResponseField>

        <ResponseField name="p99_latency_ms" type="number">
          99th percentile latency
        </ResponseField>

        <ResponseField name="success_rate" type="number">
          Success rate for this method (0-1)
        </ResponseField>

        <ResponseField name="total_calls" type="integer">
          Number of calls to this method
        </ResponseField>

        <ResponseField name="last_updated" type="integer">
          Timestamp of last update
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rpc_performance_by_method" type="array">
  Detailed RPC method performance organized by method

  <Expandable title="structure">
    <ResponseField name="method" type="string">
      RPC method name
    </ResponseField>

    <ResponseField name="providers" type="array">
      Performance data for each provider supporting this method (same structure as methods above, with added `provider_id` and `provider_name`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="last_updated" type="integer" required>
  Timestamp when metrics were last updated
</ResponseField>

## Response Example

```json theme={null}
{
  "chain": "ethereum",
  "chain_id": 1,
  "timestamp": 1709502330123,
  "system_metrics": {
    "memory_mb": 245.6,
    "cpu_percent": 12.4,
    "process_count": 542,
    "run_queue": 0
  },
  "chain_performance": {
    "total_calls": 15234,
    "success_rate": 99.2,
    "p50_latency": 125.5,
    "p95_latency": 342.1,
    "failovers_last_minute": 2,
    "connected_providers": 3,
    "total_providers": 3,
    "recent_activity": 45,
    "rpc_calls_per_second": 12.5,
    "error_rate_percent": 0.8
  },
  "providers": [
    {
      "id": "alchemy-eth-mainnet",
      "name": "Alchemy",
      "score": 95.6,
      "success_rate": 99.8,
      "total_calls": 8432,
      "avg_latency_ms": 115.3,
      "calls_last_minute": 28
    },
    {
      "id": "infura-eth-mainnet",
      "name": "Infura",
      "score": 92.1,
      "success_rate": 99.1,
      "total_calls": 4521,
      "avg_latency_ms": 145.8,
      "calls_last_minute": 12
    },
    {
      "id": "quicknode-eth-mainnet",
      "name": "QuickNode",
      "score": 94.3,
      "success_rate": 99.5,
      "total_calls": 2281,
      "avg_latency_ms": 128.2,
      "calls_last_minute": 5
    }
  ],
  "rpc_methods": [
    "eth_blockNumber",
    "eth_getBlockByNumber",
    "eth_call",
    "eth_getLogs"
  ],
  "rpc_performance_by_provider": [
    {
      "provider_id": "alchemy-eth-mainnet",
      "provider_name": "Alchemy",
      "methods": [
        {
          "method": "eth_blockNumber",
          "avg_latency_ms": 45.2,
          "p50_latency_ms": 42.0,
          "p90_latency_ms": 68.5,
          "p95_latency_ms": 85.3,
          "p99_latency_ms": 124.7,
          "success_rate": 0.998,
          "total_calls": 3421,
          "last_updated": 1709502330100
        }
      ]
    }
  ],
  "rpc_performance_by_method": [
    {
      "method": "eth_blockNumber",
      "providers": [
        {
          "provider_id": "alchemy-eth-mainnet",
          "provider_name": "Alchemy",
          "avg_latency_ms": 45.2,
          "p50_latency_ms": 42.0,
          "p90_latency_ms": 68.5,
          "p95_latency_ms": 85.3,
          "p99_latency_ms": 124.7,
          "success_rate": 0.998,
          "total_calls": 3421,
          "last_updated": 1709502330100
        }
      ]
    }
  ],
  "last_updated": 1709502330100
}
```

## Error Responses

### Chain Not Found

```json theme={null}
{
  "error": "Chain not found",
  "chain": "invalid-chain",
  "available_chains": ["ethereum", "polygon", "arbitrum"]
}
```

**HTTP Status**: `404 Not Found`

### Missing Chain Parameter

```json theme={null}
{
  "error": "Chain parameter required",
  "usage": "/api/metrics/{chain_name}",
  "available_chains": ["ethereum", "polygon", "arbitrum"]
}
```

**HTTP Status**: `400 Bad Request`

## Use Cases

### Monitor Chain Performance

Track overall performance metrics for a blockchain:

```bash theme={null}
curl http://localhost:4000/api/metrics/ethereum
```

### Provider Performance Comparison

Compare performance across different RPC providers:

```bash theme={null}
# Get provider rankings
curl -s http://localhost:4000/api/metrics/ethereum | \
  jq '.providers | sort_by(-.score) | .[] | {name, score, success_rate, avg_latency_ms}'
```

### RPC Method Analysis

Analyze performance of specific RPC methods:

```bash theme={null}
# Check eth_getLogs performance across providers
curl -s http://localhost:4000/api/metrics/ethereum | \
  jq '.rpc_performance_by_method[] | select(.method=="eth_getLogs")'
```

### System Resource Monitoring

Monitor system resource usage:

```bash theme={null}
# Alert if memory usage is high
memory_mb=$(curl -s http://localhost:4000/api/metrics/ethereum | jq '.system_metrics.memory_mb')

if (( $(echo "$memory_mb > 1000" | bc -l) )); then
  echo "Warning: High memory usage: ${memory_mb}MB"
fi
```

### Performance Dashboards

Integrate with monitoring tools like Grafana, Datadog, or Prometheus:

```javascript theme={null}
// Fetch metrics periodically
setInterval(async () => {
  const response = await fetch('http://localhost:4000/api/metrics/ethereum');
  const metrics = await response.json();
  
  // Send to monitoring backend
  await sendToDatadog({
    'lasso.chain.success_rate': metrics.chain_performance.success_rate,
    'lasso.chain.p95_latency': metrics.chain_performance.p95_latency,
    'lasso.chain.rps': metrics.chain_performance.rpc_calls_per_second,
    'lasso.system.memory_mb': metrics.system_metrics.memory_mb,
    'lasso.system.cpu_percent': metrics.system_metrics.cpu_percent
  });
}, 30000); // Every 30 seconds
```

## Notes

* Metrics are updated in real-time based on actual RPC traffic
* Performance percentiles (p50, p95, etc.) are calculated over a sliding window
* Provider scores are calculated based on a combination of latency, success rate, and reliability
* The `rpc_performance_by_provider` and `rpc_performance_by_method` fields provide the same data organized differently for convenience
* System metrics reflect the Erlang VM's resource usage, not the underlying host system