Metodologia danych
Jak Alveos zbiera, przechowuje, przekształca i opisuje metryki dystrybucji oprogramowania.
Zasady
Każda metryka musi podać źródło, znaczenie, aktualność, pokrycie i transformację. Brakujące dane pozostają brakujące: Alveos nie wypełnia przerw szacunkami. „Oficjalne”, „zweryfikowane” lub „niezależne” jest używane tylko wtedy, gdy źródło naprawdę tę tezę potwierdza.
Klasy źródeł
- Publiczne źródło dostawcy: bezpośrednie publiczne API lub listingi, np. VS Code Marketplace, Open VSX, GitHub Releases, PyPI i Packagist.
- Publiczny zbiór danych / zaufana strona trzecia: nazwane zbiory, np. PSF BigQuery lub PypiStats.
- Telemetria produktu: podłączony produkt wysyła zdarzenia cyklu życia do Alveos (Beacon; Streaming Zebra wkrótce dostępne). Liczby pochodzą z produktu i sposobu liczenia wydawcy — sterowane zdarzeniami, nie pobierane z marketplace.
- Ręczny import wydawcy: np. dane VS Code Publisher Hub dostarczone przez wydawcę. Pozostają oddzielone od publicznych liczników Gallery.
Znaczenie metryk
To, co źródło dostarcza, Alveos zapisuje. Tego, czego nie dostarcza, tutaj nie rejestrujemy.
| Źródło | Dostarczone i zapisane | Brakuje |
|---|---|---|
| VS Code Marketplace (Gallery) | Publiczne liczniki (downloadCount, install, updateCount) — pozyskanie |
Aktualnie aktywne instalacje: Gallery tego nie podaje, Alveos tego tu nie zapisuje |
| Open VSX | downloadCount (pobrania VSIX) |
Aktywne instalacje, unikalni użytkownicy, deinstalacje: ani dostarczone, ani zapisane |
| GitHub Releases | download_count plików wydania |
Klony, prywatne repozytoria, archiwa źródłowe |
| PyPI / PypiStats | Pobrania plików (seria dzienna bez luster) | Unikalni użytkownicy i instalacje, bo źródło ich nie liczy |
| Packagist | downloads.total / monthly |
Instalacje i unikalni użytkownicy |
| Beacon / cykl życia | Zdarzenia install, update, uninstall, usage i build zgłoszone przez produkt | Liczniki marketplace; uninstall często niekompletny |
| Publisher Hub (import) | Dni Daily Stats dostarczone przez wydawcę | To nie SSOT Gallery; VSIX ze strony tylko, gdy plik ma tę kolumnę |
Liczników o różnym znaczeniu nie przedstawia się po cichu jako tej samej metryki.
Zbieranie, aktualność i luki
Publiczne sklepy Alveos pobiera raz dziennie o 05:20 Europe/Berlin. Zapisuje dzisiejszy dzień UTC. Nieudane pobranie pomija dzień, zachowuje historię i nie wpisuje zer. Gallery, Open VSX, GitHub, PyPI-JSON, PypiStats i Packagist nie są dosyłane trzy dni wstecz.
Na wykresie: od pierwszego zapisanego dnia ciągła linia zostaje na ostatnim znanym stanie (step-hold). Jeśli w międzyczasie brakuje pobrania, Alveos rysuje ten sam stan linią przerywaną — ostatnia znana wartość, bez prognozy i bez krzywej trendu nad rzeczywistymi punktami. Brakujące dni w oknie są oznaczone. Dni przed połączeniem nie są lukami.
Jeśli ostatni udany dzień jest sprzed dwóch lub trzech dni, seria jest opóźniona; od czwartego dnia przestarzała. To etykieta wyświetlania, nie dosyłanie.
Dwa wyjątki nadpisują nowsze dni, gdy następne pobranie się uda: Streaming Zebra zapisuje D−2 i D−1 z podsumowania; kraje PyPI (BigQuery, płatne taryfy) ponownie zapisują ostatnie siedem dni UTC. Import wydawcy i Beacon nie są dziennym pobraniem i nie liczą się jako pominięte luki.
Transformacja i porównywalność
Alveos zachowuje surowe wartości dostawcy i oznacza wartości pochodne, takie jak różnice liczników kumulatywnych, sumy, stosunki, wartości importowane i odfiltrowane partycje. Kanały bezpośredniej dostawy i GitHub, które mogą opisywać tę samą dostawę, pozostają rozdzielone. Aktualizacje Streaming Zebra i Beacon nie są dodawane podwójnie.
Odtwarzalne eksporty
Eksporty CSV i JSON zawierają dostawcę, zewnętrzne ID, klasę źródła, znaczenie metryki, początek pokrycia, rytm, wersję transformacji, link do źródła i skrót SHA-256 wiersza. Historyczne migawki mają obecnie dokładność dnia UTC: fetched_on zawiera dzień, time_precision to day, a fetched_at pozostaje puste zamiast wymyślać godzinę.
Odniesienia do dostawców
| Źródło | Pobranie | Rytm |
|---|---|---|
| VS Code Gallery, Open VSX, GitHub Releases, PyPI-JSON, PypiStats, Packagist | Cron zapisuje dzisiejszy dzień UTC | Codziennie 05:20 Europe/Berlin |
| Kraje PyPI (BigQuery, płatne taryfy) | Upsert ostatnich siedmiu dni UTC | Ten sam cron |
| Streaming Zebra (wkrótce dostępne) | Podsumowanie; naprawia D−2 i D−1 | Ten sam cron |
| Beacon | Produkt wysyła | Sterowane zdarzeniami, nie dzienne pobranie |
| Publisher Hub | Import xlsx | Przy imporcie |
Korekty podlegające audytowi
Zalogowani właściciele i personel zgłaszają pod Korektami danych już zapisaną łączność: jeden dzień UTC, jedną metrykę (pobrania, instalacje lub aktualizacje), proponowaną liczbę całkowitą i uzasadnienie. Wniosek zamraża zaobserwowaną surową wartość. Korekta nie wypełnia brakującego pobrania i nie wpisuje szacunku w lukę. Nie ma importu korekt ani API korekt.
Inna osoba musi przyjąć, zanim czytelnicy zobaczą nową liczbę. Migawka dostawcy pozostaje bez zmian. Wykresy i sumy czytają aktywną warstwę. Brakujący dzień pozostaje luką.
Oznaczenie w eksporcie
CSV i JSON zachowują kolumny metryk. W skorygowanym wierszu są to wartości warstwy, nie pobrane liczby całkowite dostawcy.
| Kolumna | Wiersz skorygowany | Wiersz bez korekty |
|---|---|---|
correction_applied |
1 |
0 |
correction_request_ids |
Id przyjętych wniosków, rozdzielone przecinkami | puste |
corrected_fields |
installs, downloads i/lub updates |
puste |
correction_original_json |
JSON zastąpionych liczb całkowitych dostawcy, na przykład {"downloads":120} |
puste |
row_hash to SHA-256 tego wiersza eksportu, łącznie z liczbami warstwy i tymi czterema kolumnami. Porównaj correction_original_json z dostawcą, gdy potrzebujesz pobranej liczby całkowitej.
Pytania lub podejrzenie błędu danych: support@alveos.eu.