Aller au contenu principal

G-05 Métriques

Brique G de la plateforme Enterprise AI. Technologie : Prometheus (kube-prometheus-stack), ServiceMonitors, règles d'enregistrement (recording rules). Version anglaise : ../../en/bricks/G-05-metrics.md.

Rôle et responsabilités​

  • Collecter les métriques RED de chaque service, les métriques GPU (DCGM), profondeurs de file, taux de consommation des SLO.

Position et interactions​

  • Chemin d'exécution : collecte par scrape.
  • Le Control Plane expose /metrics ; les recording rules alimentent les écrans du portail (G-07) et Alertmanager (G-08) ; KEDA lit les métriques de file (H-05).

Part open source et part développée​

  • Open source réutilisé : Prometheus, kube-state-metrics, node-exporter, DCGM exporter.
  • Développé dans la plateforme : Catalogue de métriques eai_* avec cardinalité de labels bornée (pas d'id utilisateur en label).

Modèle de données​

Tables du Control Plane (schéma eai) : eai.gpu_samples.

Chaque table de tenant a tenant_id uuid NOT NULL et une politique de sécurité au niveau des lignes sur current_setting('app.tenant_id', true)::uuid. ClickHouse usage_events est la réplique analytique de eai.usage_events (ReplacingMergeTree par event_id).

Contrat : contracts/v1/usage-event.schema.json (schema_version 1.0). L'usage est toujours remonté avec contracts/v1/usage-event.schema.json, l'audit avec contracts/v1/audit-event.schema.json.

Endpoints d'API​

MéthodeChemin
GET/v1/telemetry/overview
GET/readyz

GET /v1/telemetry/overview​

Réponse :

{
  "window": "24h",
  "requests": 18234,
  "error_rate": 0.012,
  "p95_latency_ms": 2140,
  "tokens": {
    "input": 9120044,
    "output": 1203400
  },
  "top_models": [
    {
      "model_id": "gpt-4o-mini",
      "share": 0.61
    }
  ]
}

GET /readyz​

Réponse :

{
  "status": "ready",
  "checks": {
    "postgres": "ok",
    "redis": "ok",
    "clickhouse": "ok"
  }
}

Métriques SLO​

eai_http_request_duration_seconds{method,route} et eai_http_requests_total alimentent les règles d'enregistrement deploy/observability/slo/eai-slo-rules.yaml (p50, p95, p99, disponibilité, budget restant) et l'écran SLO et budgets d'erreur du portail (/observability/slo). Voir docs/operations/slo.md.

Exemples SDK​

Python​

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_live_xxx", tenant="acme", locale="fr")
client.telemetry.overview(days=1)
client.system.readyz()

TypeScript​

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY, tenant: "acme", locale: "fr" });
await client.telemetry.overview({ days: 1 });
await client.meta.ready();

Java​

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .tenant("acme")
    .locale(Locale.FRENCH)
    .build();
client.telemetry().overview(Map.of("days", 1));
client.meta().ready();

Go​

client, err := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")), eai.WithTenant("acme"), eai.WithLocale("fr"))
if err != nil { log.Fatal(err) }
ctx := context.Background()
_, err = client.Telemetry.Overview(ctx, eai.WithQuery(map[string]string{"days": "1"}))
_, err = client.Meta.Ready(ctx, nil)

Configuration​

Variables d'environnement : EAI_OTEL_ENABLED, EAI_OTEL_EXPORTER_OTLP_ENDPOINT (OTLP/HTTP, port 4318 du collecteur, chemin /v1/traces ajouté), EAI_OTEL_EXPORTER_OTLP_CERTIFICATE (CA interne pour un collecteur https), EAI_LOG_LEVEL (DEBUG, INFO, WARNING, ERROR ou CRITICAL).

Traces : avec EAI_OTEL_ENABLED=1, le Control Plane crée un TracerProvider (service.name, service.version, deployment.environment), instrumente FastAPI (hors /metrics, /healthz, /readyz) et ajoute des spans sans donnée personnelle : authentification, politique, DLP, routage, appel provider, outil, MCP, RAG et multimodal. Si un paquet OpenTelemetry manque, l'API refuse de démarrer. Le traceparent est propagé aux appels sortants et le trace_id figure dans les événements d'audit.

Journaux : une ligne JSON par événement sur stdout (timestamp, level, logger, trace_id, span_id, request_id) pour l'API, le worker et le media worker. La ligne d'accès eai.access ne contient jamais la query string, Authorization, les cookies ni les corps.

Clés de valeurs Helm (deploy/helm/enterprise-ai/values.yaml) : global.monitoring.serviceMonitor, controlPlane.port.

Sécurité​

  • /metrics accessible uniquement depuis le namespace de monitoring (politique Cilium).
  • Tenant déduit de l'identifiant d'accès, jamais du corps ; sécurité au niveau des lignes PostgreSQL sur chaque table de tenant.
  • Chaque mutation et décision de politique écrit un événement d'audit chaîné par hachage (G-11).
  • Les erreurs utilisent l'enveloppe standard avec message_i18n en et fr.

Observabilité​

  • Métriques propres de Prometheus et taille de la TSDB.
  • traceparent W3C propagé, X-Request-Id renvoyé, les spans portent eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

Unités FinOps​

  • Les métriques sont des signaux d'exploitation, pas des factures ; la FinOps utilise les gpu_samples issus de DCGM via H-04.

Modes de défaillance et résilience​

  • Cardinalité trop élevée -> le relabeling supprime le label et une alerte se déclenche.

Adoption autonome​

Un Prometheus existant peut fédérer les métriques eai_*.

Tests d'acceptation​

  1. eai_http_requests_total et eai_gateway_tokens_total présents après un appel gateway.

Feuille de route d'implémentation