可观测性与监控设置

可观测性和监控设置

概览

Soroban Registry 实现了包含 metrics、logs 和分布式 tracing 的全面可观测性。本文档涵盖监控设置、关键 metrics、日志配置和健康检查端点。

架构

┌─────────────┐
│ 应用程序    │──── Metrics ────▶ Prometheus ────▶ Grafana
│   Services  │                                       │
│  (API, etc) │──── Traces ─────▶ Jaeger        仪表盘
│             │                                       │
│             │──── Logs ───────▶ Loki/Promtail     告警
└─────────────┘                      │               │
                                     │               │
                                     ▼               ▼
                              日志聚合        AlertManager
                                 (ELK Stack)      │
                                                  │
                                                  ▼
                                        Slack / PagerDuty

Metrics（Prometheus）

暴露的 Metrics 端点

所有服务在以下地址暴露 Prometheus metrics：

GET /metrics
Content-Type: text/plain; version=0.0.4

配置

Prometheus Scrape 配置（observability/prometheus/prometheus.yml）：

global:
  scrape_interval: 15s
  evaluation_interval: 15s
  external_labels:
    app: soroban-registry

scrape_configs:
  - job_name: "soroban-registry-api"
    metrics_path: "/metrics"
    scrape_interval: 10s
    static_configs:
      - targets: ["api:3001"]
        labels:
          service: "soroban-registry"
          environment: "production"

  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: "node-exporter"
    static_configs:
      - targets: ["node-exporter:9100"]

要监控的关键 Metrics

1. HTTP Request Metrics

示例查询：

## 请求速率（每秒）
rate(soroban_http_requests_total[5m])

## P99 延迟
histogram_quantile(0.99, sum(rate(soroban_http_request_duration_seconds_bucket[5m])) by (le))

## 错误率（5xx 响应）
rate(soroban_http_requests_total{status=~"5.."}[5m]) / rate(soroban_http_requests_total[5m])

2. Verification Metrics

示例查询：

## Verification 队列积压
soroban_verification_queue_depth

## Verification 成功率
rate(soroban_verification_total{result="success"}[10m]) / rate(soroban_verification_total[10m])

## P99 verification 延迟
histogram_quantile(0.99, sum(rate(soroban_verification_latency_seconds_bucket[5m])) by (le))

3. Database Metrics

示例查询：

## 连接池利用率
soroban_db_connections_active / soroban_db_pool_size

## 慢查询率（>100ms）
rate(soroban_db_query_duration_seconds_count{quantile="0.99"}[5m])

## 查询错误率
rate(soroban_db_queries_total{result="error"}[5m]) / rate(soroban_db_queries_total[5m])

4. Cache Metrics

示例查询：

## Cache 命中率
rate(soroban_cache_hits_total[10m]) /
  (rate(soroban_cache_hits_total[10m]) + rate(soroban_cache_misses_total[10m]))

## Cache 内存使用量（MB）
soroban_cache_size_bytes / 1024 / 1024

5. Rate Limiting Metrics

示例查询：

## 每分钟 rate limit 违规次数
rate(soroban_rate_limit_exceeded_total[1m]) * 60

## 受 rate limit 影响最严重的 IP
topk(10, sum by (ip) (rate(soroban_rate_limit_exceeded_total[5m])))

6. Indexer Metrics

示例查询：

## Indexer 延迟
soroban_indexer_lag_seconds

## RPC 错误率
rate(soroban_indexer_errors_total{type="rpc_error"}[5m])

7. SLO / SLI Metrics

示例查询：

## 可用性 SLI（99.9% 目标）
soroban_sli_availability > 0.999

## 剩余 error budget
1 - soroban_slo_burn_rate{slo="availability"}

日志

结构化 JSON 日志

所有服务都会输出结构化 JSON 日志，便于解析和聚合：

{
  "timestamp": "2026-02-24T12:34:56.789Z",
  "level": "INFO",
  "message": "Contract verification completed",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "contract_id": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
  "duration_ms": 245,
  "result": "success",
  "service": "verifier",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7"
}

日志级别

使用 Loki 进行日志聚合

Promtail 配置（observability/loki/promtail-config.yml）：

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: soroban-registry
    static_configs:
      - targets:
          - localhost
        labels:
          job: soroban-api
          __path__: /var/log/soroban/*.log
    pipeline_stages:
      - json:
          expressions:
            level: level
            timestamp: timestamp
            correlation_id: correlation_id
            service: service
      - labels:
          level:
          service:
      - timestamp:
          source: timestamp
          format: RFC3339Nano

LogQL 查询：

## 最近一小时内的所有错误
{service="soroban-api"} |= "ERROR" | json

## 慢请求（>500ms）
{service="soroban-api"} | json | duration_ms > 500

## 特定 contract 的错误
{service="verifier"} | json | contract_id="CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC" |= "ERROR"

## Rate

>- 原文链接： [github.com/ALIPHATICHYD/...](https://github.com/ALIPHATICHYD/Soroban-Registry/blob/main/docs/OBSERVABILITY.md)
>- 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～