Monitorar registros do Catálogo de Conhecimento

Neste documento, explicamos como acessar, consultar e interpretar os registros do Knowledge Catalog (antigo Dataplex Universal Catalog) usando o Cloud Logging. Acessar os registros de jobs e serviços do Knowledge Catalog permite resolver 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 o desempenho do job, configurar alertas para falhas ou anomalias e rotear registros para outros serviços do Google Cloud 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 rotear registros do Logging para o Cloud Storage, o BigQuery ou o Pub/Sub, consulte Visão geral de roteamento e armazenamento.

Casos de uso

Os registros do Knowledge Catalog são compatíveis com casos de uso em diferentes setores:

  • Resolver falhas no pipeline de dados:quando uma tarefa do Knowledge Catalog para tratamento de dados falha, os registros do 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 do data_quality_scan_rule_result para acompanhar as tendências de qualidade dos dados ao longo do tempo, receber alertas sobre degradações de qualidade em recursos de dados críticos e fornecer aos auditores evidências de verificações de qualidade de dados para conformidade regulatória.
  • Rastrear o enriquecimento de metadados:uma empresa de varejo que usa jobs de importação de metadados para enriquecer o catálogo pode usar os registros do metadata_job para verificar se as importações estão sendo concluídas com sucesso e se todos os itens de metadados estão sendo processados corretamente.
  • Auditoria de descoberta de dados:as organizações podem usar os registros do 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 os processos de integração de dados.

Como funciona a geração de registros 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, horário de início e término, recursos associados (como uma verificação de dados ou tarefa) e resultado. Diferentes tipos de operações, como verificação de dados, descoberta, importação de metadados e tratamento de dados, geram diferentes tipos de registro, que podem ser consultados usando o logName ou a linguagem de consulta do Logging no Logging.

É possível acessar e analisar esses registros usando a Análise de registros no console doGoogle Cloud ou roteando-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 logName consulta Descrição do registro
Logs de eventos de verificação de dados dataplex.googleapis.com/data_scan logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdata_scan) Registros de eventos no nível do job para jobs de verificação de dados (verificações de qualidade, perfil e insights de dados) que indicam o estado, os resultados e as estatísticas do job
Registros de resultados da regra 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 da descoberta e atualizações de 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 tratamento de dados

Acessar registros do serviço Knowledge Catalog

Para acessar o Logging, use a Análise de Registros no console doGoogle Cloud , os comandos gcloud logging ou a API Logging. É possível usar a linguagem de consulta do Logging para criar consultas detalhadas.

Permissões do IAM obrigatórias

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

Ver registros no console do Google Cloud

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

    Acessar a Análise 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 de nome de registro
    Eventos de verificação de dados Recurso auditado > Serviço: Cloud Dataplex dataplex.googleapis.com/data_scan
    Resultados da regra 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 sua consulta.

  4. Clique em Aplicar e em Executar consulta.

Exemplos de filtragem de registros

É possível usar a linguagem de consulta do Logging 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 registro de eventos para verificações de qualidade ou perfil de dados, use o comando gcloud logging read 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 processo

Para ler as entradas de registro do processo, use o comando gcloud logging read 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. Use esses exemplos para entender a estrutura dos registros e criar filtros de registro.

Logs de eventos de verificação de dados

No Knowledge Catalog, as verificações de dados abrangem verificações de qualidade de dados, verificações do perfil de dados e verificações de insights de dados. Quando você executa um job de verificação de dados, o Knowledge Catalog grava um log de eventos data_scan no Logging que resume a execução geral do job. Para verificações de insights de dados bem-sucedidas (jsonPayload.type="DATA_DOCUMENTATION"), o log de eventos também inclui um bloco billableTokenUsage. Para informações sobre como consultar e gerar gráficos do consumo de tokens de insights de dados, consulte Monitorar o uso de tokens de insights de dados.

O exemplo a seguir mostra um payload de 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 da regra de verificação de qualidade de dados

Quando uma verificação de qualidade de dados é executada, o Knowledge Catalog gera um log de eventos de verificação de dados e um log de resultados de regras de verificação de qualidade de dados separado para cada regra individual 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 de avaliação, o status e as contagens de linhas.

O exemplo a seguir mostra um payload de registro de resultado de regra 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 processo:

{
  "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 ocorrerem eventos específicos do Knowledge Catalog (como uma verificação de qualidade de dados com falha).

Para criar alertas com base em registros, é preciso ter os papéis de Gravador de configuração de registros (roles/logging.configWriter) e Editor de políticas de alertas do Monitoring (roles/monitoring.alertPolicyEditor) ou permissões equivalentes.

  1. Execute uma consulta na Análise de registros que segmenta 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 com base 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 com base em registros.

A seguir