Référence schéma : perf-sentinel-report v1.6

Ce document décrit la forme JSON d'un rapport de transparence périodique en prose. Le JSON Schema lisible par machine se trouve dans docs/schemas/perf-sentinel-report-v1.json (draft 2020-12). Deux exemples remplis sont sous docs/schemas/examples/.

La v1.1 ajoute les tiers canonical_waste et operational_waste à aggregate. La v1.2 ajoute aggregate.temporal_coverage (un signal de continuité de mesure), scope_manifest.coverage_basis (un marqueur de provenance) et le hook réservé integrity.cross_period_log. La v1.3 ajoute methodology.standard_crosswalk (une correspondance interprétative vers les datapoints ESRS E1) et applications[].anti_patterns[].rgesn_criteria par pattern (critères RGESN 2024). La v1.4 ajoute aggregate.database_waste (l'énergie et le carbone évitables côté base de données aux deux seuils, avec ses modèles de provenance, une borne basse informative tenue hors de tous les totaux). La v1.5 ajoute le support messaging : deux valeurs à PatternName (n_plus_one_messaging, slow_messaging) et aggregate.messaging_waste, le jumeau broker de database_waste (tout aussi informatif et tout aussi exclu de chaque total, même si le sens de son erreur dépend de son étiquette model, voir Limites), émises dès lors que des spans de publication vers un broker sont ingérés. Les deux blocs de gaspillage gagnent aussi declared_windows et declared_energy_kwh, qui portent la part de la figure qu'un opérateur a déclarée plutôt que mesurée, pour qu'une déclaration de cluster provisionné ne soit jamais publiée dans measured_energy_kwh. Ils sont omis quand ils valent zéro, ce qui est toujours le cas sur le bloc base de données. La v1.6 rend visibles les paramètres carbone, via quatre champs de methodology.calibration_inputs : carbon_methodologies (les tags SCI observés sur les fenêtres de la période, qui disent si le transport réseau est entré dans le numérateur), embodied_gco2_total (le terme M de SCI sommé sur la période), embodied_gco2_per_request (ce total divisé par total_requests, donc comparable d'un rapport à l'autre et indépendant du volume de trafic) et scoring_coefficients (les coefficients avec lesquels les fenêtres ont été scorées, sous forme de chaînes clé=valeur, deux entrées pour une même clé signalant un changement en cours de période). Les réglages derrière eux, à commencer par [green] embodied_carbon_per_request_gco2 et [green] network_energy_per_byte_kwh, mettent à l'échelle les chiffres publiés et n'apparaissaient nulle part dans le rapport : diviser un coefficient par deux ne laissait aucune trace. Les trois sont lus sur les fenêtres archivées plutôt que sur la configuration de la machine qui lance disclose, seule source correcte quand la période a été produite ailleurs, et plusieurs entrées dans carbon_methodologies signalent que la période couvre des méthodologies de numérateur historiques et actuelles. Elle décompose aussi le total publié : aggregate.carbon_breakdown donne les termes opérationnel, embodied et transport, dont la somme fait total_carbon_kgco2eq. Seul le terme opérationnel porte une part évitable, celle que quantifient les tiers de gaspillage, tandis que le matériel amorti et le transport réseau ne se réduisent pas en corrigeant un anti-pattern : lire le total seul mélange donc ce sur quoi un opérateur peut agir et ce sur quoi il ne peut pas. Le bloc porte aussi database_kgco2eq_out_of_total et messaging_kgco2eq_out_of_total pour les chiffres mesurés ou déclarés sur un périmètre externe. Le carbone estimé de repli est déjà inclus dans le total des services et reste exclu ici. Les deux sont hors de la somme et hors de total_carbon_kgco2eq : le cgroup d'une base et un broker relèvent d'un périmètre différent des services instrumentés, et les y intégrer mélangerait les périmètres. Ils sont publiés ici pour que toute figure carbone produite par un run se lise au même endroit. Chaque terme de la décomposition est omis quand sa valeur est nulle, pour qu'un terme non mesuré ne se lise jamais comme mesuré à zéro, et la méthodologie indique toujours que le transport fait partie du numérateur actuel. Le transport reste le moins certain des trois quand il est présent : les valeurs publiées s'étalent sur deux ordres de grandeur, son coefficient est donc fixe depuis la 0.9.25 (0.04 kWh/Go, plus configurable, chaque divulgation met le même trafic à la même échelle) et le terme est aussi publié sous la fourchette sourcée, transport_kgco2eq_low (0.001 kWh/Go, Cloud Carbon Footprint) et transport_kgco2eq_high (0.059 kWh/Go, segment réseau du Sustainable Web Design Model v4, un plafond). La v1.6 remplit aussi integrity.trace_integrity_chain, réservé et toujours nul jusqu'ici. Le daemon chaîne par hachage chaque fenêtre archivée au moment où il l'écrit, et disclose parcourt cette chaîne pendant l'agrégation, en publiant combien de fenêtres se vérifient, combien ne portent aucune chaîne (écrites avant que cela existe) et combien de ruptures ont été trouvées. Une rupture signale une fenêtre éditée, supprimée ou réordonnée après son écriture. Les ruptures trouvées dans les mêmes fichiers mais hors de la période sont comptées à part, sous breaks_outside_period, puisqu'une archive glissante peut couvrir des années et que ce rapport ne répond que de sa propre période. Le rapport est produit quand même et le dit, plutôt que de refuser d'exister, si bien qu'une archive tronquée ou une rotation donne encore un rapport partiel honnête. Deux choses que la chaîne ne fait pas. Elle ne voit pas une troncature nette de la fin d'une archive, qui laisse une chaîne plus courte mais cohérente qu'aucun champ interne au fichier ne peut contredire. Et elle n'atteste pas la source : qui contrôle le daemon et ses fichiers peut régénérer une chaîne cohérente, et le champ tombe sous le content_hash justement pour qu'un compteur de ruptures ne puisse pas être remis à zéro sous une signature valide. Fermer ce dernier écart demande un ancrage externe de la tête de chaîne, ce à quoi integrity.cross_period_log reste réservé. La divulgation demeure une estimation directionnelle, pas de qualité réglementaire. Le schéma accepte perf-sentinel-report/v1.0 jusqu'à v1.6, et chaque champ ajouté prend une valeur par défaut quand il est absent, donc les lecteurs et rapports plus anciens restent valides et le content_hash d'un rapport plus ancien reste identique quand il est rehashé sur un binaire plus récent.

Clés racine

Le schéma ne fixe pas additionalProperties: false ; de nouveaux champs peuvent être ajoutés dans un bump mineur SemVer sans casser les consommateurs qui ne lisent que l'ensemble documenté.

Métadonnées de rapport

Un rapport de divulgation porte trois axes orthogonaux à lire avant tout parsing des données : intent indique à qui le rapport est destiné (brouillon privé, publication externe, ou publication auditée par un tiers), confidentiality_level indique le niveau de détail par service exposé (breakdown anti-patterns G1 complet vs comptages G2 agrégés), et integrity_level indique quelles primitives cryptographiques garantissent le document (rien, content hash seul, signé Sigstore, signé avec attestation de build SLSA). Ensemble, ils permettent à un auditeur ou un journaliste de filtrer le corpus avant de faire confiance à un chiffre à l'intérieur.

intent vaut internal | official | audited. audited est réservé pour une release future : le schéma JSON accepte la valeur pour la compatibilité ascendante, mais la CLI le refuse aujourd'hui avec le code de sortie 2. confidentiality_level vaut internal | public. integrity_level vaut none | hash-only | signed | signed-with-attestation | audited. Par défaut, la CLI produit hash-only. generated_at est un timestamp UTC RFC 3339. generated_by vaut daemon | cli-batch | ci. perf_sentinel_version est la chaîne SemVer du binaire qui a écrit le fichier. report_uuid est un UUID v4 estampillé par run.

Organisation

name est requis et non vide. country est en ISO 3166-1 alpha-2, majuscules. identifiers est un objet ouvert avec siren, vat, lei, opencorporates_url, domain optionnels. sector est un code NACE rev2 optionnel.

Le domaine de publication (par exemple transparency.example.fr) est traité comme un identifiant implicite quand notes.reference_urls.project est publié depuis cet hôte. Le schéma ne l'impose pas, par choix.

Période

from_date et to_date sont des dates calendaires ISO 8601 (YYYY-MM-DD). period_type vaut calendar-quarter | calendar-month | calendar-year | custom. days_covered vaut to_date - from_date + 1. Le validator intent officiel impose days_covered >= 30.

Manifeste de scope

total_applications_declared est la taille du portefeuille applicatif de l'organisation. applications_measured est le nombre de services pour lesquels le rapport porte des données. Chaque entrée de applications_excluded porte service_name et un reason non vide. environments_measured liste les environnements définis par l'opérateur et observés (par exemple ["prod"]). total_requests_in_period est une estimation opérateur optionnelle, requests_measured est ce que perf-sentinel a effectivement vu. coverage_percentage vaut requests_measured / total_requests_in_period * 100 quand le premier est renseigné.

coverage_basis (v1.2) rend la frontière de confiance explicite, en bande. Il liste quels champs de scope sont operator_declared (assertions non auditées que le binaire ne peut pas vérifier : les dénominateurs total_applications_declared et total_requests_in_period, plus les listes d'exclusion) versus machine_derived (calculés par l'agrégateur depuis les archives : applications_measured, requests_measured, coverage_percentage). Un lecteur de coverage_percentage doit traiter son dénominateur comme une assertion opérateur : un opérateur qui fixe total_requests_in_period bas peut présenter une couverture proche de 100 % d'un univers qu'il a lui-même défini. C'est inhérent à un modèle d'auto-déclaration, les garanties d'intégrité cryptographique lient le rapport publié, pas l'honnêteté de la taille de portefeuille déclarée. Voir 08 · Divulgation périodique.

Méthodologie

sci_specification référence la révision SCI (par exemple "ISO/IEC 21031:2024"). perf_sentinel_version reprend le champ des métadonnées pour les consommateurs qui n'indexent que le bloc méthodologie. enabled_patterns et disabled_patterns portent chacun des noms de patterns issus du set fermé défini par FindingType::as_str() (12 valeurs). core_patterns_required est la liste fermée des patterns dont la remédiation coupe directement de l'I/O et du carbone : n_plus_one_sql, n_plus_one_http, redundant_sql, redundant_http. conformance vaut core-required | extended | partial, core-required étant le seuil minimum pour un rapport intent = "official". calibration_inputs.carbon_intensity_source vaut electricity_maps | static_tables | mixed. specpower_table_version est la version déclarée par l'opérateur de la table SPECpower / coefficients CCF embarquée, fixée dans le TOML de config org. binary_specpower_vintage (0.7.3+) est la chaîne de millésime que le binaire embarque au build, populée automatiquement par perf-sentinel disclose. Les consommateurs peuvent comparer les deux chaînes pour détecter une dérive entre la déclaration opérateur et les données embarquées. scaphandre_used indique si le proxy énergie temps réel vient de Scaphandre RAPL. C'est un champ historique spécifique à Scaphandre : il précède les autres backends d'énergie mesurée et n'a jamais été généralisé, il reste donc à false pour une période mesurée avec Alumet, Kepler ou Redfish. energy_source_models est la source de vérité générale pour savoir quelles sources d'énergie ont produit les chiffres d'une période, il est dérivé automatiquement des fenêtres archivées et porte l'étiquette de chaque backend (alumet_rapl, scaphandre_rapl, kepler_ebpf, redfish_bmc, cloud_specpower, io_proxy_v*). Les consommateurs doivent lire energy_source_models et traiter scaphandre_used comme un indice hérité. Généraliser le champ casserait un schéma publié, haché et attesté, c'est donc reporté à une révision ultérieure du schéma. standard_crosswalk (v1.3) est une correspondance interprétative des chiffres du rapport vers les datapoints ESRS E1 (total_energy_kwh vers E1-5, le terme carbone opérationnel vers E1-6 Scope 2 location-based, le carbone embarqué vers E1-6 Scope 3). Il porte son propre tableau caveats. C'est une aide à la correspondance, pas une certification : le chiffre location-based n'est pas la valeur Scope 2 market-based qu'ESRS exige aussi, et l'intervalle d'incertitude 2x s'applique toujours. Absent sur les rapports pré-v1.3.

calibration_applied (0.7.0+) vaut true si au moins une fenêtre de scoring de la période a appliqué des coefficients de calibration opérateur per-service à l'énergie proxy. Le flag est méthodologiquement distinct de scaphandre_used et energy_source_models : ceux-ci décrivent quelle source d'énergie a produit les chiffres, ce flag décrit si ces chiffres ont été ensuite ajustés par des coefficients opérateur.

Agrégat

Voir aussi. L'introduction énergie et SCI dans la doc méthodologie définit les termes SCI v1.0 (E, I, M), efficiency_score, io_waste_ratio, Scaphandre, SPECpower et le vocabulaire associé utilisé par tous les champs ci-dessous.

Sommes sur toute la période et tout le tableau applications. total_requests, total_energy_kwh, total_carbon_kgco2eq et estimated_optimization_potential_kgco2eq sont des nombres finis non négatifs. aggregate_waste_ratio est dans [0, 1]. aggregate_efficiency_score est dans [0, 100] et vaut clamp(100 - 100 * io_waste_ratio, 0, 100). anti_patterns_detected_count est la somme de toutes les occurrences par service, y compris les patterns non évitables.

Tiers de gaspillage (1.1+)

Le rapport porte le gaspillage évitable, énergie et carbone, à deux seuils de détection N+1, côte à côte, pour rendre l'écart auditable :

• canonical_waste est calculé à un seuil N+1 fixe épinglé dans le binaire (2), pas la config de l'opérateur. C'est le chiffre non manipulable : un opérateur ne peut pas le réduire en relâchant son propre seuil. C'est le chiffre évitable de référence, et depuis la v1.1 les champs plats estimated_optimization_potential_kgco2eq, aggregate_waste_ratio et aggregate_efficiency_score sont des alias de ce tier (ils portaient la valeur opérationnelle en v1.0).
• operational_waste est calculé au seuil N+1 configuré par l'opérateur et enregistre ce seuil dans n_plus_one_threshold. Le comparer à canonical_waste montre combien de gaspillage évitable le seuil de l'opérateur masque.

Chaque tier porte n_plus_one_threshold (entier), energy_kwh et carbon_kgco2eq (non négatifs), waste_ratio ([0, 1]) et efficiency_score ([0, 100]). Pour intent = "official", le validator exige que canonical_waste.n_plus_one_threshold égale le seuil canonique du binaire. Le seuil opérationnel est le choix enregistré de l'opérateur et n'est délibérément pas borné, puisqu'un seuil relâché est précisément ce que ce tier sert à exposer. L'énergie et le carbone totaux (total_energy_kwh, total_carbon_kgco2eq) sont dérivés des spans et indépendants des deux seuils.

Gaspillage base de données (v1.4)

database_waste est un objet optionnel portant l'énergie et le carbone évitables côté base de données sur la période. C'est une borne basse et un chiffre informatif : jamais intégré à total_energy_kwh, total_carbon_kgco2eq ni aux tiers de gaspillage, absent des rapports pré-v1.4 et quand aucune fenêtre n'a porté le chiffre. Le chiffre par fenêtre est l'énergie de la base multipliée par le ratio de gaspillage SQL seul : énergie mesurée sur le cgroup Alumet déclaré quand [green.alumet.database] est configuré, sinon estimée depuis l'énergie modélisée des spans SQL de la fenêtre. models porte les étiquettes de provenance distinctes observées sur la période (alumet_rapl = mesuré, estimated = construit depuis l'énergie modélisée des spans SQL), un auditeur distingue donc mesure et modèle sans quitter le rapport. windows_with_figure compte les fenêtres qui portaient le bloc. Les chiffres operational_* utilisent le seuil N+1 de l'opérateur, les chiffres canonical_* recalculent le ratio SQL au seuil canonique épinglé dans le binaire contre la même énergie, la même construction anti-manipulation que les tiers de gaspillage ci-dessus.

Signaux de qualité (0.7.0+)

L'agrégat porte quatre champs optionnels qui décrivent la qualité des archives sources, pas la charge applicative elle-même. Ils permettent à un auditeur d'évaluer quelle proportion de la période a été mesurée directement plutôt qu'inférée d'un proxy.

• period_coverage est dans [0, 1] et vaut runtime_windows / (runtime_windows + fallback_windows). Une valeur de 1.0 signifie que toutes les fenêtres de scoring de la période portaient une énergie runtime-calibrated (Scaphandre ou cloud SPECpower). Une valeur de 0.0 signifie que toutes les fenêtres sont tombées sur le proxy I/O. Le validator refuse un rapport intent = "official" avec period_coverage < 0.75, voir 08 · Divulgation périodique pour la justification du seuil.
• runtime_windows_count et fallback_windows_count portent les compteurs absolus derrière ce ratio, pour qu'un lecteur puisse distinguer "9 fenêtres sur 10 runtime-calibrated" de "900 sur 1000".
• binary_versions est l'ensemble des versions distinctes du binaire perf-sentinel qui ont produit les archives repliées dans cette période. Une période qui couvre plusieurs versions (upgrade de daemon en milieu de trimestre, releases asynchrones entre équipes) porte plus d'une entrée dans cet ensemble, ce que le disclaimer du rapport surface.

Champs de qualité par service (0.7.0+)

• per_service_energy_models mappe chaque service à l'ensemble des tags de modèle énergétique observés sur la période (scaphandre_rapl, cloud_specpower, io_proxy_v3, etc.). Le suffixe +cal est strippé avant insertion, le flag period-wide calibration_applied dans methodology.calibration_inputs porte cette information à la place.
• per_service_measured_ratio est la moyenne par service de la fraction par fenêtre des spans dont l'énergie a été résolue par Scaphandre ou cloud SPECpower. Une valeur proche de 1.0 signifie que le service est entièrement mesuré sur la période, 0.0 qu'il s'appuie sur le proxy fallback. C'est une moyenne arithmétique simple des ratios par fenêtre, pas pondérée par le nombre de spans : une fenêtre de 10 spans et une fenêtre de 10000 spans contribuent à part égale à la moyenne.

Couverture temporelle (v1.2)

temporal_coverage est un signal de continuité : quelle part de la période déclarée a réellement porté des mesures. C'est un objet avec temporal_coverage (dans [0, 1], égal à observed_days / days_in_period), observed_days (jours calendaires UTC distincts portant au moins une fenêtre archivée), days_in_period (reflète period.days_covered) et largest_gap_days (la plus longue suite de jours consécutifs de la période sans fenêtre).

À lire comme une borne basse de l'activité, pas comme l'uptime du daemon. L'archivage du daemon est déclenché par le trafic : une fenêtre sans trafic n'écrit rien, donc les jours légitimement calmes (nuits, week-ends, services peu sollicités) abaissent le chiffre. Pour cette raison ce n'est jamais une barrière dure official. La CLI disclose publie la valeur, émet un warning sur stderr sous un seuil informatif, et ajoute un disclaimer en bande portant la même mise en garde. Il existe pour qu'un lecteur distingue une période mesurée en continu d'une période où le daemon n'a tourné que quelques jours, ce que le days_covered calendaire seul ne peut pas révéler.

Applications

Deux granularités, homogènes par rapport. Le validator refuse un rapport qui mélangerait les deux.

G1 (intent internal)

Chaque entrée porte les totaux au niveau service plus un tableau anti_patterns: [...]. Chaque détail anti-pattern a type (un des 12 patterns connus), occurrences, estimated_waste_kwh, estimated_waste_kgco2eq, first_seen, last_seen. Les timestamps sont UTC RFC 3339. rgesn_criteria (v1.3) est la liste interprétative des critères RGESN 2024 auxquels le pattern se rapporte (voir Méthodologie), vide pour slow_* et absente sur les rapports pré-v1.3. display_name et service_version sont des hints optionnels.

G2 (intent official avec confidentiality public)

Chaque entrée porte les mêmes totaux au niveau service mais remplace le tableau par un seul entier anti_patterns_detected_count. Le schéma impose que les entrées G2 ne portent pas de champ anti_patterns, et inversement.

Les deux granularités sont encodées dans le JSON Schema avec des clauses not: { required: [...] } mutuellement exclusives pour rendre la discrimination explicite aux validateurs de schéma.

Intégrité

Voir aussi. L'introduction à Sigstore dans la doc supply-chain définit Cosign, Fulcio, Rekor, in-toto, OIDC et SLSA utilisés dans cette section.

content_hash est "sha256:<64-hex>" sur la forme JSON canonique du document avec le champ content_hash mis à chaîne vide. Le schéma accepte aussi une chaîne vide pour ce champ afin que les exemples puissent être livrés sans valeur cuite. binary_hash est "sha256:<64-hex>" du binaire perf-sentinel qui a produit le fichier. binary_verification_url pointe vers l'artefact de release où les consommateurs récupèrent le même binaire. trace_integrity_chain porte le verdict de la chaîne source depuis la v1.6 et vaut null sur les rapports antérieurs, jamais omis, puisque retirer la clé changerait les octets canoniques de tout rapport déjà publié.

signature (0.7.0+) vaut soit null (rapport hash-only) soit un objet typé avec format ("sigstore-cosign-intoto-v1"), bundle_url, signer_identity, signer_issuer, rekor_url, rekor_log_index, et signed_at. Les champs permettent collectivement à un vérifieur de localiser le bundle cosign et la preuve d'inclusion Rekor.

binary_attestation (0.7.0+) est optionnel et, quand présent, porte un format ("slsa-provenance-v1"), attestation_url, builder_id, git_tag, git_commit, et slsa_level ("L2" pour 0.7.0, "L3" à partir de 0.7.1 puisque le workflow de release est passé à actions/attest-build-provenance qui produit une attestation niveau 3 par construction). Les consommateurs vérifient le binaire téléchargé depuis binary_verification_url avec gh attestation verify <binary> --repo robintra/perf-sentinel pour les releases 0.7.1+, ou avec slsa-verifier verify-artifact --provenance-path multiple.intoto.jsonl ... pour la 0.7.0 legacy.

cross_period_log (v1.2) est réservé et absent aujourd'hui. C'est le hook de schéma pour un journal externe en ajout seul ou de type Rekor qui chaîne les rapports périodiques successifs, afin qu'un tiers puisse détecter un opérateur qui aurait arrêté de publier sur plusieurs périodes, le seul trou que les garanties d'intégrité par rapport ne peuvent pas combler. Il ne sera renseigné que sous un futur intent = "audited", aux côtés de l'attestation d'audit externe.

integrity_level dans report_metadata vaut none, hash-only, signed, signed-with-attestation (0.7.0+), audited. Le lecteur peut l'utiliser comme filtre rapide avant de parser le bloc integrity.

Notes

disclaimers porte huit déclarations par défaut : les deux avertissements standard d'incertitude (estimation directionnelle, fourchette multiplicative ~2x, la spécification SCI elle-même ne définit aucune disposition d'incertitude), la précision sur le scope embarqué (exclu du potentiel d'optimisation), la note embarqué par service (opérationnel uniquement au niveau service, total au niveau agrégat), le caveat sur l'attribution runtime (les archives runtime-calibrated portent des données per-service, les plus anciennes retombent sur la part d'I/O), deux lignes de fitness réglementaire (inadapté à CSRD / GHG Scope 3, référence méthodologique), et la note de crosswalk ESRS E1 (la correspondance standard_crosswalk est une aide, pas un substitut à un inventaire CSRD audité). Les opérateurs peuvent surcharger la liste dans leur TOML org-config. reference_urls est un objet ouvert qui mappe des clés courtes (methodology, schema, project) à des URLs. Les opérateurs peuvent ajouter des clés personnalisées.

Boavizta et autres champs omis

boavizta_version a été envisagé pour calibration_inputs mais ne fait pas partie du schéma actuel parce que perf-sentinel ne consomme pas de données Boavizta aujourd'hui. Le champ reviendra quand l'intégration sera livrée. Les consommateurs de schéma DOIVENT tolérer des champs inconnus gracieusement parce que perf-sentinel en ajoutera dans des révisions mineures.

Versionnement

Un changement incompatible incrémente la version majeure dans schema_version (v2.0, v3.0). Les changements additifs (nouveaux champs optionnels, nouvelles valeurs d'énumération que les consommateurs peuvent traiter comme inconnues) incrémentent la partie mineure (v1.1, v1.2). L'URL $id du JSON Schema ne contient que la version majeure.

Renvois

• Divulgation est le guide d'utilisation côté opérateur.
• Méthodologie couvre la chaîne de calcul qui remplit aggregate et les champs énergie/carbone par application.
• docs/schemas/perf-sentinel-report-v1.json est le JSON Schema autoritaire.
• docs/schemas/examples/example-internal-G1.json et example-official-public-G2.json sont des exemples remplis.