Méthodologie des données
Comment Alveos collecte, stocke, transforme et qualifie les métriques de distribution logicielle.
Principes
Chaque métrique doit nommer sa source, son sens, sa fraîcheur, sa couverture et sa transformation. Les données manquantes restent manquantes : Alveos ne comble pas les pannes par des estimations. « Officiel », « vérifié » ou « indépendant » n’est utilisé que si la source porte réellement cette affirmation.
Classes de source
- Source fournisseur publique : API ou fiches publiques telles que VS Code Marketplace, Open VSX, GitHub Releases, PyPI et Packagist.
- Jeu de données public / tiers de confiance : jeux nommés tels que PSF BigQuery ou PypiStats.
- Télémétrie du produit : le produit connecté envoie des événements de cycle de vie à Alveos (Beacon ; Streaming Zebra bientôt disponible). Les chiffres viennent du produit et de la façon de compter du publisher — déclenchés par les événements, non récupérés d’une place de marché.
- Import manuel du publisher : par exemple les données Publisher Hub fournies par l’éditeur. Elles restent séparées des compteurs Gallery publics.
Sens des métriques
Alveos stocke ce que la source livre. Ce qu’elle ne livre pas n’est pas capturé ici.
| Source | Livré et capturé | Manque |
|---|---|---|
| VS Code Marketplace (Gallery) | Compteurs publics (downloadCount, install, updateCount) — acquisition |
Installations actuellement actives : la Gallery ne les fournit pas, Alveos ne les capture pas ici |
| Open VSX | downloadCount (téléchargements VSIX) |
Installations actives, utilisateurs uniques, désinstallations : ni livrés ni capturés |
| GitHub Releases | download_count des fichiers de release |
Clones, dépôts privés, archives sources |
| PyPI / PypiStats | Téléchargements de fichiers (série quotidienne hors miroirs) | Utilisateurs uniques et installations, parce que la source ne les compte pas |
| Packagist | downloads.total / monthly |
Installations et utilisateurs uniques |
| Beacon / cycle de vie | Événements install, update, uninstall, usage et build signalés par le produit | Compteurs de place de marché ; uninstall souvent incomplet |
| Publisher Hub (import) | Jours Daily Stats fournis par le publisher | Pas de SSOT Gallery ; VSIX site seulement si le fichier a la colonne |
Des compteurs de sens différent ne sont pas présentés silencieusement comme la même métrique.
Collecte, fraîcheur et lacunes
Alveos interroge les stores publics une fois par jour à 05:20 Europe/Berlin. Seul le jour UTC d’aujourd’hui est stocké. Un échec saute le jour, conserve l’historique et n’écrit pas de zéros. Gallery, Open VSX, GitHub, PyPI-JSON, PypiStats et Packagist ne sont pas rattrapés sur trois jours.
Sur le graphe : dès le premier jour stocké, la ligne continue reste sur le dernier niveau connu (step-hold). Si un prélèvement manque, Alveos trace ce même niveau en pointillés — dernière valeur connue, pas une projection ni une courbe de tendance au-dessus des points réels. Les jours manquants dans la fenêtre sont marqués. Les jours avant la connexion ne sont pas des lacunes.
Si le dernier jour réussi date de deux ou trois jours, la série est retardée ; à partir du quatrième jour elle est périmée. C’est un libellé d’affichage, pas un rattrapage.
Deux exceptions réécrivent des jours récents si le prochain prélèvement réussit : Streaming Zebra stocke J−2 et J−1 depuis le résumé ; les pays PyPI (BigQuery, offres payantes) réécrivent les sept derniers jours UTC. Import publisher et Beacon ne sont pas un prélèvement quotidien et ne sont pas notés comme lacunes manquées.
Transformations et comparabilité
Alveos conserve les entiers bruts du fournisseur et identifie les valeurs dérivées : écarts de compteurs cumulatifs, sommes, ratios, imports et partitions filtrées. Les canaux de livraison directe et GitHub qui peuvent décrire la même livraison restent séparés. Les mises à jour Streaming Zebra et Beacon ne sont pas additionnées deux fois.
Exports reproductibles
Les exports CSV et JSON incluent fournisseur, identifiant externe, classe de source, sémantique, début de couverture, cadence, version de transformation, URL source et un hachage SHA-256 de ligne. Les snapshots historiques ont actuellement une précision au jour UTC : fetched_on contient le jour, time_precision vaut day, et fetched_at reste vide plutôt que d’inventer une heure.
Références fournisseurs
| Source | Prélèvement | Cadence |
|---|---|---|
| VS Code Gallery, Open VSX, GitHub Releases, PyPI-JSON, PypiStats, Packagist | Le cron stocke le jour UTC d’aujourd’hui | Quotidien 05:20 Europe/Berlin |
| Pays PyPI (BigQuery, offres payantes) | Upsert des sept derniers jours UTC | Même cron |
| Streaming Zebra (bientôt disponible) | Résumé ; répare J−2 et J−1 | Même cron |
| Beacon | Le produit envoie | Événementiel, pas un prélèvement quotidien |
| Publisher Hub | Import xlsx | À l’import |
- VS Code Marketplace
- Open VSX
- API GitHub Release Assets
- Données publiques PyPI dans BigQuery
- API Packagist
Corrections auditables
Les publishers connectés signalent sous Corrections de données une connexion déjà stockée : jour UTC, métrique (téléchargements, installations ou mises à jour), valeur proposée et motif. La demande conserve la valeur brute observée. Une correction ne comble pas un prélèvement manqué et n’écrit pas d’estimation dans une lacune.
Examen, acceptation, rejet, application et remplacement sont des événements uniquement ajoutés dans une chaîne de hachage visible. Une correction appliquée est un overlay de lecture versionné ; le snapshot fournisseur reste inchangé. Graphes, totaux et exports utilisent l’overlay actif. CSV/JSON indiquent la demande et les valeurs d’origine avec correction_request_ids et correction_original_json. Une validation plus récente révoque l’ancien overlay mais conserve les deux historiques.
Questions ou erreurs de données suspectées : support@alveos.eu.