Surveillance

bext expose un point de terminaison de métriques compatible Prometheus et un point de terminaison de vérification de l'état, vous offrant une observabilité complète avec votre pile de surveillance existante.

Configuration#

# bext.config.toml
[metrics]
enabled = true                   # expose /__bext/metrics
path = "/__bext/metrics"         # customize the endpoint path
include_process = true           # include process_* metrics (RSS, CPU, FDs)

[health]
enabled = true                   # expose /__bext/health
path = "/__bext/health"          # customize the endpoint path
include_details = true           # include component-level health in response

Les deux points de terminaison sont exclus des journaux d’accès et de la limitation de débit par défaut.

Point de terminaison des métriques#

Grattez /__bext/metrics avec Prometheus. La réponse est dans le format d'exposition standard de Prometheus.

Métriques disponibles#

Métriques HTTP

Métriques de cache

Métriques de piscine SSR / V8

Métriques du plug-in

Métriques de processus (lorsque include_process = true)

Exemple de configuration de Prometheus Scrape#

# prometheus.yml
scrape_configs:
  - job_name: bext
    scrape_interval: 15s
    static_configs:
      - targets: ["bext-host:3061"]
    metrics_path: /__bext/metrics

Point de terminaison du bilan de santé#

GET /__bext/health renvoie un rapport d'état JSON :

{
  "status": "healthy",
  "uptime_secs": 86412,
  "checks": {
    "render_pool": "ok",
    "isr_cache": "ok",
    "redis": "ok",
    "tls_certs": "ok",
    "disk_space": "ok"
  }
}

Renvoie 200 lorsqu'il est sain, 503 lorsqu'un composant est signalé dégradé. Utilisez-le pour les vérifications de l’état de l’équilibreur de charge et les sondes d’activité Kubernetes.

Tableau de bord Grafana#

Un exemple JSON de tableau de bord Grafana est disponible dans le référentiel bext à l'adresse contrib/grafana-dashboard.json. Importez-le dans Grafana et définissez la source de données Prometheus.

Les panneaux clés comprennent :

• Taux de demande ( rate(http_requests_total[5m]) )
• Latence P50/P95/P99 ( histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) )
• Taux d'erreur ( rate(http_requests_total{status=~"5.."}[5m]) )
• Taux de réussite du cache ( rate(cache_hits_total[5m]) / (rate(cache_hits_total[5m]) + rate(cache_misses_total[5m])) )
• V8 saturation de la piscine ( render_pool_active / render_pool_total )

Règles d'alerte#

Règles d'alerte Prometheus recommandées :

# alerts.yml
groups:
  - name: bext
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "bext error rate above 5%"

      - alert: HighLatency
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 1.0
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "bext P95 latency above 1 second"

      - alert: JscPoolExhausted
        expr: render_pool_idle == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "All render workers busy — SSR requests are queuing"

      - alert: CacheHitRateLow
        expr: rate(cache_hits_total[10m]) / (rate(cache_hits_total[10m]) + rate(cache_misses_total[10m])) < 0.5
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Cache hit rate below 50% — check ISR TTLs and cache capacity"

OpenTelemetry#

bext exporte des traces et des métriques via OTLP :

# bext.config.toml
[telemetry]
otlp_endpoint = "http://otel-collector:4317"
otlp_protocol = "grpc"          # grpc | http
sample_rate = 0.1                # sample 10% of traces
service_name = "bext-production"

Chaque demande crée une étendue avec request_id, path, status et duration. Les spans enfants sont créés pour le rendu SSR, la recherche de cache, les hooks de plugin et les appels de proxy en amont, vous offrant ainsi une trace distribuée complète pour chaque requête.

En rapport#

• Enregistrement — champs de journal JSON structurés et transfert vers Loki/ELK/Datadog
• Dépannage — commandes de diagnostic et correctifs de problèmes par zone
• Performance — cadre budgétaire, magasin d'historique et porte de régression
• Mise à l'échelle — point de terminaison de vérification de l'état, Redis L2 et réglage du nombre de travailleurs
• Architecture : pool de rendu V8 – rendre la topologie des nœuds de calcul et le comportement du pool