Monitorar registros do Catálogo de Conhecimento

Este documento explica como acessar, consultar e interpretar os registros do Knowledge Catalog (antigo Dataplex Universal Catalog) usando o Cloud Logging. O acesso aos registros de jobs e serviços do Knowledge Catalog permite solucionar problemas e monitorar atividades de gerenciamento de dados, incluindo a descoberta de dados com tecnologia de IA e a verificação de qualidade de dados.

Ao centralizar os registros no Logging, é possível analisar a performance do job, configurar alertas para falhas ou anomalias e encaminhar registros para outros Google Cloud serviços, como o BigQuery, para retenção e análise de longo prazo.

Para entender os custos, consulte Preços do Google Cloud Observability.

Para mais informações sobre a retenção de registros, consulte Períodos de armazenamento de registros.

Para desativar todos os registros ou excluir registros do Logging, consulte Filtros de exclusão.

Para encaminhar registros do Logging para o Cloud Storage, o BigQuery ou o Pub/Sub, consulte Visão geral de roteamento e armazenamento.

Casos de uso

O registro do Knowledge Catalog oferece suporte a casos de uso em diferentes setores:

  • Solução de problemas de falhas no pipeline de dados:quando uma tarefa do Knowledge Catalog para processamento de dados falha, os registros process fornecem mensagens de erro detalhadas que ajudam os engenheiros de dados a identificar e resolver problemas nos jobs do Spark ou nas tarefas personalizadas.
  • Monitorar a qualidade dos dados:uma empresa de serviços financeiros pode monitorar os registros data_quality_scan_rule_result para acompanhar as tendências de qualidade de dados ao longo do tempo, receber alertas sobre degradações de qualidade para ativos de dados críticos e fornecer aos auditores evidências de verificações de qualidade de dados para conformidade regulatória.
  • Acompanhar o enriquecimento de metadados:uma empresa de varejo que usa jobs de importação de metadados para enriquecer o catálogo pode usar registros metadata_job para verificar se as importações estão sendo concluídas e se todos os itens de metadados estão sendo processados corretamente.
  • Auditoria da descoberta de dados:as organizações podem usar registros discovery para monitorar como e quando novas fontes de dados estão sendo descobertas e registradas no Knowledge Catalog, fornecendo uma trilha de auditoria para processos de integração de dados.

Como funciona o registro do Knowledge Catalog

O Knowledge Catalog envia registros de operações de serviço e execuções de jobs para o Cloud Logging. Cada entrada de registro contém detalhes sobre a operação ou o job, como status, hora de início e término, recursos associados (como uma verificação ou tarefa de dados) e resultado. Diferentes tipos de operações, como verificação de dados, descoberta, importação de metadados e processamento de dados, geram tipos de registro diferentes, que podem ser consultados usando logName ou a linguagem de consulta de registro no Logging.

É possível acessar e analisar esses registros usando a Análise de registros no Google Cloud console ou encaminhando-os para outros destinos, como buckets do Cloud Storage ou tabelas do BigQuery, para análise mais detalhada.

Tipos de registro do Knowledge Catalog

O Knowledge Catalog publica os seguintes registros de serviço no Cloud Logging.

Tipo de registro Nome do registro Consulta logName Descrição do registro
Registros de eventos de verificação de dados dataplex.googleapis.com/data_scan logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdata_scan) Logs de eventos no nível do job para jobs de verificação de dados (verificações de qualidade de dados e de perfil de dados) que indicam o estado, os resultados e as estatísticas do job
Registros de resultados de regras de verificação de qualidade de dados dataplex.googleapis.com/data_quality_scan_rule_result logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdata_quality_scan_rule_result) Resultados detalhados da avaliação no nível da regra para cada regra avaliada em um job de verificação de qualidade de dados
Registros de descoberta dataplex.googleapis.com/discovery logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdiscovery) Progresso e atualizações de descoberta em relação aos recursos em uma zona
Registros de jobs de metadados dataplex.googleapis.com/metadata_job logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job) Registros sobre jobs de importação de metadados e itens de importação no arquivo de importação de metadados
Registros de processos dataplex.googleapis.com/process logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fprocess) Execuções de jobs resultantes de tarefas de processamento de dados

Acessar registros de serviço do Knowledge Catalog

Para acessar a geração de registros, use a Análise de registros no Google Cloud console, os gcloud logging comandos, ou a API Logging. É possível usar a linguagem de consulta de registro para criar consultas detalhadas.

Permissões do IAM obrigatórias

Para visualizar e consultar registros, é necessário ter o papel de Leitor de registros (roles/logging.viewer) ou permissões equivalentes no projeto.

Visualizar registros no Google Cloud console

  1. No Google Cloud console, acesse a página Observabilidade > Logging > Explorador de registros.

    Acessar o "Explorador de registros"

  2. Configure os filtros Recurso e Nome do registro com base na tabela a seguir:

    Tipo de registro Seleção de recursos Seleção do nome do registro
    Eventos de verificação de dados Recurso auditado > Serviço: Cloud Dataplex dataplex.googleapis.com/data_scan
    Resultados de regras de verificação de qualidade de dados Recurso auditado > Serviço: Cloud Dataplex dataplex.googleapis.com/data_quality_scan_rule_result
    Registros de descoberta Zona do Cloud Dataplex dataplex.googleapis.com/discovery
    Registros de jobs de metadados Job de metadados do Cloud Dataplex dataplex.googleapis.com/metadata_job
    Registros de processos Tarefa do Cloud Dataplex dataplex.googleapis.com/process

  3. (Opcional) Selecione subfiltros específicos (como um ID de tarefa específico) para restringir a consulta.

  4. Clique em Aplicar e em Executar consulta.

Exemplos de filtragem de registros

É possível usar a linguagem de consulta de geração de registros no editor de consultas da Análise de registros ou com a Google Cloud CLI. Os exemplos a seguir demonstram como ler registros usando a CLI gcloud.

Exemplo: ler eventos de verificação de dados

Para ler entradas de log de eventos para verificações de qualidade de dados ou de perfil de dados, use o gcloud logging read comando com a seguinte consulta:

gcloud logging read \
    'resource.type="dataplex.googleapis.com/DataScan" AND
    logName=projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdata_scan AND
    resource.labels.location=LOCATION AND
    resource.labels.datascan_id=DATA_SCAN_ID'
    --limit 10

Exemplo: ler entradas de registro de processos

Para ler entradas de registro de processos, use o gcloud logging read comando com a seguinte consulta:

gcloud logging read \
    'resource.type="dataplex.googleapis.com/Task" AND
    logName=projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fprocess AND
    resource.labels.location=LOCATION AND
    resource.labels.lake_id=LAKE_ID AND
    resource.labels.task_id=TASK_ID'
    --limit 10

Exemplos de payloads de registro

Os exemplos a seguir mostram as estruturas de payload JSON para diferentes tipos de registros do Knowledge Catalog. É possível usar esses exemplos para entender a estrutura dos registros e criar filtros de registro.

Registros de eventos de verificação de dados

No Knowledge Catalog, as verificações de dados abrangem tanto verificações de qualidade de dados quanto verificações de perfil de dados. Quando você executa um job de verificação de dados de qualquer tipo, o Knowledge Catalog produz um registro de eventos data_scan no Logging que resume a execução geral do job.

O exemplo a seguir mostra o payload do registro de eventos para uma verificação de qualidade de dados:

{
  "insertId": "123456abcdef",
  "jsonPayload": {
    "dataQuality": {
      "passed": false,
      "rowsAnalyzed": "5000"
    },
    "dataSource": "//bigquery.googleapis.com/projects/my-project/datasets/my_dataset/tables/my_table"
  },
  "resource": {
    "type": "dataplex.googleapis.com/DataScan",
    "labels": {
      "datascan_id": "my-data-quality-scan",
      "location": "us-central1",
      "resource_container": "projects/1234567890"
    }
  },
  "severity": "INFO"
}

Registros de resultados de regras de verificação de qualidade de dados

Quando uma verificação de qualidade de dados é executada, o Knowledge Catalog gera um registro de eventos de verificação de dados e um registro de resultados de regras de verificação de qualidade de dados separado para cada regra avaliada no job.

Cada entrada de registro data_quality_scan_rule_result contém informações sobre a regra específica, incluindo a configuração da regra, a dimensão da avaliação, o status e as contagens de linhas.

O exemplo a seguir mostra um payload de registro de resultados de regras de verificação de qualidade de dados:

{
  "insertId": "123456abcdef",
  "jsonPayload": {
    "jobId": "my-data-quality-scan-job-123",
    "dataSource": "//bigquery.googleapis.com/projects/my-project/datasets/my_dataset/tables/my_table",
    "column": "user_id",
    "ruleName": "user-id-not-null",
    "ruleType": "NON_NULL_EXPECTATION",
    "ruleDimension": "COMPLETENESS",
    "thresholdPercent": 100,
    "result": "PASSED",
    "evaluatedRowCount": "5000",
    "passedRowCount": "5000",
    "nullRowCount": "0"
  },
  "resource": {
    "type": "dataplex.googleapis.com/DataScan",
    "labels": {
      "datascan_id": "my-data-quality-scan",
      "location": "us-central1",
      "resource_container": "projects/1234567890"
    }
  },
  "severity": "INFO"
}

Registros de descoberta

O exemplo a seguir mostra um payload de registro de descoberta:

{
  "insertId": "123456abcdef",
  "jsonPayload": {
    "message": "BigQuery table published successfully.",
    "lakeId": "my-lake",
    "zoneId": "my-zone",
    "assetId": "my-asset",
    "dataLocation": "gs://my-bucket/path/to/data",
    "type": "TABLE_PUBLISHED",
    "table": {
      "table": "projects/my-project/datasets/my_dataset/tables/my_table",
      "type": "EXTERNAL_TABLE"
    }
  },
  "resource": {
    "type": "dataplex.googleapis.com/Zone",
    "labels": {
      "lake_id": "my-lake",
      "zone_id": "my-zone",
      "location": "us-central1",
      "resource_container": "projects/1234567890"
    }
  },
  "severity": "INFO"
}

Registros de jobs de metadados

O exemplo a seguir mostra um payload de registro de job de metadados:

{
  "insertId": "123456abcdef",
  "jsonPayload": {
    "resource": "projects/my-project/locations/us-central1/metadataJobs/my-metadata-job",
    "message": "Metadata import job completed successfully.",
    "type": "IMPORT",
    "importResult": {
      "state": "SUCCEEDED",
      "stage": "INGESTION",
      "mutatedEntryGroups": "1",
      "createdEntries": "50",
      "updatedEntries": "10",
      "deletedEntries": "5"
    }
  },
  "resource": {
    "type": "dataplex.googleapis.com/MetadataJob",
    "labels": {
      "metadata_job_id": "my-metadata-job",
      "location": "us-central1",
      "resource_container": "projects/1234567890"
    }
  },
  "severity": "INFO"
}

Registros de processos

O exemplo a seguir mostra um payload de registro de processos:

{
  "insertId": "123456abcdef",
  "jsonPayload": {
    "message": "Spark job completed successfully.",
    "jobId": "my-task-job-123",
    "startTime": "2026-08-13T10:00:00Z",
    "endTime": "2026-08-13T10:05:00Z",
    "state": "SUCCEEDED",
    "type": "SPARK",
    "service": "DATAPROC",
    "serviceJob": "projects/my-project/regions/us-central1/jobs/dataproc-job-123",
    "executionTrigger": "TASK_CONFIG"
  },
  "resource": {
    "type": "dataplex.googleapis.com/Task",
    "labels": {
      "task_id": "my-task",
      "lake_id": "my-lake",
      "location": "us-central1",
      "resource_container": "projects/1234567890"
    }
  },
  "severity": "INFO"
}

Configurar alertas baseados em registros

É possível configurar alertas baseados em registros para receber notificações sempre que eventos específicos do Knowledge Catalog ocorrerem (como uma verificação de qualidade de dados com falha).

Para criar alertas baseados em registros, é necessário ter os papéis de Gravador de configuração de registros (roles/logging.configWriter) e Editor de AlertPolicy do Monitoring (roles/monitoring.alertPolicyEditor) ou permissões equivalentes.

  1. Execute uma consulta no Análise de registros que tenha como destino a condição de falha (por exemplo: resource.type="dataplex.googleapis.com/DataScan" AND NOT jsonPayload.dataQuality.passed=true).
  2. Acima do painel de resultados da consulta, clique em Criar alerta.
  3. No painel Criar alerta baseado em registros, insira um nome e uma descrição para a política de alertas.
  4. Clique em Próxima e configure os canais de notificação.
  5. Clique em Salvar.

Para mais informações, consulte Criar alertas baseados em registros.

A seguir