Solução de problemas.

Comece com o ID de execução e depois percorra as tabelas de controle. Evite depurar apenas a partir da saída do notebook; a evidência durável está em Delta.

Primeiras consultas

SELECT *
FROM ops.ctrl_ingestion_runs
WHERE run_id = '<run_id>';

SELECT stack_trace
FROM ops.ctrl_ingestion_errors
WHERE run_id = '<run_id>'
ORDER BY error_ts_utc DESC;

Falhas comuns

Credenciais ou rede indisponíveis

Verifique o âmbito secreto, o tipo de runtime, a localização externa, a política de rede e se o conector requer acesso do lado do condutor ou do lado do Spark.

O conector retornou HTTP 401 ou 403

Trate isso como determinístico. Verifique a credencial do provedor, a função, a permissão do site, o escopo da API, a política de rede do Snowflake ou a concessão de armazenamento de objetos. ContractForge não tenta novamente a maioria das respostas 4xx porque a nova tentativa não pode corrigir a autorização.

O conector retornou HTTP 429, 5xx ou tempo limite

Eles podem ser transitórios para conectores de driver Python. Revise source.limits.retry_attempts, source.limits.retry_backoff_seconds e source.limits.timeout_seconds e verifique os limites de taxa do provedor e a estabilidade da rede.

O conector de download de driver excedeu os limites

Inspecione source_limits_json e source_metrics_json. Se a origem exceder regularmente max_bytes, max_files ou max_records, coloque o feed no armazenamento de objetos e ingira-o com conectores de arquivo ou carregador automático.

A política de esquema bloqueou a execução

Inspecione ctrl_ingestion_schema_changes e decida se a alteração é esperada. Não afrouxe cegamente a política de esquema.

Falha na qualidade

Verifique ctrl_ingestion_quality e ctrl_ingestion_quarantine. As regras somente para abortar não podem ser colocadas em quarentena.

Marca d’água não avançou

As execuções ignoradas e com falha não atualizam o estado. Lotes vazios preservam o estado anterior.

Serverless não pode acessar o armazenamento

Use locais externos do catálogo do Unity ou política de rede do espaço de trabalho. A configuração direta de credenciais geralmente é um padrão de cluster clássico.

Campos de solução de problemas do conector

Os metadados do conector são persistidos com segredos editados. Comece com estas colunas antes de alterar um contrato:

SELECT
  run_id,
  source_connector,
  source_type,
  source_format,
  source_path,
  source_options_json,
  source_read_json,
  source_auth_json,
  source_limits_json,
  source_metrics_json,
  error_message
FROM ops.ctrl_ingestion_runs
WHERE run_id = '<run_id>';

Use source_metrics_json para distinguir o comportamento do conector do comportamento de gravação do Spark. Campos como runtime_strategy, read_strategy, bytes_read, records_read, files_read, pages_read e materialization_strategy estão presentes apenas quando o conector pode calculá-los sem uma varredura extra cara.

Lista de verificação do operador

1. Identifique run_id e status final.
2. Leia o breve error_message em ctrl_ingestion_runs.
3. Abra o rastreamento de pilha redigido completo em ctrl_ingestion_errors.
4. Verifique os metadados de origem e o tipo de runtime.
5. Verifique as tabelas de controle de qualidade e esquema.
6. Só então execute novamente, repare ou altere o contrato.