Metodologia de dados
Como o Alveos recolhe, guarda, transforma e identifica métricas de distribuição de software.
Princípios
Cada métrica deve nomear fonte, significado, atualidade, cobertura e transformação. Dados em falta permanecem em falta: o Alveos não preenche falhas com estimativas. «Oficial», «verificado» ou «independente» só é usado se a fonte realmente sustentar essa afirmação.
Classes de fonte
- Fonte pública do fornecedor: APIs ou listagens públicas como VS Code Marketplace, Open VSX, GitHub Releases, PyPI e Packagist.
- Conjunto de dados público / terceiro de confiança: conjuntos nomeados como PSF BigQuery ou PypiStats.
- Telemetria do produto: o produto ligado envia eventos de ciclo de vida ao Alveos (Beacon; Streaming Zebra em breve). Os números vêm do produto e da forma de contar do publisher — por eventos, não obtidos de um marketplace.
- Importação manual do publisher: por exemplo dados do Publisher Hub. Permanecem separados dos contadores públicos da Gallery.
Significado das métricas
O Alveos guarda o que a fonte entrega. O que não entrega não é capturado aqui.
| Fonte | Entregue e capturado | Falta |
|---|---|---|
| VS Code Marketplace (Gallery) | Contadores públicos (downloadCount, install, updateCount) — aquisição |
Instalações atualmente ativas: a Gallery não as dá; o Alveos não as captura aqui |
| Open VSX | downloadCount (transferências VSIX) |
Instalações ativas, utilizadores únicos, desinstalações: nem entregues nem capturados |
| GitHub Releases | download_count dos ficheiros de release |
Clones, repositórios privados, arquivos-fonte |
| PyPI / PypiStats | Transferências de ficheiros (série diária sem mirrors) | Utilizadores únicos e instalações, porque a fonte não os conta |
| Packagist | downloads.total / monthly |
Instalações e utilizadores únicos |
| Beacon / ciclo de vida | Eventos install, update, uninstall, usage e build do produto | Contadores de marketplace; uninstall muitas vezes incompleto |
| Publisher Hub (importação) | Dias de Daily Stats fornecidos pelo publisher | Não é SSOT da Gallery; VSIX do sítio só se o ficheiro tiver a coluna |
Contadores com significados diferentes não são apresentados em silêncio como a mesma métrica.
Recolha, atualidade e lacunas
O Alveos consulta as lojas públicas uma vez por dia às 05:20 Europe/Berlin. Guarda o dia UTC de hoje. Uma falha salta o dia, mantém o histórico e não escreve zeros. Gallery, Open VSX, GitHub, PyPI-JSON, PypiStats e Packagist não são preenchidos três dias para trás.
No gráfico: a partir do primeiro dia guardado, a linha contínua fica no último valor conhecido (step-hold). Se faltar uma consulta, o Alveos desenha o mesmo valor a tracejado — último stock, não uma previsão nem uma curva de tendência sobre os pontos reais. Os dias em falta na janela são marcados. Os dias anteriores à ligação não são lacunas.
Se o último dia bem-sucedido tiver dois ou três dias, a série está atrasada; a partir do quarto dia está obsoleta. É um rótulo de ecrã, não um preenchimento.
Duas exceções reescrevem dias recentes se a consulta seguinte funcionar: Streaming Zebra guarda D−2 e D−1 do resumo; países PyPI (BigQuery, tarifas pagas) reescrevem os últimos sete dias UTC. Importação e Beacon não são consulta diária e não contam como lacunas perdidas.
Transformações e comparabilidade
O Alveos conserva os inteiros brutos do fornecedor e identifica valores derivados: diferenças de contadores cumulativos, somas, rácios, importações e partições filtradas. Os canais de entrega direta e GitHub que podem descrever a mesma entrega permanecem separados. As atualizações Streaming Zebra e Beacon não são somadas duas vezes.
Exportações reproduzíveis
CSV e JSON incluem fornecedor, ID externo, classe, significado, início da cobertura, cadência, versão de transformação, URL e um hash SHA-256 da linha. Os snapshots históricos têm precisão de dia UTC: fetched_on contém o dia, time_precision é day, e fetched_at fica vazio em vez de inventar uma hora.
Referências de fornecedores
| Fonte | Consulta | Cadência |
|---|---|---|
| VS Code Gallery, Open VSX, GitHub Releases, PyPI-JSON, PypiStats, Packagist | O cron guarda o dia UTC de hoje | Diário 05:20 Europe/Berlin |
| Países PyPI (BigQuery, tarifas pagas) | Upsert dos últimos sete dias UTC | O mesmo cron |
| Streaming Zebra (em breve) | Resumo; repara D−2 e D−1 | O mesmo cron |
| Beacon | O produto envia | Por eventos, não consulta diária |
| Publisher Hub | Importação xlsx | Na importação |
- VS Code Marketplace
- Open VSX
- GitHub Release Assets API
- Dados públicos PyPI no BigQuery
- API Packagist
Correções auditáveis
Publishers autenticados indicam em Correções de dados uma ligação já guardada: dia UTC, métrica (transferências, instalações ou atualizações), valor proposto e motivo. O pedido guarda o valor bruto observado. Uma correção não preenche uma consulta falhada nem escreve uma estimativa numa lacuna.
Revisão, aceitação, rejeição, aplicação e substituição são apenas eventos acrescentados numa cadeia de hash visível. Uma correção aplicada é um overlay de leitura versionado; o snapshot do fornecedor permanece inalterado. Gráficos, totais e exportações usam o overlay ativo. CSV/JSON identificam o pedido e os valores originais com correction_request_ids e correction_original_json. Uma aprovação mais recente revoga o overlay antigo, mas conserva ambos os históricos.
Perguntas ou possíveis erros nos dados: support@alveos.eu.