Observabilidade do Cortex Framework
Para executar e operar plataformas de dados corporativas com sucesso, é fundamental ter visibilidade da execução do pipeline, da qualidade de dados e dos erros operacionais.
O Cortex Framework categoriza a observabilidade em dois ciclos de vida distintos:
- Observabilidade no momento da implantação: rastreamento do carregamento da configuração, da compilação do modelo, das verificações de validação, das ações de implantação e da telemetria da API durante a execução das ferramentas da CLI.
- Observabilidade no momento da execução: rastreamento da execução, do progresso do pipeline, da performance da consulta, das declarações de qualidade de dados e dos alertas automatizados para os pipelines de dados implantados em Google Cloud.
Observabilidade no momento da implantação
A observabilidade no momento da implantação se concentra na execução das ferramentas da CLI (por exemplo, uv run cortex-build, uv run cortex-deploy, uv run cortex-build-and-deploy, uv run cortex-demo, uv run cortex-kc-sync).
Registro do console local
Quando você executa comandos da CLI, o Cortex Framework registra o progresso diretamente no console (stdout).
- Nível de registro: por padrão, os registros são gerados no nível
INFO. - Destaques visuais: as mensagens são codificadas por cores para destacar erros e avisos dinamicamente:
- ❌ Erros (vermelho) indicam falhas críticas que interrompem a execução.
- ⚠️ Avisos (laranja) indicam possíveis anomalias de configuração ou problemas não bloqueadores.
- Carimbo de data/hora e origem: cada linha de registro mostra o tempo de execução e os nomes de classe ou módulo do Python ativos para um rastreamento preciso.
Arquivos de registro locais persistentes
Em cada execução de comando, o orquestrador do Python transmite automaticamente o registro de execução completo para um arquivo de registro temporário no diretório temporário do sistema:
/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log
O caminho exato é impresso no console durante a inicialização das ferramentas da CLI. Esses arquivos contêm detalhes abrangentes do registro (incluindo rastreamentos de pilha para erros inesperados) e são muito úteis para depurar problemas encontrados durante a execução das ferramentas da CLI ou quando você está anexando a solicitações de suporte.
Google Cloud Validação do ambiente
Antes de realizar ações de build, implantação ou sincronização, o mecanismo de orquestração executa o utilitário GcpEnvironmentChecker. Essa verificação valida:
- APIs necessárias: confirma se as APIs Google Cloud cruciais estão ativadas (por exemplo,
bigquery.googleapis.com,dataform.googleapis.com). - Existência do conjunto de dados: verifica se os conjuntos de dados brutos e de destino necessários existem ou podem ser criados.
- Locais e regiões: garante que os conjuntos de dados de destino correspondam às regiões geográficas dos conjuntos de dados de origem.
- Capacidade e configurações: valida as configurações de reserva e as configurações de catálogo.
Qualquer incompatibilidade é registrada como um erro com dicas recomendadas sobre como resolvê-las antes de fazer Google Cloud chamadas de serviço.
Telemetria
Durante os processos de implantação e sincronização, o Cortex Framework registra a telemetria anônima de adoção, variante e versão do framework em Google Cloud. Para mais detalhes sobre como isso funciona e instruções sobre como desativar, consulte Telemetria.
Observabilidade no momento da execução
Depois de criadas e implantadas, as camadas de dados e os produtos de dados em conformidade com o Cortex Framework são executados inteiramente no Dataform e no BigQuery. Como resultado, a observabilidade de execução é integrada diretamente aos conjuntos operacionais. Google Cloud
Registro de execução do pipeline
Todos os pipelines implantados são rastreados usando Cloud Logging e as ferramentas de execução:
- Registros de execução do Dataform: o Dataform registra todos os eventos de compilação e execução. Esses detalhes podem ser acessados no Google Cloud console ou programaticamente usando a API Dataform.
- Histórico de jobs do BigQuery: cada tabela e visualização materializada pelos pipelines do Dataform executa consultas SQL no BigQuery. O uso detalhado de recursos, a performance da consulta, os bytes processados e os carimbos de data/hora de execução são registrados no histórico de jobs do BigQuery.
Monitoramento de pipeline
É possível monitorar a integridade do pipeline, as configurações de versão e o histórico de execução visual ou programaticamente:
- Interface da Web do Dataform: acesse o console do Dataform para:
- Inspecionar modelos de dados compilados e visualizar o gráfico compilado.
- Verificar o status das configurações de versão, dos modelos compilados e dos ambientes ativos.
- Monitorar o histórico e os detalhes das execuções de fluxo de trabalho atuais e anteriores.
- Integração do Cloud Monitoring: rastreie as métricas do pipeline do Dataform, como durações de execução, compilações ativas e taxas de falha de jobs de fluxo de trabalho, usando painéis personalizados.
Alertas e qualidade de dados
Para garantir a integridade dos dados e sinalizar falhas de pipeline automaticamente, configure alertas usando os seguintes mecanismos:
Declarações de qualidade de dados
É possível definir regras de validação de dados personalizadas (por exemplo, garantir que uma coluna nunca seja nula, verificar se as chaves primárias são exclusivas ou validar intervalos numéricos) criando arquivos de declaração .sqlx.
- É possível fornecer um arquivo de declarações personalizado usando o
--assertionsparâmetro:bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx - Durante a execução do pipeline, o Dataform executa essas consultas de validação. Se uma consulta de declaração retornar uma ou mais linhas, a validação falhará e a execução do pipeline será marcada imediatamente como falha.
- Para mais informações sobre como escrever regras de validação de dados, consulte a documentação oficial de declarações do Dataform.
Exemplo de arquivo de declaração (assertions.sqlx)
Exemplo de uma consulta de declaração do Dataform que verifica valores NULL e registros de clientes duplicados. Se essa consulta retornar linhas, a declaração vai falhar e interromper o fluxo de trabalho de execução:
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 alerta do Cloud
Configure políticas de alerta padrão Google Cloud Alerting Policies para notificar suas equipes de engenharia ou operações quando surgirem problemas:
- Alertas baseados em registros: crie alertas no Cloud Logging que são acionados quando eventos de erro, execuções de fluxo de trabalho com falha ou problemas do compilador são detectados nos registros.
- Alertas baseados em métricas: defina limites no Cloud Monitoring com base na duração da execução ou em falhas de compilação.
- Canais de notificação: configure esses alertas para encaminhar problemas aos canais de comunicação preferidos da sua equipe.