Monitorare i log di Knowledge Catalog

Questo documento spiega come accedere ai log di Knowledge Catalog (in precedenza Dataplex Universal Catalog), eseguirne query e interpretarli utilizzando Cloud Logging. L'accesso ai log dei job e dei servizi di Knowledge Catalog consente di risolvere i problemi e monitorare le attività di gestione dei dati, inclusi il rilevamento dei dati basato sull'AI e la scansione della qualità dei dati.

Centralizzando i log in Logging, puoi analizzare il rendimento dei job, configurare avvisi per errori o anomalie e indirizzare i log ad altri Google Cloud servizi come BigQuery per la conservazione e l'analisi a lungo termine.

Per comprendere i costi, consulta la pagina Prezzi di Google Cloud Observability.

Per ulteriori informazioni sulla conservazione dei log, consulta Periodi di conservazione dei log.

Per disabilitare tutti i log o escluderli da Logging, consulta Filtri di esclusione.

Per indirizzare i log da Logging a Cloud Storage, BigQuery o Pub/Sub, consulta la panoramica su routing e archiviazione.

Casi d'uso

Il logging di Knowledge Catalog supporta casi d'uso in diversi settori:

  • Risoluzione dei problemi relativi agli errori della pipeline di dati: quando un'attività di Knowledge Catalog per il trattamento dei dati non riesce, i log process forniscono messaggi di errore dettagliati che aiutano gli ingegneri dei dati a identificare e risolvere i problemi nei job Spark o nelle attività personalizzate.
  • Monitoraggio della qualità dei dati: una società di servizi finanziari può monitorare i log data_quality_scan_rule_result per monitorare le tendenze della qualità dei dati nel tempo, ricevere avvisi in caso di peggioramento della qualità per gli asset di dati critici e fornire ai revisori prove dei controlli di qualità dei dati per la conformità legale.
  • Monitoraggio dell'arricchimento dei metadati: una società di vendita al dettaglio che utilizza i job di importazione dei metadati per arricchire il proprio catalogo può utilizzare i log metadata_job per verificare che le importazioni vengano completate correttamente e che tutti gli elementi dei metadati vengano elaborati correttamente.
  • Controllo del rilevamento dei dati: le organizzazioni possono utilizzare i log discovery per monitorare come e quando vengono rilevate e registrate nuove origini dati in Knowledge Catalog, fornendo una traccia di audit per i processi di onboarding dei dati.

Come funziona il logging di Knowledge Catalog

Knowledge Catalog invia i log per le operazioni di servizio e le esecuzioni dei job a Cloud Logging. Ogni voce di log contiene dettagli sull'operazione o sul job, come lo stato, l'ora di inizio e di fine, le risorse associate (ad esempio una scansione o un'attività dei dati) e il risultato. Diversi tipi di operazioni, come la scansione dei dati, il rilevamento, l'importazione dei metadati e il trattamento dei dati, generano diversi tipi di log, che puoi eseguire query utilizzando logName o il linguaggio di query di logging in Logging.

Puoi accedere a questi log e analizzarli utilizzando Esplora log nella Google Cloud console o indirizzandoli ad altre destinazioni, come bucket Cloud Storage o tabelle BigQuery, per ulteriori analisi.

Tipi di log di Knowledge Catalog

Knowledge Catalog pubblica i seguenti log di servizio in Cloud Logging.

Tipo di log Nome log Query logName Descrizione log
Log degli eventi di scansione dei dati dataplex.googleapis.com/data_scan logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdata_scan) Log degli eventi a livello di job per i job di scansione dei dati (sia scansioni della qualità dei dati sia scansioni del profilo di dati) che indicano lo stato, i risultati e le statistiche del job
Log dei risultati delle regole di scansione della qualità dei dati dataplex.googleapis.com/data_quality_scan_rule_result logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdata_quality_scan_rule_result) Risultati dettagliati della valutazione a livello di regola per ogni regola valutata in un job di scansione della qualità dei dati
Log di rilevamento dataplex.googleapis.com/discovery logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fdiscovery) Avanzamento e aggiornamenti del rilevamento sugli asset in una zona
Log dei job di metadati dataplex.googleapis.com/metadata_job logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job) Log sui job di importazione dei metadati e sugli elementi di importazione nel file di importazione dei metadati
Log di processo dataplex.googleapis.com/process logName=(projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fprocess) Esecuzioni di job risultanti da attività di trattamento dei dati

Accedere ai log di servizio di Knowledge Catalog

Per accedere a Logging, utilizza l' Esplora log nella Google Cloud console, i gcloud logging comandi, o l'API Logging. Puoi utilizzare il linguaggio di query di logging per creare query dettagliate.

Autorizzazioni IAM obbligatorie

Per visualizzare ed eseguire query sui log, devi disporre del ruolo Visualizzatore log (roles/logging.viewer) o di autorizzazioni equivalenti sul progetto.

Visualizzare i log nella Google Cloud console

  1. Nella Google Cloud console, vai alla pagina Osservabilità > Logging > Esplora log.

    Vai a Esplora log

  2. Configura i filtri Risorsa e Nome log in base alla tabella seguente:

    Tipo di log Selezione delle risorse Selezione del nome del log
    Eventi di scansione dei dati Risorsa sottoposta a controllo > Servizio: Cloud Dataplex dataplex.googleapis.com/data_scan
    Risultati delle regole di scansione della qualità dei dati Risorsa sottoposta a controllo > Servizio: Cloud Dataplex dataplex.googleapis.com/data_quality_scan_rule_result
    Log di rilevamento Zona Cloud Dataplex dataplex.googleapis.com/discovery
    Log dei job di metadati Job metadati Cloud Dataplex dataplex.googleapis.com/metadata_job
    Log di processo Attività Cloud Dataplex dataplex.googleapis.com/process

  3. (Facoltativo) Seleziona filtri secondari specifici (ad esempio un ID attività specifico) per restringere la query.

  4. Fai clic su Applica, quindi su Esegui query.

Esempi di filtri dei log

Puoi utilizzare il linguaggio di query di logging nell'editor di query di Esplora log o con Google Cloud CLI. I seguenti esempi mostrano come leggere i log utilizzando gcloud CLI.

Esempio: leggere gli eventi di scansione dei dati

Per leggere le voci dei log degli eventi per le scansioni della qualità dei dati o del profilo di dati, utilizza il gcloud logging read comando con la seguente query:

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

Esempio: leggere le voci dei log di processo

Per leggere le voci dei log di processo, utilizza il gcloud logging read comando con la seguente query:

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

Payload di log di esempio

I seguenti esempi mostrano le strutture del payload JSON per diversi tipi di log di Knowledge Catalog. Puoi utilizzare questi esempi per comprendere la struttura dei log e creare filtri dei log.

Log degli eventi di scansione dei dati

In Knowledge Catalog, le scansioni dei dati comprendono sia le scansioni della qualità dei dati sia le scansioni del profilo di dati. Quando esegui un job di scansione dei dati di uno dei due tipi, Knowledge Catalog produce un log degli eventi data_scan in Logging che riepiloga l'esecuzione complessiva del job.

L'esempio seguente mostra il payload del log degli eventi per una scansione della qualità dei dati:

{
  "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"
}

Log dei risultati delle regole di scansione della qualità dei dati

Quando viene eseguita una scansione della qualità dei dati, Knowledge Catalog genera un log degli eventi di scansione dei dati e un log dei risultati delle regole di scansione della qualità dei dati separato per ogni singola regola valutata nel job.

Ogni voce di log data_quality_scan_rule_result contiene informazioni sulla regola specifica, tra cui la configurazione della regola, la dimensione di valutazione, lo stato e i conteggi delle righe.

L'esempio seguente mostra un payload del log dei risultati delle regole di scansione della qualità dei dati:

{
  "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"
}

Log di rilevamento

L'esempio seguente mostra un payload del log di rilevamento:

{
  "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"
}

Log dei job di metadati

L'esempio seguente mostra un payload del log dei job di metadati:

{
  "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"
}

Log di processo

L'esempio seguente mostra un payload del log di 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"
}

Configurare gli avvisi basati su log

Puoi configurare gli avvisi basati su log per ricevere una notifica ogni volta che si verificano eventi specifici di Knowledge Catalog (ad esempio una scansione della qualità dei dati non riuscita).

Per creare avvisi basati su log, devi disporre dei ruoli Writer di configurazione log (roles/logging.configWriter) ed Editor di policy di avviso di Monitoring (roles/monitoring.alertPolicyEditor) o di autorizzazioni equivalenti.

  1. Esegui una query in Esplora log che abbia come target la condizione di errore (ad esempio: resource.type="dataplex.googleapis.com/DataScan" AND NOT jsonPayload.dataQuality.passed=true).
  2. Sopra il riquadro dei risultati della query, fai clic su Crea avviso.
  3. Nel riquadro Crea avviso basato su log, inserisci un nome e una descrizione per la policy di avviso.
  4. Fai clic su Avanti e configura i canali di notifica.
  5. Fai clic su Salva.

Per informazioni più dettagliate, consulta Creare avvisi basati su log.

Passaggi successivi