Consulta y retención de telemetry

Esta página es la referencia para leer telemetry de vuelta desde CORE-M y para los controles de gobierno de datos que la rodean: cuánto tiempo se conservan los datos, cómo se agregan en rollups, cómo se exportan y cómo se eliminan sin falsificar pruebas en blockchain. Para saber cómo se escriben los datos en primer lugar, consulta Enviar telemetry.

Consulta

CORE-M admite consultar múltiples dispositivos y múltiples métricas sobre un rango de tiempo, con agregación, downsampling, bucketing consciente del timezone y paginación. Una consulta devuelve una serie por cada par dispositivo/métrica.

Parámetros de consulta

Parámetro	Descripción
`devices`	Uno o más device IDs.
`metrics`	Uno o más nombres de métrica.
`start` / `end`	Límites del rango de tiempo (ISO 8601).
`aggregation`	Reducción por bucket, p. ej. `avg`, `min`, `max`, `sum`, `count`.
`interval`	Ancho del bucket, p. ej. `5m`, `1h`, `1d`.
`timezone`	Timezone de alineación de buckets (por defecto el timezone del tenant).
`fill`	Cómo se representan los buckets faltantes (fill policy).

POST /api/v1/telemetry  (query via QueryTelemetrySeries)
{
  "devices": ["D1", "D2"],
  "metrics": ["temperature", "humidity"],
  "start": "2026-05-01T00:00:00Z",
  "end": "2026-05-08T00:00:00Z",
  "aggregation": "avg",
  "interval": "5m"
}

Alineación de buckets por timezone

Cuando un interval de agregación es una unidad de calendario (un día, por ejemplo), los límites de bucket se alinean con los días locales del tenant, no con UTC. Una consulta diaria que abarca una transición de horario de verano sigue produciendo buckets de día local correctamente alineados, y la respuesta lleva metadata de timezone para que el cliente pueda interpretarlos.

Límites de tamaño de consulta

Una consulta que devolvería más puntos en crudo que el max_query_points del tenant se rechaza en lugar de servirse parcialmente.

Condición	Resultado
Resultado estimado dentro de `max_query_points`	La consulta se ejecuta
Resultado estimado excede `max_query_points`	`RESOURCE_EXHAUSTED`; la respuesta sugiere un `interval` más grueso que satisfaría el límite

Rollups y agregados continuos

CORE-M mantiene rollups con downsampling en resoluciones fijas para que los dashboards y las consultas de rango largo nunca escaneen telemetry en crudo.

Resolución	Uso
`1m`	Vistas de rango corto y alto detalle
`5m`	Vistas de rango medio
`1h`	Vistas de varios días a varias semanas
`1d`	Vistas de varios meses

Los rollups se calculan como agregados continuos de TimescaleDB y se indexan en Aerospike (namespace telemetry, set rollups).
Un scheduler refresca los agregados a medida que llega nueva telemetry y actualiza la métrica corem_telemetry_rollup_lag_seconds.
El planner de consultas selecciona el rollup apropiado automáticamente. Por ejemplo, una petición horaria de 90 días se resuelve contra el rollup 1h, y la metadata de la respuesta reporta source="rollup_1h".

Políticas de retención

La retención está guiada por políticas y se aplica por selector. Una política nunca elimina registros de prueba en blockchain necesarios para verificar datos ya anclados.

Campos de la política

Campo	Significado
`policy_id`	Identificador de la política
`tenant_id`	Tenant propietario
`selector`	A qué apunta la política — dispositivo, grupo/perfil, métrica o tag
`raw_retention_days`	Cuánto tiempo se conserva la telemetry en crudo
`rollup_retention_days`	Cuánto tiempo se conservan los rollups
`proof_retention`	Retención de los registros de prueba (preservada de forma independiente de los datos en crudo)
`delete_behavior`	Qué hace la limpieza al expirar: redact, delete o archive
`legal_hold`	Si está activo, suspende toda eliminación para el selector
`created_at` / `updated_at`	Timestamps de audit

Comportamiento

Escenario	Resultado
Telemetry en crudo más allá de `raw_retention_days`, el punto es final	Las filas en crudo de TimescaleDB pueden eliminarse; la fila de prueba y la metadata de prueba portable permanecen; el registro de proof lifecycle permanece o se compacta a un resumen final
Selector bajo legal hold	No se elimina ningún dato raw, rollup, prueba, alarma ni audit; la limpieza reporta un conteo `skipped_legal_hold`
Política actualizada (p. ej. 90 → 365 días)	La limpieza futura usa el nuevo valor; el evento de audit `retention.policy.updated` registra los valores antiguo y nuevo

Legal hold

legal_hold en un selector congela la eliminación por completo. Mientras un dispositivo, grupo o tenant esté bajo hold, la limpieza de retención omite toda su telemetry en crudo, rollups, pruebas, alarmas y datos de audit, y reporta el conteo omitido en las métricas de limpieza. Levantar el hold reanuda la limpieza normal guiada por políticas.

Jobs de export

Los exports son jobs asíncronos que cubren telemetry, rollups, alarmas, audit logs y bundles de prueba. Los registros de job viven en el namespace telemetry de Aerospike, set export_jobs, con clave {tenant_id}:{job_id}.

Paso	Comportamiento
Create	Requiere el permiso `exports`; el job se crea con `status="queued"` y se publica el evento `export.requested.{tenant}.{job}`
Build	Un worker escribe un manifiesto de archivos de telemetry más referencias de bundle de prueba (cuando `include_proofs=true`)
Size guard	Si el tamaño estimado excede `max_export_size_bytes`, el job se rechaza con `RESOURCE_EXHAUSTED`, devolviendo `estimated_size_bytes` y `max_export_size_bytes`
Download	El job completado expone una URL de descarga firmada y con expiración (p. ej. 24 h); tras la expiración, un usuario autorizado puede regenerar una

Eliminación de cumplimiento con preservación de pruebas

La eliminación operacional y la preservación de pruebas inmutables están deliberadamente separadas. Eliminar telemetry por cumplimiento no debe falsificar ni remover los hechos de prueba en blockchain.

Escenario	Resultado
Redactar un campo personal (p. ej. `operator_name`) de un dispositivo	Las APIs de consulta dejan de devolver el campo; los registros de prueba conservan los hashes y la metadata necesarios para probar la existencia histórica; la verificación revela que el payload en crudo ya no se retiene
Solicitar la eliminación de una fila de prueba final	Rechazado. El sistema rechaza la eliminación directa de pruebas, sugiere flujos de redacción/export y escribe el evento de audit `proof.delete.denied`

Consulta Seguridad y cumplimiento para los flujos de derechos del titular de los datos y el rastro de audit en torno a la eliminación.

Quotas de tenant

Las quotas se aplican por recurso y rechazan con RESOURCE_EXHAUSTED cuando se exceden. Son distintas del rate limit de peticiones por tenant del gateway (consulta Visión general de la API).

Quota	Se aplica sobre
Tasa de ingesta	Puntos por minuto aceptados en la ingesta
Almacenamiento	Total de bytes almacenados por tenant
Rango de consulta	`max_query_points` por consulta
Tamaño de export	`max_export_size_bytes` por job de export
Conexiones de dashboard	Conexiones WebSocket concurrentes
Peticiones de API	Tasa de peticiones por tenant
Backlog de anchoring	Lotes (batch) pendientes por tenant

Escenario	Resultado
Quota de ingesta excedida	La petición de telemetry se rechaza con `RESOURCE_EXHAUSTED`; no se crea ningún registro de proof lifecycle; `corem_quota_rejections_total{quota="ingest_points"}` se incrementa
Almacenamiento al 85% de la quota	Se publica el evento `quota.warning.{tenant}.storage`; los admins del tenant ven una advertencia en settings

Contadores de uso

CORE-M rastrea el uso por tenant para poder razonar sobre quotas y facturación.

Contador	Granularidad	Descripción
Puntos ingeridos	por día	Puntos de datos aceptados por tenant por día
Almacenamiento	por día	Bytes almacenados por tenant por día