Référence de configuration

perf-sentinel se configure via un fichier .perf-sentinel.toml. Tous les champs sont optionnels et ont des valeurs par défaut raisonnables.

<img alt="Vue d'ensemble des commandes CLI" src="https://raw.githubusercontent.com/robintra/perf-sentinel/main/docs/diagrams/svg/cli-commands.svg">

Sommaire

• Fragments de configuration : chargement multi-fichier déterministe.
• Sous-commandes : quelles sous-commandes lisent .perf-sentinel.toml.
• Sections : référence complète par section ([thresholds], [detection], [green], [daemon], [reporting]).
• Configuration minimale : le .perf-sentinel.toml le plus court utile.
• Exemple de configuration complète : chaque section peuplée avec des valeurs d'exemple.
• Migration depuis 0.5.x : les 8 clés top-level legacy retirées en 0.6.0 et comment migrer.
• Variables d'environnement : quelles variables d'environnement surchargent les valeurs du fichier de config.

Fragments de configuration

perf-sentinel charge les documents TOML du répertoire .perf-sentinel.d/ placé à côté de la configuration principale, puis charge .perf-sentinel.toml en dernier. Cette règle vaut aussi avec --config chemin/vers/custom.toml : les fragments viennent de chemin/vers/.perf-sentinel.d/ et custom.toml reste la surcharge finale. Le fichier principal est facultatif uniquement sans option --config. Les valeurs par défaut sont utilisées uniquement si ni le fichier principal implicite ni aucun fragment n'existe. Un fichier illisible ou une erreur de syntaxe TOML individuelle arrête la commande avec le code 75. Après application des surcharges, la configuration fusionnée doit aussi passer la désérialisation typée et la validation, sinon la commande s'arrête.

Le nom d'un fragment doit suivre NN-nom-minuscule.toml, avec une priorité unique NN comprise entre 00 et 99. Les fichiers sont chargés par priorité croissante. Une priorité dupliquée, une majuscule ou un séparateur ambigu est refusé. Les fichiers qui ne se terminent pas par .toml sont ignorés.

Lorsque les deux valeurs sont des tables, elles fusionnent récursivement. Toute autre valeur plus tardive remplace la précédente à la même clé. Le document fusionné final doit toujours respecter le schéma de configuration typé. Les exemples réservent ces plages :

Les fragments prêts à copier dans examples/ conservent leur priorité dans leur nom. Gardez ces noms en les copiant dans .perf-sentinel.d/ : 30-green-alumet.toml, 31-green-cloud.toml, 32-green-scaphandre.toml, 33-green-kepler.toml, 34-green-redfish.toml et 40-green-electricity-maps.toml. 60-daemon-docker.toml est une configuration principale autonome pour les topologies Compose collector et sharded. Montez-le comme .perf-sentinel.toml, puis placez uniquement les fragments GreenOps optionnels dans le répertoire frère .perf-sentinel.d/.

Sous-commandes

Sections

[thresholds]

Seuils du quality gate. Le quality gate échoue si une règle est violée.

[detection]

Paramètres des algorithmes de détection.

sanitizer_aware_classification

Les agents OpenTelemetry et les drivers de base de données activent par défaut la sanitization des instructions SQL pour éviter de laisser fuir des PII dans les attributs de trace. Le style de placeholder dépend de la stack : les agents JDBC produisent ?, les drivers PostgreSQL natifs (pgx, asyncpg, sqlx) produisent $1/$2 (normalisés en $?), les drivers Python DB-API produisent %s, les drivers .NET produisent @p0/@Name, et Oracle/SQLAlchemy produisent :name. Dans tous les cas, les spans arrivent dans perf-sentinel avec le même template et aucun paramètre extractible. La règle standard de paramètres distincts rejette donc le groupe et le détecteur de redondance le récupère sous l'étiquette redundant_sql au lieu de n_plus_one_sql. Ce paramètre contrôle l'heuristique qui restaure la classification correcte :

• "auto" (défaut) : émet n_plus_one_sql quand soit un marqueur ORM est présent dans les instrumentation_scopes des spans (Spring Data, Hibernate, EF Core, SQLAlchemy, ActiveRecord, GORM, Prisma, Diesel, Laravel/Eloquent, Doctrine, ...) soit la variance des durées par span est suffisante pour indiquer des accès à des lignes distinctes. Sinon, le groupe reste à la charge du détecteur de redondance. Meilleur rappel sur les stacks production Spring Data, EF Core et similaires.
• "strict" : reclassifie uniquement quand un signal primaire (marqueur ORM, nombre d'occurrences >= 3 x n_plus_one_min_occurrences, ou siblings séquentiels) se déclenche conjointement avec un signal corroboratif (variance temporelle élevée ou nombre d'occurrences élevé). Préserve la précision de redundant_sql sur les requêtes identiques de compte modéré (boucles de polling legacy, lookups de config non mémoïsés, typiquement 5-10 appels par requête). Au-dessus de la barre (par défaut 15), tout groupe sanitisé se déclenche quel que soit le scope ORM, les siblings séquentiels ou la variance, sous la garde looks_sanitized. À utiliser quand les findings redundant_sql sont un signal exploitable qui ne doit pas être absorbé silencieusement par n_plus_one_sql. Le laboratoire de simulation fait tourner toutes ses stacks ainsi, parce que sous auto un marqueur de scope ORM suffit à reclassifier en N+1 une répétition de la même requête servie par un cache. Ce changement de verdict ne vaut que pour les comptes modérés, la barre de haute occurrence ci-dessus se déclenchant aussi sous strict.
• "always" : reclassifie tout groupe sanitisé qui atteint n_plus_one_min_occurrences spans en n_plus_one_sql. Plus agressif, peut requalifier une vraie redondance à un seul paramètre.
• "never" : désactive complètement l'heuristique et retombe sur le check strict distinct_params.

Les findings reclassifiés par l'heuristique (sous "auto", "strict" ou "always") portent classification_method = "sanitizer_heuristic" dans leur représentation JSON, ce qui permet à un opérateur de repérer où elle se déclenche. Les findings produits par la règle standard omettent ce champ.

[green]

Voir aussi. L'introduction énergie et SCI dans la doc méthodologie définit SCI v1.0 (termes E + I + M), RAPL, Scaphandre, SPECpower, Boavizta et l'API Electricity Maps utilisés par les sections de config ci-dessous. À lire une fois si l'un des termes ne vous est pas familier.

Configuration du scoring GreenOps alignée sur SCI v1.0 (termes opérationnel + embodié, intervalles de confiance, multi-région).

[green.service_regions]

Surcharges de région par service utilisées quand cloud.region OTel est absent des spans (ex. ingestion Jaeger / Zipkin). Mappe nom de service → clé de région.

[green]
default_region = "eu-west-3"
embodied_carbon_per_request_gco2 = 0.001

[green.service_regions]
"order-svc" = "us-east-1"
"chat-svc"  = "ap-southeast-1"

Chaîne de résolution de région

Pour chaque span, l'étape de scoring carbone résout la région effective dans cet ordre (premier match gagne) :

1. event.cloud_region : depuis l'attribut de ressource OTel cloud.region (ou attribut de span en fallback). Le plus autoritatif.
2. [green.service_regions][event.service] : surcharge config par service.
3. [green] default_region : fallback global.

Les ops I/O sans région résolvable atterrissent dans un bucket synthétique "unknown" (zéro CO₂ opérationnel ; la ligne apparaît dans regions[] pour la visibilité). Le carbone embodié est tout de même émis car les émissions de fabrication matérielle sont indépendantes de la région. La cardinalité des régions est plafonnée à 256 buckets distincts ; le surplus tombe dans le bucket unknown pour éviter l'épuisement mémoire en cas d'ingestion mal configurée.

Forme de sortie

Quand le scoring vert est activé et qu'au moins un événement est analysé, le green_summary du rapport JSON inclut :

• co2 : objet structuré { total, avoidable, operational_gco2, embodied_gco2 }. total et avoidable sont tous deux { low, mid, high, model, methodology } avec une incertitude multiplicative 2× (low = mid/2, high = mid×2). Le tag methodology distingue total ("sci_v1_numerator+transport" : (E × I) + M + T sommé sur les traces, y compris quand T vaut zéro) de avoidable ("sci_v1_operational_ratio" : ratio global aveugle à la région, exclut l'embodié et le transport). Les rapports historiques peuvent porter "sci_v1_numerator". Valeurs model, le plus précis gagne : "electricity_maps_api" → "scaphandre_rapl" → "kepler_ebpf" → "redfish_bmc" → "cloud_specpower" → "io_proxy_v3" → "io_proxy_v2" → "io_proxy_v1". Quand des facteurs de calibration sont actifs sur les modèles proxy, +cal est ajouté (ex. "io_proxy_v2+cal"). Le suffixe +cal ne s'applique jamais à un tag mesuré.
• regions[] : breakdown par région avec { region, grid_intensity_gco2_kwh, pue, io_ops, co2_gco2, intensity_source }, trié par co2_gco2 décroissant (régions à plus fort impact en premier) avec tiebreak alphabétique. intensity_source vaut "annual", "hourly", "monthly_hourly" ou "real_time" (API Electricity Maps) selon quelle source d'intensité carbone a été utilisée pour la région.

Les données d'intensité carbone sont embarquées dans le binaire (aucun appel réseau sortant). Voir 05 · GreenOps & carbon pour la formule complète et la méthodologie et Limites pour le disclaimer directionnel / non-réglementaire.

Profils horaires fournis par l'utilisateur

Mettre [green] hourly_profiles_file vers un fichier JSON pour fournir vos propres profils horaires. C'est utile pour les opérateurs de datacenter avec leurs propres PPAs (power purchase agreements) ou pour surcharger les données embarquées avec des mesures locales.

{
  "profiles": {
    "my-datacenter": {
      "type": "flat_year",
      "hours": [45.0, 44.0, 43.0, "... 24 valeurs au total ..."]
    },
    "eu-west-3": {
      "type": "monthly",
      "months": [
        [50.0, 49.0, "... 24 valeurs pour janvier ..."],
        ["... 11 mois supplémentaires ..."]
      ]
    }
  }
}

Les profils fournis par l'utilisateur ont priorité sur les profils embarqués pour la même clé de région. Validation au chargement de la config : chaque flat_year doit contenir exactement 24 valeurs, chaque monthly doit contenir exactement 12 tableaux de 24 valeurs. Toutes les valeurs doivent être finies et non-négatives. Si la clé de région existe dans la table carbone embarquée, un warning est loggé quand la moyenne du profil s'écarte de plus de 5% de la valeur annuelle, mais le profil est quand même accepté.

Alias de régions pour les profils horaires

Les alias de code pays et les synonymes de fournisseurs cloud résolvent vers le même profil horaire. Par exemple, "fr", "francecentral" et "europe-west9" mappent tous vers le profil eu-west-3 (France). Mappings notables :

• "us", "eastus" → us-east-1 (US-East, la région de déploiement US la plus courante)
• "westeurope", "nl" → eu-west-4 (Pays-Bas)
• "northeurope", "ie" → eu-west-1 (Irlande)
• "uksouth", "gb", "uk" → eu-west-2 (Royaume-Uni)
• "westus2" → us-west-2 (Oregon)

La table complète des alias se trouve dans score/carbon_profiles.rs. Si votre clé de région n'est pas aliasée, la valeur annuelle plate de la table carbone principale est utilisée.

Tous les backends d'énergie et d'intensité réseau sont réservés au daemon. [green.alumet], [green.scaphandre], [green.kepler], [green.redfish], [green.cloud], [green.broker_static] et [green.electricity_maps] sont interrogés par le daemon watch et par rien d'autre. Un run batch analyze ou report ne démarre aucun scraper : il calcule donc avec l'estimation proxy I/O sur les données d'intensité embarquées quoi que disent ces sections, et il émet un avertissement nommant les sections qu'il a dû ignorer. Attribuer une puissance mesurée maintenant à des traces enregistrées plus tôt produirait un chiffre faux plutôt qu'un chiffre absent, d'où l'absence de scraping en batch.

[green.scaphandre] (optionnel, opt-in)

Intégration opt-in avec Scaphandre pour la mesure énergétique par processus sur les hôtes Linux avec support Intel RAPL. Quand cette section est configurée, le daemon watch lance une tâche de fond qui scrape l'endpoint Prometheus de Scaphandre toutes les scrape_interval_secs secondes et utilise les lectures de puissance mesurées pour remplacer la constante ENERGY_PER_IO_OP_KWH fixe pour chaque service mappé.

Préférez [green.alumet] pour les nouveaux déploiements. Les deux intégrations lisent les mêmes compteurs RAPL, mais l'échantillonnage d'Alumet est mesurablement moins erroné, comme le caractérisent ses propres auteurs dans Dissecting the software-based measurement of CPU energy consumption (Raffin et al.), et il attribue par cgroup plutôt que par processus. Le support Scaphandre est conservé pour les déploiements existants, et alumet_rapl surclasse scaphandre_rapl dès que les deux alimentent le même service. Voir Limites.

Chaque entrée process_map est une table avec deux champs : exe_contains (obligatoire, sous-chaîne comparée au label exe de Scaphandre) et cmdline_contains (optionnel, sous-chaîne comparée au label cmdline). Quand cmdline_contains est défini, le matcher exige que les deux sous-chaînes soient présentes. Un seul processus Scaphandre doit matcher par entrée, sinon l'étape de scoring saute ce service pour le tick et émet un log warn nommant l'ambiguïté.

[green.scaphandre]
endpoint = "http://localhost:8080/metrics"
scrape_interval_secs = 5

[green.scaphandre.process_map."order-svc"]
exe_contains = "bin/java"
cmdline_contains = "order-svc.jar"

[green.scaphandre.process_map."chat-svc"]
exe_contains = "bin/java"
cmdline_contains = "chat-svc.jar"

[green.scaphandre.process_map."native-svc"]
exe_contains = "/opt/native-svc/bin/native-svc"

Pourquoi exe_contains ET cmdline_contains. Scaphandre émet exe comme chemin absolu du runtime (/usr/lib/jvm/.../bin/java, /usr/share/dotnet/dotnet). Plusieurs services co-localisés partageant un runtime (plusieurs JVMs, plusieurs assemblies .NET) collisionnent sur exe, et seul cmdline les distingue. Scaphandre concatène en plus argv sans séparateurs : java -jar /tmp/order-svc.jar apparaît comme cmdline="java-jar/tmp/order-svc.jar". Configurez cmdline_contains avec une sous-chaîne présente dans cette forme concaténée (par exemple le nom du jar ou de la dll), PAS avec une ligne de commande POSIX contenant des espaces.

Ignoré en mode batch analyze. Seul le daemon watch lance le scraper. La commande analyze utilise toujours le modèle proxy quelle que soit cette section.

Comportement de fallback. Quand l'endpoint est inaccessible, qu'un service n'est pas présent dans process_map ou qu'un service a eu zéro ops dans la fenêtre de scrape courante, l'étape de scoring retombe sur le modèle proxy pour ces spans. Le premier échec est logué en niveau warn ; les échecs suivants en debug pour éviter le spam. La jauge Prometheus perf_sentinel_scaphandre_last_scrape_age_seconds permet aux opérateurs de détecter un scraper bloqué.

Limites de précision (important). Scaphandre améliore le coefficient énergétique au niveau service mais ne donne PAS d'attribution par finding. RAPL est au niveau processus, pas au niveau span : deux findings dans le même processus pendant la même fenêtre de scrape partagent le même coefficient. Voir Limites pour la discussion complète.

[green.kepler] (optionnel, opt-in)

Intégration opt-in avec Kepler (projet CNCF sandbox) pour la mesure d'énergie par conteneur ou par processus via eBPF. Contrairement à Scaphandre, Kepler fonctionne sur ARM64 (Graviton, Ampere, Apple Silicon, Cobalt 100) avec une précision dégradée mais un signal réel. Une fois configuré, le daemon watch scrape l'endpoint Prometheus /metrics de Kepler, calcule le delta de joules par service par rapport au scrape précédent, et publie un coefficient mesuré par opération taggué kepler_ebpf.

[green.kepler]
endpoint = "http://kepler.kube-system.svc.cluster.local:9102/metrics"
scrape_interval_secs = 5
metric_kind = "container"

[green.kepler.service_mappings]
"order-svc" = "order-svc-deployment"
"chat-svc" = "chat"

Ignoré en mode batch analyze. Comme Scaphandre, seul watch lance le scraper.

Les compteurs partageant une valeur de label sont sommés. Un même nom de conteneur répété entre pods (ou un même comm partagé par plusieurs processus) produit plusieurs séries cumulatives sous une même valeur de mapping. Leurs compteurs sont sommés avant le calcul du delta par fenêtre, le coefficient les couvre donc ensemble.

Précédence par rapport à Scaphandre. Scaphandre RAPL surclasse Kepler eBPF sur x86_64 avec accès RAPL. L'intégration Kepler prend tout son sens sur ARM64 où Scaphandre est indisponible. Voir Limites pour les mises en garde sur la précision du modèle eBPF ARM (issue amont Kepler #1556).

Forme de déploiement en production. Kepler s'exécute en général comme DaemonSet Kubernetes, un pod par nœud. Le scraper actuel effectue un GET direct et la réponse doit exposer les séries Kepler elles-mêmes. L'endpoint /metrics d'un serveur Prometheus expose les métriques internes de Prometheus, pas les séries qu'il a scrapées. Pour un cluster multi-nœuds, exécutez un perf-sentinel par nœud ou fournissez un endpoint de fédération/proxy qui expose directement les séries Kepler agrégées au format d'exposition Prometheus. Le mode de requête PromQL natif est réservé à une version ultérieure.

[green.alumet] (optionnel, opt-in)

Intégration opt-in avec Alumet (INRIA/LIG, EUPL-1.2) pour l'énergie mesurée. Alumet est un framework de mesure modulaire : un plugin source (rapl, nvidia-nvml, ...) produit des relevés, des plugins de transformation optionnels les attribuent aux charges de travail, et un plugin de sortie les expose. perf-sentinel scrape la sortie prometheus-exporter. Une fois configuré, le démon watch publie un coefficient mesuré par opération étiqueté alumet_rapl, qui surclasse toutes les autres sources mesurées, Scaphandre compris.

Pourquoi metric_name et label_key n'ont pas de défaut. L'exporteur d'Alumet ajoute un prefix en tête et un suffix en fin (par défaut _alumet) à chaque nom de métrique, et la série par service est produite par une formule energy-attribution dont vous choisissez le nom. Aucun défaut ne serait correct pour tous les déploiements, et une mauvaise supposition ne scraperait rien. Lisez les noms sur votre propre endpoint :

curl -s http://localhost:9091/metrics | grep -i energy

Plusieurs lignes par service sont sommées. Le label_key d'Alumet est couramment partagé : un pod porte une ligne par domaine RAPL (package + dram), et label_key = "domain" sur un hôte bi-socket porte une ligne domain="package" par socket. Toutes les lignes partageant une valeur de label sont sommées, ce qui est la lecture physiquement correcte puisque l'énergie est additive (les lignes NaN ou négatives sont ignorées). Deux conséquences à configurer. Choisissez label_key de sorte que les lignes partageant une valeur soient bien celles que vous voulez additionner. Et assurez-vous que ces lignes ne se recouvrent pas : les domaines RAPL s'emboîtent (psys contient package, package contient pp0/pp1), donc une formule qui émet un domaine parent et son enfant pour un même label compte deux fois la part partagée. package plus dram se somme correctement, psys plus package non.

Pourquoi energy_interval_secs existe. C'est le champ à ne pas rater. L'exporteur d'Alumet publie chaque mesure comme une jauge Prometheus contenant la dernière valeur flushée, et rapl_consumed_energy est un CounterDiff : les joules brûlés pendant un poll_interval de la source, ni un compteur cumulatif ni une puissance. perf-sentinel divise par cet intervalle pour retrouver des watts. L'intervalle n'apparaît nulle part sur le fil, il doit donc être déclaré ici et correspondre à la configuration côté Alumet. Un écart met l'énergie et le carbone à une échelle linéairement fausse, en silence : déclarer 1.0 alors qu'Alumet échantillonne à 5s surestime l'énergie d'un facteur 5, sans aucun avertissement. Voir Limites. Le démon affiche la valeur utilisée dans la ligne de log Alumet scraper started.

Configuration Alumet correspondante. L'attribution par service demande trois plugins Alumet qui travaillent ensemble, rapl seul ne mesure que la machine entière et procfs n'identifie les processus que par PID :

# alumet-config.toml
[plugins.rapl]
poll_interval = "1s"          # <- energy_interval_secs de perf-sentinel doit valoir ceci

[plugins.k8s]
# découverte des pods, fournit les attributs `name` / `namespace`

[plugins.energy-attribution.formulas.attributed_energy_cpu]
expr = "cpu_energy * cpu_usage / 100.0"
ref = "cpu_energy"

[plugins.energy-attribution.formulas.attributed_energy_cpu.per_resource]
cpu_energy = { metric = "rapl_consumed_energy", resource_kind = "local_machine", domain = "package_total" }

[plugins.energy-attribution.formulas.attributed_energy_cpu.per_consumer]
cpu_usage = { metric = "cpu_percent", kind = "total" }

[plugins.prometheus-exporter]
port = 9091
suffix = "_alumet"            # <- d'où le nom de métrique en _alumet ci-dessous

Le côté perf-sentinel correspondant :

[green.alumet]
endpoint = "http://localhost:9091/metrics"
scrape_interval_secs = 5
metric_name = "attributed_energy_cpu_alumet"
label_key = "name"
energy_interval_secs = 1.0

[green.alumet.service_mappings]
"order-svc" = "order-svc-pod"
"chat-svc" = "chat-svc-pod"

Ignoré en mode batch analyze. Comme tous les backends d'énergie mesurée, seul watch lance le scraper.

Précédence. alumet_rapl est en tête de la chaîne mesurée, devant scaphandre_rapl. Les deux lisent RAPL, mais l'échantillonnage d'Alumet est mesurablement moins erroné et il attribue par cgroup plutôt que par processus. Faire tourner les deux sur le même service est supporté, Alumet gagne.

Pièges du packaging amont. Le .deb amont installe /etc/alumet/alumet-config.toml (avec des sections csv, procfs, perf, ...) et son wrapper alumet-agent pointe ALUMET_CONFIG dessus si la variable n'est pas déjà définie. Activer prometheus-exporter via --plugins fonctionne même si ce fichier n'a pas de section prometheus-exporter. L'agent remplit la section absente à partir des défauts du plugin (prefix "", suffix "_alumet", port 9091). Pour une config contrôlée plutôt que celle livrée, pointez ALUMET_CONFIG vers un chemin vierge pour que l'agent régénère les défauts de votre jeu de plugins, ou lancez config regen. En conteneur, le binaire packagé porte des file capabilities (cap_perfmon, cap_sys_nice, cap_sys_ptrace) : un docker run nu échoue en EPERM sans les --cap-add correspondants.

Le scraper seul ne met pas alumet_rapl dans le rapport. Déclarer [green.alumet] démarre le scraper (visible sur /api/energy), mais le coefficient mesuré n'atteint green_summary que quand le scoring green résout une région pour les spans ([green] default_region, [green.service_regions], ou un attribut de span cloud.region). Sans cela, per_service_energy_model continue d'afficher le tag proxy, ce qui se lit facilement comme une intégration Alumet cassée.

Alumet est pré-1.0 (v0.9.5 au moment de l'écriture). Les noms de métriques et la configuration des plugins peuvent changer d'une version à l'autre. Si un scrape cesse de correspondre après une montée de version d'Alumet, le démon avertit avec no samples matched the configured metric après trois ticks consécutifs.

[green.alumet.database] (optionnel)

Déclare une charge de base de données mesurée par Alumet. Une base n'émet pas de spans, elle ne peut donc jamais apparaître dans service_mappings (zéro op, le chemin des coefficients par op l'ignore). À la place, son énergie sur chaque fenêtre de scoring est multipliée par le ratio de gaspillage SQL (avoidable_sql_io_ops / total_sql_io_ops) et publiée dans green_summary.database_waste, un chiffre autonome exclu de energy_kwh, de co2 et de la divulgation publique. Voir Méthodologie pour la formule et Limites de précision Alumet pour la raison d'une borne basse.

[green.alumet.database]
label_value = "postgres-pod"   # valeur portée par label_key pour le cgroup de la base, texto
region = "eu-west-3"           # optionnel, active la conversion gCO2 (déclarée, pas inférée)

label_value est obligatoire, apparié exactement comme une valeur de service_mappings. region est optionnel et utilise les mêmes identifiants de région que [green.service_regions] : sans lui le gaspillage est publié en kWh seulement. Une base par configuration, déclarez le cgroup qui sert votre trafic SQL.

[green.alumet.broker] (optionnel)

Le jumeau messaging de la section ci-dessus. Déclare un broker de messages mesuré par Alumet : un broker n'émet pas de spans propres non plus, donc son énergie de fenêtre est multipliée par le ratio de gaspillage messaging (avoidable_messaging_io_ops / total_messaging_io_ops) et rapportée en green_summary.messaging_waste.

[green.alumet.broker]
label_value = "kafka-pod"      # valeur portée par label_key pour le cgroup du broker, telle quelle
region = "eu-west-3"           # optionnel, active la conversion gCO2

Un même cgroup ne peut pas alimenter deux figures : un label_value qui apparaît aussi dans service_mappings, ou qui correspond à la déclaration de base de données, est rejeté au chargement de la config. Exige un agent sur l'hôte du broker, donc inapplicable à un broker managé. Pour ceux-là, voir [green.broker_static].

[green.broker_static] (optionnel, opt-in)

Déclare un cluster de brokers provisionné, sans agent ni métrique. C'est la seule voie qui fonctionne pour un broker managé (Confluent Cloud, MSK, SQS, Pulsar managé), où aucun hôte n'est instrumentable.

[green.broker_static]
nodes = 3                      # nœuds de broker provisionnés, requis
instance_type = "m5.2xlarge"   # cherché dans la table SPECpower embarquée, requis
provider = "aws"               # optionnel : aws, gcp, azure ou generic (défaut)
region = "eu-west-3"           # optionnel, active la conversion gCO2

L'énergie vaut nodes × max_watts × durée de la fenêtre, suivant E(n) = n × P_max : les nœuds provisionnés multipliés par leur plafond de puissance. Trois propriétés à accepter avant de s'appuyer dessus :

• Le chiffre borne le calcul, pas la consommation murale. max_watts est la puissance à 100 % de CPU, tirée d'une table SPECpower qui couvre le CPU et la carte mère et exclut le stockage, le réseau et les pertes d'alimentation. Or ce sont eux qui dominent sur un broker : c'est donc un plafond sur les vCPU déclarés, pas sur ce que le cluster tire réellement de la prise. Un nœud Kafka limité par le stockage peut consommer plus que ce que ce chiffre rapporte.
• Il compte l'infrastructure provisionnée, pas consommée. Un cluster de trois nœuds est immobilisé qu'il tourne à 10 % ou à 60 %. Dans l'autre sens, une période sans trafic facture au plus une heure, donc un cluster majoritairement inactif est sous-compté.
• Le chiffre ne réagit à aucun changement applicatif. Grouper vos publications ne le fera pas bouger, puisque rien dedans ne dépend du trafic. Si vous voulez un chiffre qui répond à une remédiation, il faut la voie mesurée.

Un instance_type inconnu émet un avertissement et retombe sur un défaut fournisseur plutôt que d'échouer : le chiffre devient simplement plus grossier, et l'avertissement le dit. Un provider non reconnu est rejeté d'emblée, car il se résoudrait silencieusement aux watts génériques on-premise. Daemon uniquement, comme toute voie mesurée, puisqu'une durée de fenêtre est nécessaire. Quand cette section et [green.alumet.broker] sont toutes deux configurées, la mesure gagne. La précédence suit la série Alumet du broker, pas l'endpoint de scrape : un scrape qui répond sans porter le label_value déclaré ne mesure rien, la déclaration prend donc le relais au lieu d'être supprimée par un endpoint qui fonctionne. L'énergie déjà mise de côté par la série est livrée d'abord, et le delta qui arrive à la reprise est jeté une fois, puisqu'il remonte sur du temps déjà facturé par la déclaration.

[green.redfish] (optionnel, opt-in)

Intégration opt-in avec le standard BMC Redfish pour les lectures de puissance murale sur bare-metal. Contrairement à Scaphandre et Kepler (qui mesurent uniquement CPU + DRAM), Redfish lit la sortie réelle de l'alimentation via le BMC, donc la périphérie (NIC, disques, ventilateurs, pertes PSU) est incluse. Bare-metal uniquement, pas de VMs cloud.

Chaque table d'endpoint a deux champs : url (chaîne, URL Redfish complète chemin inclus) et schema (chaîne, soit "legacy_power" soit "environment_metrics"). Le schema sélectionne le pointeur JSON canonique utilisé par le parser, sans pointeur tapé par l'opérateur :

[green.redfish]
scrape_interval_secs = 60

[green.redfish.endpoints."chassis-legacy-1"]
url = "https://bmc-rack-01.dc.example/redfish/v1/Chassis/1/Power"
schema = "legacy_power"

[green.redfish.endpoints."chassis-modern-1"]
url = "https://bmc-rack-02.dc.example/redfish/v1/Chassis/1/EnvironmentMetrics"
schema = "environment_metrics"

[green.redfish.service_mappings]
"order-svc"  = "chassis-legacy-1"
"chat-svc"   = "chassis-legacy-1"
"ledger-svc" = "chassis-modern-1"

Quel schema choisir. /Power (legacy_power) a été déprécié par DMTF Release 2020.4 mais reste obligatoire sur les firmwares BMC en 2026, tous les fournisseurs en production l'exposent. /EnvironmentMetrics (environment_metrics) est le remplacement moderne qui expose PowerWatts.Reading directement, présent en parallèle de /Power pendant la transition. Choisir legacy_power sauf si la documentation BMC recommande explicitement EnvironmentMetrics. Une flotte mixte se déclare en donnant à chaque châssis le schema que son firmware sert.

Ignoré en mode batch analyze. Comme Scaphandre et Kepler, seul watch intègre Redfish.

Coefficient au niveau du nœud. Chaque service mappé au même châssis reçoit le même coefficient. Deux services sur un même châssis n'auront jamais de coefficients mesurés distincts via Redfish. Voir Limites pour la discussion complète de ce compromis et de la variance JSON entre fournisseurs.

[green.cloud] (optionnel, opt-in)

Estimation d'énergie cloud-native via utilisation CPU% + interpolation SPECpower. Quand cette section est configurée, le daemon watch scrape les métriques CPU% depuis un endpoint Prometheus/VictoriaMetrics et utilise une table de lookup embarquée (watts idle/max par type d'instance cloud) pour estimer la consommation énergétique par service. Supporte AWS, GCP, Azure et le matériel on-premise avec surcharge manuelle des watts.

Les entrées par service dans [green.cloud.services] supportent deux formes :

Instance cloud (lookup dans la table) :

[green.cloud]
prometheus_endpoint = "http://prometheus:9090"
scrape_interval_secs = 15
default_provider = "aws"

[green.cloud.services]
"account-svc" = { provider = "aws", instance_type = "m7i.4xlarge" }       # Sapphire Rapids
"api-asia" = { provider = "gcp", instance_type = "c4d-standard-8" }       # AMD Turin
"analytics" = { provider = "azure", instance_type = "Standard_D8s_v6" }   # Emerald Rapids
"ml-bench" = { provider = "aws", instance_type = "m8g.4xlarge" }          # Graviton 4

La liste complète des types couverts, avec leurs watts au repos et maximum, est dans Types d'instance. Familles d'instances modernes couvertes : AWS m7i/c7i/r7i, m7a/c7a, m6a/c6a, m7g/c7g, m8g/c8g, GCP c3, c3d, c4, c4d, n2d, t2a, Azure Standard_Dv6, Standard_Dadsv6, Standard_Dpsv6 (Cobalt 100), Standard_Ev6. Une entrée CPU-named bare-metal pour Sierra Forest (xeon-6780e, watts au niveau système, suppose pleine possession de la puce).

Watts manuels (on-premise ou matériel custom) :

[green.cloud.services]
"my-service" = { idle_watts = 45, max_watts = 120 }

Ignoré en mode analyze batch. Seul le daemon watch lance le scraper Prometheus.

Comportement de repli. Si le endpoint Prometheus est inaccessible, le daemon utilise le modèle proxy pour tous les services configurés cloud. Les types d'instance inconnus retombent sur un défaut au niveau du fournisseur.

Limites de précision. Le modèle d'interpolation SPECpower a une précision d'environ +/-30%, meilleure que le modèle proxy mais moins précise que Scaphandre RAPL. Voir Limites pour les détails.

[green.electricity_maps] (optionnel, opt-in)

Intensité carbone en temps réel via l'API Electricity Maps. Mode daemon uniquement.

La sous-table region_map associe les régions cloud aux zones Electricity Maps :

[green.electricity_maps]
# Utilisez PERF_SENTINEL_EMAPS_TOKEN au lieu de api_key dans le fichier
poll_interval_secs = 300

[green.electricity_maps.region_map]
"eu-west-3" = "FR"
"us-east-1" = "US-NY"
"ap-northeast-1" = "JP-TK"

Staleness : si le dernier sondage réussi date de plus de 3x poll_interval_secs, le scraper retombe sur les profils horaires embarqués.

Limites de débit : le tier gratuit d'Electricity Maps autorise environ 30 requêtes par mois et par zone. Les utilisateurs du tier gratuit doivent mettre poll_interval_secs = 3600 ou plus. La valeur par défaut de 300s est prévue pour les plans payants.

Version d'API : l'endpoint par défaut cible v4 depuis perf-sentinel 0.5.11. v3 reste accepté (le schéma de réponse est identique sur carbon-intensity/latest), mais un avertissement de dépréciation est loggué une fois au démarrage du daemon. Pour le faire taire, mettez endpoint = "https://api.electricitymaps.com/v4" explicitement. Pour rester délibérément sur v3 (par exemple pour valider A/B contre v4), laissez endpoint = "https://api.electricitymaps.com/v3" et acceptez l'avertissement.

Valeurs inconnues pour emission_factor_type et temporal_granularity : ces deux knobs utilisent un parser fail-graceful. Une faute de frappe ou une valeur non supportée (par exemple temporal_granularity = "5min" au lieu de "5_minutes") ne rejette pas la config au chargement. La valeur est sanitisée, un tracing::warn! est émis, et le daemon retombe sur le défaut. Surveillez les logs du daemon au démarrage si vous suspectez une faute de frappe, la ligne warn nommera le champ et la valeur fautifs.

Visibilité dans les rapports (depuis perf-sentinel 0.5.12) : la configuration de scoring active (version d'API, modèle de facteur d'émission, granularité temporelle) est exposée à trois endroits pour qu'un auditeur Scope 2 puisse vérifier quel modèle carbone a produit les chiffres sans lire la TOML de l'opérateur.

• Le rapport JSON porte toujours green_summary.scoring_config quand le scoring GreenOps est actif : il enregistre les coefficients appliqués et un flag electricity_maps. Les champs propres à l'API ne sont significatifs que lorsque ce flag vaut true.
• Le dashboard HTML rend un bandeau de chips au-dessus de la table green-regions. Les valeurs par défaut (v4, lifecycle, hourly) apparaissent en chips neutres, les opt-ins (direct, 5_minutes, 15_minutes) en chips accent, l'endpoint legacy v3 en chip warning miroir de l'avertissement de dépréciation. Les tooltips natifs du navigateur expliquent chaque valeur.
• La sortie terminale print_green_summary ajoute une ligne Carbon scoring: Electricity Maps v4, lifecycle, hourly avant le détail par région.

Le bandeau et la ligne terminal sont masqués quand [green.electricity_maps] n'est pas configuré.

[green] calibration_file (optionnel)

Chemin vers un fichier TOML de calibration généré par perf-sentinel calibrate. Les facteurs par service multiplient l'énergie proxy par opération.

[green]
calibration_file = ".perf-sentinel-calibration.toml"

Limites de taille d'entrée pour perf-sentinel calibrate. Les deux entrées sont plafonnées pour éviter une consommation mémoire incontrôlée : le fichier --traces est plafonné à 1 Gio (plafond batch fixe depuis 0.8.7, identique à analyze) et le CSV --measured-energy est plafonné à 64 MiB. Calibrate termine avec une erreur claire si l'un des fichiers dépasse sa limite. 64 MiB est généreux pour des milliers d'échantillons RAPL par minute, si vous avez besoin de plus, augmentez max_payload_size et ouvrez une issue décrivant la charge de travail.

perf-sentinel tempo (pas de section de config)

La sous-commande tempo s'exécute en mode batch (pas daemon), récupère les traces depuis l'API HTTP d'un Grafana Tempo et les passe dans le pipeline d'analyse standard. Ses réglages propres sont des flags CLI uniquement, il n'existe pas de section [tempo] : --endpoint est obligatoire, --max-traces vaut 100 par défaut, aux côtés de --trace-id, --service, --lookback et --auth-header. Lancez perf-sentinel tempo --help pour la liste à jour. Une table [tempo] écrite dans le fichier de config est ignorée en silence, comme toute table racine inconnue. Le fichier --config s'applique quand même pour le reste, les seuils et la détection en particulier, puisque les traces récupérées passent par le même pipeline.

[daemon]

Paramètres du mode streaming (perf-sentinel watch).

Zones de confort et avertissements au démarrage

Les limites du daemon acceptent toute valeur à l'intérieur de leurs bornes dures (rejetées au chargement de la config), mais perf-sentinel watch émet un log WARN unique au démarrage quand une valeur sort de la zone de confort recommandée. L'avertissement est informatif : le daemon continue de tourner. Sert de garde-fou pour vérifier qu'une valeur inhabituelle est bien volontaire.

Les zones de confort jugent la valeur statique au démarrage. Au runtime, le daemon les complète avec un conseiller de réglages : quand les compteurs lifetime montrent un réglage sous-dimensionné pour la charge observée (sheds de file, rejets d'ingestion, fenêtre de traces presque pleine...), /api/export/report émet des entrées tuning dans Report.warning_details nommant le réglage, sa valeur actuelle et l'ajustement suggéré. Voir Métriques section "Kinds de warning : transitoire vs collant" pour la table des règles.

[daemon.correlation] (optionnel)

Corrélation temporelle cross-trace en mode daemon. Quand activé, le daemon détecte les co-occurrences récurrentes entre findings de services ou traces différents (ex. "chaque fois que le N+1 dans order-svc se déclenche, une saturation du pool apparaît dans payment-svc dans les 2 secondes").

[daemon.correlation]
enabled = true
window_minutes = 10
lag_threshold_ms = 2000
min_co_occurrences = 3
min_confidence = 0.5

Les corrélations sont exposées via GET /api/correlations (quand api_enabled = true) et émises en NDJSON sur le flux stdout du daemon.

[daemon.ack] (optionnel, depuis 0.5.20)

Store d'acks runtime côté daemon. Complète les acks TOML CI (voir Acquittements) avec un fichier JSONL append-only muté via les endpoints HTTP POST / DELETE /api/findings/{signature}/ack.

[daemon.ack]
enabled = true
storage_path = "/var/lib/perf-sentinel/acks.jsonl"
# api_key = "<à-rotater>"
toml_path = "/etc/perf-sentinel/acknowledgments.toml"

Le fichier JSONL est rejoué et atomiquement réécrit (via tmp + rename) à chaque redémarrage du daemon, donc des cycles ack / unack répétés ne peuvent pas s'accumuler au-delà de leur état actif net. Sur Unix, le fichier est créé avec le mode 0600 (lecture-écriture propriétaire uniquement).

[daemon.cors] (optionnel, depuis 0.5.23)

Cross-origin resource sharing pour les endpoints /api/* du daemon. Désactivé par défaut (aucun en-tête Access-Control-Allow-Origin n'est émis, la posture loopback-only est préservée). À activer quand un client navigateur doit appeler le daemon, typiquement le rapport HTML en mode live (perf-sentinel report --daemon-url <URL>, voir Rapport HTML).

Scope : le layer CORS est branché uniquement sur le sous-router /api/*. Le chemin d'ingestion OTLP (/v1/traces), l'exposition Prometheus (/metrics) et le liveness probe (/health) ne sont PAS exposés en cross-origin, même en mode wildcard. Les pages navigateur ne peuvent pas poster des traces, scraper /metrics ou frapper /health quel que soit allowed_origins. Ce confinement est intentionnel, les clients navigateur n'ont aucun usage légitime pour ces surfaces.

Exposition des read endpoints : chaque GET /api/* (/api/findings, /api/acks, /api/status, /api/correlations, /api/explain/*, /api/export/report) est non authentifié par design, en cohérence avec la posture loopback-only pré-0.5.23. Une fois qu'une origine est whitelistée, tout onglet de navigateur sur cette origine peut lire chaque signature de finding, métadonnée d'ack et export de trace que le daemon retient. Whiteliste seulement les origines auxquelles vous faites confiance pour voir l'ensemble des données du daemon. Mélanger des origines non fiables avec le mode wildcard (["*", "https://x"]) est rejeté au load de la config.

Exemple wildcard (développement) :

[daemon.cors]
allowed_origins = ["*"]

Exemple production (whitelist) :

[daemon.cors]
allowed_origins = [
    "https://reports.example.com",
    "https://gitlab.example.com",
]

Méthodes autorisées : GET, POST, DELETE, OPTIONS. En-têtes autorisés : Content-Type, X-API-Key. (X-User-Id n'est pas annoncé parce que le daemon ne l'enforce pas côté serveur, le champ by sur le body d'un ack POST est attesté par l'opérateur uniquement.) Préflight Access-Control-Max-Age : 120 secondes. Assez long pour amortir l'aller-retour OPTIONS sur une interaction typique, assez court pour qu'un whitelist resserré prenne effet au prochain préflight navigateur sans refresh forcé.

Le layer CORS ne positionne pas Access-Control-Allow-Credentials: true, incompatible avec ["*"] et inutile car le daemon authentifie via l'en-tête X-API-Key et non via des cookies. Les navigateurs sur une origine non-whitelistée reçoivent une réponse sans en-tête Access-Control-Allow-Origin et la requête est bloquée côté client, sans rejet côté daemon.

Les origines qui ne se parsent pas comme une valeur d'en-tête HTTP valide (typiquement un copier-coller avec des caractères de contrôle) sont écartées au démarrage avec un log warn! et le reste de la liste est honoré. Si toutes les entrées sont invalides, le layer est désactivé entièrement. Si daemon_api_enabled = false, le layer CORS est skippé (le sous-router /api/* n'est pas monté de toute façon) et un warn! signale la config inutilisée.

Depuis 0.5.27, combiner allowed_origins = ["*"] avec [daemon.ack] api_key émet aussi un warn! au démarrage. Le mode CORS wildcard combiné à une auth X-API-Key autorise n'importe quelle origine navigateur à rejouer une clé capturée à travers le daemon, même sans cookie ni mode Allow-Credentials. Whitelistez des origines explicites pour les déploiements de production qui configurent la clé API.

[reporting]

Paramètres de divulgation publique consommés par disclose, hash-bake et verify-hash. La section entière est optionnelle. Une section absente signifie que l'opérateur n'a jamais demandé de divulgation périodique. Guide complet dans Divulgation, référence des champs dans Schéma.

disclose ne lit aucune de ces clés : il prend --intent, --confidentiality, --period-type, --org-config et --output sur la ligne de commande. Ce que cette section fait encore, c'est conditionner le démarrage du daemon via intent et org_config_path.

La sous-section [reporting.sigstore] porte les endpoints Sigstore, Rekor étant le journal de transparence et Fulcio l'autorité de certification. Les deux sont réservés : ils sont parsés puis inutilisés. verify-hash délègue la vérification de signature au binaire cosign et appelle cosign verify-blob sans --rekor-url ni --fulcio-url, cosign suit donc sa propre configuration et renseigner l'une de ces clés ici n'a aucun effet. Pointez une instance Sigstore privée sur cosign lui-même en attendant que ce soit câblé.

Configuration minimale

Un fichier vide ou l'absence de fichier utilise tous les défauts. Une configuration minimale pour la CI peut se limiter aux seuils :

[thresholds]
n_plus_one_sql_critical_max = 0
io_waste_ratio_max = 0.25

Exemple de configuration complète

[thresholds]
n_plus_one_sql_critical_max = 0
n_plus_one_http_warning_max = 3
n_plus_one_messaging_warning_max = 3
io_waste_ratio_max = 0.30
# min_usable_span_ratio = 0.9   # absent = désactivé, voir le tableau thresholds

[detection]
n_plus_one_min_occurrences = 5
window_duration_ms = 500
slow_query_threshold_ms = 500
slow_query_min_occurrences = 3
max_fanout = 20
chatty_service_min_calls = 15
pool_saturation_concurrent_threshold = 10
serialized_min_sequential = 3

[green]
enabled = true
default_region = "eu-west-3"

[daemon]
listen_address = "127.0.0.1"
listen_port_http = 4318
listen_port_grpc = 4317
json_socket = "/tmp/perf-sentinel.sock"
max_active_traces = 10000
trace_ttl_ms = 30000
sampling_rate = 1.0
max_events_per_trace = 1000
max_payload_size = 16777216
# Optionnel : activer le TLS sur les listeners gRPC et HTTP.
# Les deux champs doivent être renseignés ensemble (ou les deux absents pour TCP en clair).
# tls_cert_path = "/etc/tls/server-cert.pem"
# tls_key_path = "/etc/tls/server-key.pem"
api_enabled = true
max_retained_findings = 10000
# Optionnel : régler les files bornées (valeurs par défaut affichées).
# Augmentez sous charge en rafales pour réduire la contre-pression
# d'ingestion / le délestage d'analyse.
ingest_queue_capacity = 1024
analysis_queue_capacity = 1024
# Optionnel : rejeter l'ingest OTLP quand la mémoire cgroup franchit ce
# pourcentage de la limite du conteneur, bornant la RSS contre l'OOM. 0
# désactive (défaut). Linux/cgroup-v2 uniquement. Réglez 80-85 pour garder
# de la marge au-dessus du régime permanent.
memory_high_water_pct = 0

# Optionnel : corrélation cross-trace (mode daemon uniquement)
# [daemon.correlation]
# enabled = true
# window_minutes = 10
# lag_threshold_ms = 2000

Migration depuis 0.5.x

Huit clés top-level legacy ont été dépréciées en 0.5.26 et retirées en 0.6.0. Une configuration 0.5.x qui en utilise encore une échoue désormais au chargement avec un message de migration explicite, plutôt que de retomber silencieusement sur la valeur par défaut. Migrez vers la forme sectionnée ci-dessous avant la mise à jour.

Exemple de migration. Avant (0.5.x) :

n_plus_one_threshold = 5
listen_port = 4318
max_payload_size = 2097152

Après (0.6.0+) :

[detection]
n_plus_one_min_occurrences = 5

[daemon]
listen_port_http = 4318
max_payload_size = 2097152

Le chargement d'un fichier 0.5.x sur 0.6.0 retourne une ConfigError::Validation dont le message nomme à la fois la clé retirée et son remplacement, donc un simple tail du flux d'erreur indique exactement quoi modifier.

Variables d'environnement

Les fichiers de configuration ne doivent jamais contenir de secrets. Pour les valeurs sensibles (clés API, tokens), utilisez des variables d'environnement dans vos outils de déploiement. perf-sentinel ne lit pas lui-même de variables d'environnement pour la configuration.

Fichier d'acknowledgments

.perf-sentinel-acknowledgments.toml est un fichier séparé de .perf-sentinel.toml. Il vit à la racine du repo applicatif et liste les findings que l'équipe a acceptés comme connus. Les findings acquittés sont retirés de la sortie CLI (analyze, report, inspect, diff) et exclus de la quality gate.

Règles de chargement :

• Le chemin par défaut est ./.perf-sentinel-acknowledgments.toml dans le répertoire courant. Override avec --acknowledgments <chemin>.
• Si le fichier n'existe pas, le run est un no-op (pas d'erreur, pas de bruit en sortie).
• --no-acknowledgments ignore le fichier complètement (vue d'audit).
• Une coquille dans signature, un champ requis manquant, ou un expires_at mal formé fait échouer le run de façon visible plutôt que d'élargir silencieusement l'ensemble acquitté.

Entry minimale :

[[acknowledged]]
signature = "redundant_sql:order-service:POST__api_orders:cafebabecafebabecafebabecafebabe"
acknowledged_by = "alice@example.com"
acknowledged_at = "2026-05-02"
reason = "Pattern d'invalidation de cache, intentionnel. Voir ADR-0042."

Le champ expires_at = "YYYY-MM-DD" est optionnel. L'omettre rend l'ack permanent. Le définir permet d'imposer une réévaluation périodique : quand la date passe, l'ack cesse de s'appliquer et le finding réapparaît au prochain run CI.

Pas de support glob ou wildcard, chaque entry est matchée contre une signature exacte. Les signatures sont émises sur chaque finding dans la sortie JSON, copiez-les dans le fichier plutôt que de recalculer le préfixe SHA-256 à la main.

Pour le workflow complet et la FAQ, voir Acquittements.