Metodología de datos
Cómo Alveos recopila, almacena, transforma y etiqueta métricas de distribución de software.
Principios
Cada métrica debe nombrar fuente, significado, actualidad, cobertura y transformación. Los datos faltantes siguen faltando: Alveos no rellena los cortes con estimaciones. «Oficial», «verificado» o «independiente» solo se usa si la fuente sostiene realmente esa afirmación.
Clases de fuente
- Fuente pública del proveedor: API o fichas públicas como VS Code Marketplace, Open VSX, GitHub Releases, PyPI y Packagist.
- Conjunto de datos público / tercero de confianza: conjuntos nominados como PSF BigQuery o PypiStats.
- Telemetría del producto: el producto conectado envía eventos de ciclo de vida a Alveos (Beacon; Streaming Zebra próximamente). Las cifras vienen del producto y de la forma de contar del publisher — por eventos, no descargadas de un marketplace.
- Importación manual del publisher: por ejemplo datos de Publisher Hub. Permanecen separados de los contadores públicos de Gallery.
Significado de las métricas
Alveos guarda lo que la fuente entrega. Lo que no entrega no se captura aquí.
| Fuente | Entregado y capturado | Falta |
|---|---|---|
| VS Code Marketplace (Gallery) | Contadores públicos (downloadCount, install, updateCount) — adquisición |
Instalaciones actualmente activas: Gallery no las da; Alveos no las captura aquí |
| Open VSX | downloadCount (descargas VSIX) |
Instalaciones activas, usuarios únicos, desinstalaciones: ni entregadas ni capturadas |
| GitHub Releases | download_count de archivos de release |
Clones, repositorios privados, archivos fuente |
| PyPI / PypiStats | Descargas de archivos (serie diaria sin espejos) | Usuarios únicos e instalaciones, porque la fuente no los cuenta |
| Packagist | downloads.total / monthly |
Instalaciones y usuarios únicos |
| Beacon / ciclo de vida | Eventos install, update, uninstall, usage y build del producto | Contadores de marketplace; uninstall a menudo incompleto |
| Publisher Hub (importación) | Días Daily Stats que aporta el publisher | No es SSOT de Gallery; VSIX de sitio solo si el archivo tiene la columna |
Contadores con significado distinto no se presentan en silencio como la misma métrica.
Recogida, actualidad y huecos
Alveos consulta los stores públicos una vez al día a las 05:20 Europe/Berlin. Guarda el día UTC de hoy. Un fallo salta el día, conserva el historial y no escribe ceros. Gallery, Open VSX, GitHub, PyPI-JSON, PypiStats y Packagist no se rellenan tres días hacia atrás.
En el gráfico: desde el primer día guardado, la línea continua se queda en el último valor conocido (step-hold). Si falta una consulta, Alveos dibuja el mismo valor a trazos — último stock, no una previsión ni una curva de tendencia sobre los puntos reales. Los días faltantes en la ventana se marcan. Los días anteriores a la conexión no son huecos.
Si el último día correcto tiene dos o tres días, la serie está retrasada; desde el cuarto día está obsoleta. Es una etiqueta de pantalla, no un relleno.
Dos excepciones reescriben días recientes si la siguiente consulta funciona: Streaming Zebra guarda D−2 y D−1 del resumen; países PyPI (BigQuery, tarifas de pago) reescriben los últimos siete días UTC. Importación y Beacon no son consulta diaria y no se puntúan como huecos perdidos.
Transformaciones y comparabilidad
Alveos conserva los enteros brutos del proveedor y etiqueta valores derivados: diferencias de contadores acumulativos, sumas, ratios, importaciones y particiones filtradas. Los canales de entrega directa y GitHub que pueden describir la misma entrega se mantienen separados. Las actualizaciones de Streaming Zebra y Beacon no se suman dos veces.
Exportaciones reproducibles
CSV y JSON incluyen proveedor, ID externo, clase, significado, inicio de cobertura, cadencia, versión de transformación, URL y un hash SHA-256 de fila. Los snapshots históricos tienen precisión de día UTC: fetched_on contiene el día, time_precision es day, y fetched_at queda vacío en lugar de inventar una hora.
Referencias de proveedores
| Fuente | Consulta | Cadencia |
|---|---|---|
| VS Code Gallery, Open VSX, GitHub Releases, PyPI-JSON, PypiStats, Packagist | El cron guarda el día UTC de hoy | Diario 05:20 Europe/Berlin |
| Países PyPI (BigQuery, tarifas de pago) | Upsert de los últimos siete días UTC | El mismo cron |
| Streaming Zebra (próximamente) | Resumen; repara D−2 y D−1 | El mismo cron |
| Beacon | El producto envía | Por eventos, no consulta diaria |
| Publisher Hub | Importación xlsx | En la importación |
- VS Code Marketplace
- Open VSX
- GitHub Release Assets API
- Datos públicos de PyPI en BigQuery
- API Packagist
Correcciones auditables
Titulares y personal con sesión informan bajo Correcciones de datos una conexión ya guardada: un día UTC, una métrica (descargas, instalaciones o actualizaciones), un entero propuesto y un motivo. La solicitud congela el valor bruto observado. Una corrección no rellena una consulta fallida ni escribe una estimación en un hueco. No hay importación de correcciones ni API de corrección.
Otra persona debe aceptar antes de que los lectores vean el número nuevo. La instantánea del proveedor no cambia. Gráficos y totales leen la capa activa. Un día ausente sigue siendo un hueco.
Marca en la exportación
CSV y JSON conservan las columnas de métricas. En una fila corregida son los valores de la capa, no los enteros obtenidos del proveedor.
| Columna | Fila corregida | Fila sin corregir |
|---|---|---|
correction_applied |
1 |
0 |
correction_request_ids |
Ids de las solicitudes aceptadas, separados por comas | vacío |
corrected_fields |
installs, downloads y/o updates |
vacío |
correction_original_json |
JSON de los enteros del proveedor sustituidos, por ejemplo {"downloads":120} |
vacío |
row_hash es el SHA-256 de esa fila de exportación, incluidos los números de la capa y estas cuatro columnas. Compare correction_original_json con el proveedor cuando necesite el entero obtenido.
Preguntas o posibles errores de datos: support@alveos.eu.