Filtrado de Ingesta

Descripción General

El filtrado de ingesta permite a los operadores de Horizon reducir drásticamente la huella de almacenamiento de los datos históricos en la base de datos de Horizon al incluir en la lista blanca los Activos y/o Cuentas que son relevantes para sus operaciones.

¿Por qué es útil:

Anteriormente, la única forma de limitar el almacenamiento de datos era limitando el rango temporal de la historia a través de retención continua (por ejemplo, los últimos 30 días). La función de filtrado permite a los usuarios almacenar un marco temporal histórico más largo en la base de datos de Horizon solo para los activos y cuentas en la lista blanca, y sus entidades históricas relacionadas (transacciones, operaciones, intercambios, etc.).

Para mayor contexto, ejecutar una instancia de Horizon con historia completa sin filtrar actualmente requiere más de 30 TB de espacio en disco (a partir de junio de 2023) con almacenamiento creciendo a una tasa de aproximadamente 1 TB/mes. Como referencia, filtrar incluso 100 de las cuentas y activos más activos reduce el almacenamiento en más del 90%. Para la mayoría de las aplicaciones que están interesadas en un conjunto aún más limitado de activos y cuentas, los ahorros de almacenamiento deberían ser superiores al 99%. Otros beneficios incluyen la reducción de costos operativos para mantener el almacenamiento, métricas de salud de la base de datos mejoradas y mayor rendimiento de consultas.

¿Cómo funciona:

La función de filtrado opera durante la ingesta en procesos de en vivo y de rango histórico. Indica al proceso de ingesta que solo acepte transacciones de ledger entrantes que coincidan con una regla de filtrado; cualquier transacción que no coincida con las reglas de filtrado es omitida por la ingesta y, por ende, no se almacena en la base de datos.

Algunos aspectos clave a tener en cuenta sobre el comportamiento del filtrado:

Si tanto los filtros de activo como de cuenta están habilitados y cada filtro tiene al menos una regla, entonces las transacciones se almacenan en la base de datos cuando cualquier regla de cualquiera de los filtros coincide con la transacción dada.
El filtrado se aplica únicamente a la ingesta de datos históricos en la base de datos, no afecta cómo el proceso de ingesta mantiene los datos del estado actual almacenados en la base de datos, que es la última entrada de ledger conocida para cada entidad única dentro de cuentas, líneas de confianza, fondos de liquidez, ofertas. Sin embargo, los datos del estado actual consumen una cantidad relativamente pequeña de la capacidad total de almacenamiento.
Cuando se cambian las reglas de filtrado, solo se aplican a procesos de ingesta existentes y en ejecución (en vivo y rango histórico). No activan ningún filtrado retroactivo ni llenado de los datos históricos existentes en la base de datos.
- Cuando las reglas de filtrado se actualizan para incluir cuentas o activos adicionales en la lista blanca, las transacciones relacionadas de la ingesta en vivo solo aparecerán en los datos históricos de la base de datos una vez que las reglas de filtrado hayan sido actualizadas usando la API de administración. Lo mismo se aplica a la ingesta de rango histórico, donde las nuevas reglas de filtrado solo afectarán los datos del ledger actual dentro de su rango configurado en el momento de la actualización.
- Actualizar las reglas de filtrado para incluir cuentas o activos adicionales no activa el llenado automático relacionado con nuevas entidades en la base de datos histórica. Para incluir la historia previa de las entidades recién incluidas en la lista blanca en la base de datos, puedes ejecutar manualmente un nuevo Rango de Ingesta Histórica después de actualizar las reglas de filtrado.
- Cuando las reglas de filtrado se actualizan para eliminar cuentas o activos previamente definidos en la lista blanca, los datos históricos en la base de datos no serán eliminados ni filtrados retroactivamente en función de las reglas actualizadas. Los datos se almacenan en las tablas de historia durante la duración de la base de datos o hasta que se supere el HISTORY_RETENTION_COUNT. Una vez alcanzado el límite de retención, Horizon eliminará todos los datos históricos relacionados con los ledgers más antiguos, independientemente de las reglas de filtrado.
El filtrado no afectará el rendimiento o la tasa de rendimiento de un proceso de ingesta; permanecerá consistente sin importar si las reglas de filtrado están presentes o no.

Las reglas de filtrado definen listas blancas de las siguientes entidades admitidas:

ID de cuenta
ID de activo (canónico)

Dado que todas las transacciones relacionadas con las entidades incluidas en la lista blanca están incluidas, todos los datos de series temporales históricas relacionadas con esas transacciones se guardan en la base de datos de historia de Horizon, incluyendo la transacción misma, todas las operaciones en la transacción, y las referencias a cualquier entidad auxiliar de las operaciones.

Configuración:

El filtrado está habilitado por defecto sin reglas de filtrado definidas. Cuando no se definen reglas de filtrado, esto significa que no se realiza filtrado de los datos ingresados. Para comenzar a filtrar la ingesta, necesitas definir al menos una regla de filtrado:

habilita el puerto de administración de Horizon con el parámetro de configuración ambiental ADMIN_PORT=XXXXX, esto te permitirá acceder al puerto.
define las listas blancas de filtrado. envía solicitudes de API HTTP de administración para ver y actualizar las reglas de filtrado:

Consulta los Documentos de la API de Administración de Horizon que también están publicados en las instancias de Horizon en ejecución como documento Open API 3.0 en el puerto de administración cuando está habilitado en http://localhost:<admin_port>/. Puedes pegar el contenido de esa URL en cualquier herramienta OAPI, como Swagger, que renderizará un explorador visual de los puntos finales de la API. En el editor de Swagger, también puedes cargar el admin.oapi.yml publicado de Horizon directamente como una URL, selecciona Archivo->Importar URL:
```
 https://raw.githubusercontent.com/stellar/go/master/services/horizon/internal/httpx/static/admin_oapi.yml
```
Sigue los detalles y ejemplos de cargas útiles de solicitud/respuesta para leer y actualizar las reglas de filtrado para estos puntos finales:
```
/ingestion/filters/account
/ingestion/filters/asset
```
Elegir el botón Prueba de cualquiera de los puntos finales mostrará ejemplos de curl de toda la solicitud HTTP.

Ejemplo de Caso de Uso:

Como emisor de activos, he emitido 4 activos y estoy interesado en todos los datos de transacciones relacionados con esos activos, incluyendo las cuentas de clientes que interactúan con esos activos a través de las siguientes operaciones:

Operaciones
Efectos
Pagos
Saldos reclamables
Operaciones de cambio

Me gustaría almacenar la historia completa de todas las transacciones relacionadas desde el génesis de esos activos.

Requisitos Previos:

Has instalado Horizon con una base de datos vacía y tiene ingesta en vivo habilitada.

Pasos:

Configura una regla de filtrado con 4 activos en la lista blanca mediante el envío de la solicitud a la API ADMIN de Horizon <horizon_host>:<ADMIN_PORT>/ingestion/filters/asset.

curl -X 'PUT' \
  'http://localhost:4200/ingestion/filters/asset' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "whitelist": [
    "USDC:GAFRNZHK4DGH6CSF4HB5EBKK6KARUOVWEI2Y2OIC5NSQ4UBSN4DR456U",
    "DOTT:GAFRNZHK4DGH6CSF4HB5EBKK6KARUOVWEI2Y2OIC5NSQ4UBSN4DR456U",
    "ABCD:GAFRNZHK4DGH6CSF4HB5EBKK6KARUOVWEI2Y2OIC5NSQ4UBSN4DR456U",
    "EFGH:GAFRNZHK4DGH6CSF4HB5EBKK6KARUOVWEI2Y2OIC5NSQ4UBSN4DR456U"
  ],
  "enabled": true
}'

Dado que esta es una nueva base de datos de Horizon y las primeras reglas de filtrado, no hay nada más que hacer y aquí se detiene efectivamente.
Sin embargo, con fines de ejercicio, supongamos que ya tenías Horizon funcionando durante un tiempo y la base de datos se había poblado basada en algunas reglas de filtrado, y estas nuevas reglas eran listas blancas adicionales que acabas de agregar. En este caso, eliges si quieres llenar retroactivamente los datos históricos en la base de datos de Horizon para estas nuevas entidades en la lista blanca desde un tiempo anterior hasta el presente, porque originalmente fueron omitidos en el tiempo de ingesta anterior y no se incluyeron en la base de datos. Si decides que quieres llenar retroactivamente, entonces ejecutas un proceso de ingesta rango histórico separado, consulta Rango de Ingesta Histórica para los pasos:

Descripción General​

¿Por qué es útil:​

¿Cómo funciona:​

Configuración:​

Ejemplo de Caso de Uso:​

Requisitos Previos:​

Pasos:​