Observabilidad de Cortex Framework

Para ejecutar y operar con éxito plataformas de datos de nivel empresarial, es fundamental tener visibilidad de la ejecución de la canalización, la calidad de los datos y los errores operativos.

Cortex Framework categoriza la observabilidad en sus dos ciclos de vida distintos:

  1. Observabilidad en el momento de la implementación: Supervisa la carga de configuración, la compilación de plantillas, las verificaciones de validación, las acciones de implementación y la telemetría de la API durante la ejecución de las herramientas de CLI.
  2. Observabilidad en el momento de la ejecución: Supervisa la ejecución, el progreso de la canalización, el rendimiento de las consultas, las aserciones de calidad de los datos y las alertas automatizadas para las canalizaciones de datos implementadas que se ejecutan dentro de Google Cloud.

Observabilidad en el momento de la implementación

La observabilidad en el momento de la implementación se centra en la ejecución de las herramientas de CLI (p.ej., uv run cortex-build, uv run cortex-deploy, uv run cortex-build-and-deploy, uv run cortex-demo, uv run cortex-kc-sync).

Registro de la consola local

Cuando ejecutas comandos de CLI, Cortex Framework registra el progreso directamente en la consola (stdout).

  • Nivel de registro: De forma predeterminada, los registros se generan en el nivel INFO.
  • Resaltados visuales: Los mensajes están codificados por colores para resaltar errores y advertencias de forma dinámica:
    • ❌ Errores (rojo) que indican fallas críticas que detienen la ejecución.
    • ⚠️ Advertencias (naranja) que indican posibles anomalías de configuración o problemas que no bloquean.
  • Marca de tiempo y fuente: Cada línea de registro muestra la hora de ejecución y los nombres de la clase o el módulo de Python activos para un seguimiento preciso.

Archivos de registro locales persistentes

En cada ejecución de comandos, el orquestador de Python transmite automáticamente el registro de ejecución completo a un archivo de registro temporal en el directorio temporal de tu sistema:

/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log

La ruta de acceso precisa se imprime en la consola durante el inicio de las herramientas de CLI. Estos archivos contienen detalles de registro integrales (incluidas las seguimientos de pila para errores inesperados) y son muy valiosos para depurar problemas que se producen durante la ejecución de las herramientas de CLI o cuando te comunicas con las solicitudes de asistencia.

Google Cloud Validación del entorno

Antes de realizar acciones de compilación, implementación o sincronización, el motor de orquestación ejecuta la utilidad GcpEnvironmentChecker. Esta verificación valida lo siguiente:

  1. APIs requeridas: Confirma que las APIs Google Cloud cruciales estén habilitadas (p.ej., bigquery.googleapis.com, dataform.googleapis.com).
  2. Existencia del conjunto de datos: Verifica que existan los conjuntos de datos sin procesar y de destino requeridos o que se puedan crear.
  3. Ubicaciones y regiones: Asegura que los conjuntos de datos de destino coincidan con las regiones geográficas de los conjuntos de datos de origen.
  4. Capacidad y configuración: Valida la configuración de reservas y las configuraciones de catálogos.

Cualquier falta de coincidencia se registra como un error con sugerencias recomendadas sobre cómo resolverlos antes de realizar Google Cloud llamadas de servicio.

Telemetría

Durante los procesos de implementación y sincronización, Cortex Framework registra la telemetría anónima de adopción, variante y versión del framework en Google Cloud. Para obtener detalles sobre cómo funciona y las instrucciones para inhabilitarla, consulta Telemetría.

Observabilidad en el momento de la ejecución

Una vez compiladas e implementadas, las capas de datos y los productos de datos conformes de Cortex Framework se ejecutan por completo en Dataform y BigQuery. Como resultado, la observabilidad en el momento de la ejecución se integra directamente con Google Cloud las suites operativas.

Registro de ejecución de canalizaciones

Todas las canalizaciones implementadas se supervisan con Cloud Logging y herramientas de ejecución:

  • Registros de ejecución de Dataform: Dataform registra cada evento de compilación y ejecución. Se puede acceder a estos detalles en la Google Cloud consola o de forma programática con la API de Dataform.
  • Historial de trabajos de BigQuery: Cada tabla y vista materializada por tus canalizaciones de Dataform ejecuta consultas de SQL dentro de BigQuery. El uso detallado de recursos, el rendimiento de las consultas, los bytes procesados y las marcas de tiempo de ejecución se registran en el historial de trabajos de BigQuery.

Supervisión de canalizaciones

Puedes supervisar el estado de la canalización, la configuración de lanzamiento y el historial de ejecución de forma visual o programática:

  1. IU web de Dataform: Navega a la consola de Dataform para hacer lo siguiente:
    • Inspeccionar los modelos de datos compilados y visualizar el gráfico compilado
    • Verificar el estado de las configuraciones de lanzamiento, las plantillas compiladas y los entornos activos
    • Supervisar el historial y los detalles de las ejecuciones de flujo de trabajo actuales y anteriores
  2. Integración de Cloud Monitoring: Supervisa las métricas de canalización de Dataform, como las duraciones de ejecución, las compilaciones activas y las tasas de fallas de trabajos de flujo de trabajo, a través de paneles personalizados.

Alertas y calidad de los datos

Para garantizar la integridad de los datos y marcar automáticamente las fallas de la canalización, configura las alertas con los siguientes mecanismos:

Aserciones de calidad de los datos

Puedes definir reglas de validación de datos personalizadas (p.ej., asegurarte de que una columna nunca sea nula, verificar que las claves primarias sean únicas o validar rangos numéricos) mediante la creación de archivos de aserción .sqlx.

  • Puedes proporcionar un archivo de aserciones personalizado con el --assertions parámetro: bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx
  • Durante la ejecución de la canalización, Dataform ejecuta estas consultas de validación. Si una consulta de aserción muestra una o más filas, la validación falla y la ejecución de la canalización se marca de inmediato como fallida.
  • Para obtener más información sobre cómo escribir reglas de validación de datos, consulta la documentación oficial de aserciones de Dataform.

Archivo de aserciones de ejemplo (assertions.sqlx)

Ejemplo de una consulta de aserción de Dataform que verifica los valores NULL y los registros de clientes duplicados. Si esta consulta muestra filas, la aserción fallará y detendrá el flujo de trabajo de ejecución:

config {
  type: "assertion",
  description: "Ensure customer_number_kunnr is not null and unique"
}

-- Check for NULL values
(
  SELECT
    "customer_number_kunnr is NULL" AS error_message
  FROM
    ${ref("customers")}
  WHERE
    customer_number_kunnr IS NULL
)
UNION ALL
-- Check for duplicate keys
(
  SELECT
    CONCAT("Duplicate customer number found: ", customer_number_kunnr) AS error_message
  FROM
    ${ref("customers")}
  GROUP BY
    customer_number_kunnr,
    client_mandt
  HAVING
    COUNT(*) > 1
)

Políticas de Cloud Alerting

Configura Google Cloud políticas de alertas estándar para notificar a tus equipos de ingeniería o de operaciones cuando surjan problemas:

  • Alertas basadas en registros: Crea alertas en Cloud Logging que se activen cuando se detecten eventos de error, ejecuciones de flujo de trabajo fallidas o problemas del compilador en tus registros.
  • Alertas basadas en métricas: Define umbrales en Cloud Monitoring según la duración de la ejecución o las fallas de compilación.
  • Canales de notificaciones: Configura estas alertas para enrutar los problemas a los canales de comunicación preferidos de tu equipo.