Accedere ai log della piattaforma e utilizzarli

Configura i log della piattaforma in Artifact Registry per visualizzare informazioni sulle richieste riuscite e non riuscite effettuate ai tuoi repository Artifact Registry. I log della piattaforma vengono generati da Cloud Logging e possono essere visualizzati in Esplora log. Puoi esaminare i log della piattaforma Artifact Registry per risolvere i problemi relativi alle richieste non riuscite, mantenere i record delle richieste riuscite e visualizzare il numero di download di un artefatto.

Un log della piattaforma è formattato come LogEntry.

Panoramica

Artifact Registry genera log della piattaforma per le chiamate API del piano dati e le chiamate API del control plane. Le azioni del control plane includono operazioni di gestione dei repository come la creazione, la modifica delle descrizioni e l'eliminazione dei repository, nonché azioni di gestione degli artefatti come l'elenco, l'assegnazione di tag e l'eliminazione degli artefatti. Le azioni del piano dati includono operazioni come il push e il pull di artefatti dai repository Artifact Registry.

I log per entrambi i tipi di chiamate contengono le seguenti informazioni:

• Dettagli richiesta
• Dettagli della risposta
• Stato
• Etichette
  • Nome metodo
  • Nome risorsa
  • Località della risorsa
  • ID operazione (per operazioni a lunga esecuzione)
  • Formato del repository (per le risorse del repository)
  • Modalità repository (per le risorse del repository)

Inoltre, i log per le chiamate API del control plane contengono le seguenti informazioni:

• Informazioni HTTP
  • Metodo di richiesta
  • Richiedi URL
  • Dimensione della richiesta (in byte)
  • Stato
  • Dimensioni della risposta (in byte)
  • User agent
  • IP remoto (IP client che ha emesso la richiesta)
  • Protocollo
  • Referer
  • Latenza

Puoi visualizzare i log della piattaforma per Artifact Registry in Esplora log.

Prima di iniziare

Abilita l'API Logging.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire i log della piattaforma, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Artifact Registry Admin (roles/artifactregistry.admin)
• Visualizzatore log (roles/logging.viewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilita logging della piattaforma

Puoi attivare la registrazione della piattaforma per l'intero progetto Google Cloud o per un repository specifico.

Abilitare il logging della piattaforma per un progetto

Per attivare la registrazione della piattaforma per il tuo progetto Google Cloud , esegui questo comando:

gcloud artifacts projects update --enable-platform-logs --severity=SEVERITY --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH -H "X-GFE-SSL: yes" -H "Content-Type: application/json" -d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {"logging_state": "ENABLED", "severity_level": "SEVERITY"}}' "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Dove:

• SEVERITY determina il tipo di azioni che attivano la creazione dei log della piattaforma Artifact Registry. Puoi inserire INFO, ERROR o escludere il campo --severity per creare log della piattaforma per tutte le azioni supportate.
• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

Abilitare il logging della piattaforma per un repository

gcloud artifacts repositories update --enable-platform-logs --severity=SEVERITY REPOSITORY --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {"loggingState": "ENABLED", "severityLevel": "SEVERITY"}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Dove:

• SEVERITY determina il tipo di azioni che attivano la creazione dei log della piattaforma Artifact Registry. Puoi inserire INFO, ERROR o escludere il campo --severity per creare log della piattaforma per tutte le azioni supportate.
• REPOSITORY è il nome del repository in Artifact Registry.
• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

Verifica la configurazione del logging della piattaforma

Puoi verificare se la registrazione della piattaforma Artifact Registry è abilitata nel tuo progetto o per un repository specifico.

Verificare la registrazione della piattaforma per un progetto

Per verificare se la registrazione della piattaforma Artifact Registry è abilitata nel tuo progetto, esegui questo comando:

gcloud artifacts projects describe --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Dove:

• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

L'output è simile al seguente:

{
  "name": "projects/PROJECT/locations/{"<var>LOCATION</var>"}}/projectConfig"
  "platformLogsConfig": {
    "loggingState": "ENABLED"
    "severityLevel": "INFO"
  }
}

Verifica la registrazione della piattaforma per un repository

Per verificare se la registrazione della piattaforma Artifact Registry è abilitata in un repository, esegui questo comando:

gcloud artifacts repositories describe REPOSITORY --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY"

Dove:

• REPOSITORY è il nome del repository.
• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

L'output è simile al seguente:

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY"
  "platformLogsConfig": {
    "loggingState": "ENABLED",
    "severityLevel": "INFO"
  }
}

Disabilita logging della piattaforma

Puoi disattivare la registrazione della piattaforma per l'intero progetto Google Cloud o per un repository specifico.

Disabilitare il logging della piattaforma per un progetto

Per disattivare la registrazione della piattaforma per il tuo progetto Google Cloud , esegui questo comando:

gcloud artifacts projects update --disable-platform-logs --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {"logging_state": "DISABLED"}}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Dove:

• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

Disabilita il logging della piattaforma per un repository

Per disattivare la registrazione della piattaforma per un repository, esegui questo comando:

gcloud artifacts repositories update --disable-platform-logs REPOSITORY --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {"loggingState": "DISABLED", "severityLevel": "INFO"}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Dove:

• REPOSITORY è il nome del repository in Artifact Registry.
• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

Cancella la configurazione del logging della piattaforma

Puoi cancellare la configurazione della registrazione della piattaforma per un progetto o per un repository. Quando esegui il comando di cancellazione, loggingState e severityLevel del tuo progetto o repository vengono impostati su null.

Se cancelli la configurazione per il tuo progetto, solo i repository in cui la registrazione della piattaforma è già stata abilitata produrranno log della piattaforma. Se cancelli la configurazione di un repository, questo eredita la configurazione di logging della piattaforma dal tuo progetto.

Cancella la configurazione del logging della piattaforma per un progetto

Per cancellare la configurazione della registrazione della piattaforma del tuo Google Cloud progetto, esegui questo comando:

gcloud artifacts projects update --clear-platform-logs --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {}}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Dove:

• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

Cancella la configurazione del logging della piattaforma per un repository

Per cancellare la configurazione della registrazione della piattaforma di un repository, esegui questo comando:

gcloud artifacts repositories update --clear-platform-logs REPOSITORY --location LOCATION --project PROJECT

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Dove:

• REPOSITORY è il nome del repository in Artifact Registry.
• LOCATION è la posizione del tuo repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

Visualizza i log della piattaforma

Per visualizzare i log della piattaforma:

1. Apri la pagina Esplora log nella console Google Cloud .

   Apri la pagina Esplora log

2. Nel riquadro della query, fai clic sul menu a discesa Nome log.

3. Inserisci requests, quindi seleziona la casella di controllo requests sotto l'intestazione Artifact Registry.

4. Fai clic su Applica.

   Il logging mostra i log delle chiamate API del data plane e del control plane nel riquadro Risultati delle query.

5. Per visualizzare i contenuti di un log, fai clic sulla freccia accanto a un log elencato nei risultati della query.

Per saperne di più su come interpretare i risultati delle query in Esplora log, vedi Visualizzare i risultati della query.

Analizzare i log della piattaforma con Observability Analytics

Puoi utilizzare Observability Analytics per eseguire query SQL sui log di Artifact Registry, in modo da analizzarli in modo più dettagliato. Questa sezione contiene diverse query di esempio per casi d'uso comuni. Puoi adattare queste query per analizzare altri aspetti dell'utilizzo di Artifact Registry filtrando in base a diversi campi all'interno della struttura LogEntry.

Prima di iniziare a utilizzare Observability Analytics, segui questi passaggi:

1. Configura i bucket di log per utilizzare Observability Analytics.

2. Configura ruoli e autorizzazioni Identity and Access Management per utilizzare Observability Analytics.

Dopodiché, segui i passaggi per inserire ed eseguire una query personalizzata. Quando arrivi al riquadro Query SQL, puoi inserire una delle seguenti query di esempio:

Esempio: i 10 principali indirizzi IP per volume di download

Questa query valuta i log della piattaforma Artifact Registry e restituisce i primi 10 indirizzi IP che hanno scaricato il maggior numero di dati dai tuoi repository negli ultimi sette giorni:

SELECT
  http_request.remote_ip AS client_ip,
  SUM(http_request.response_size) AS total_download_bytes
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND http_request.request_method = "GET"
  AND http_request.status >= 200 AND http_request.status < 300
  AND http_request.response_size > 0
  AND CAST(http_request.response_size AS INT64) > 0
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY
  client_ip
ORDER BY
  total_download_bytes DESC
LIMIT 10;

Esempio: richieste per repository

Questa query valuta i log della piattaforma Artifact Registry e restituisce il numero di richieste effettuate a ogni repository nelle ultime 24 ore:

SELECT
  JSON_VALUE(resource.labels.repository_id) AS repository,
  JSON_VALUE(resource.labels.location) AS location,
  COUNT(*) AS request_count
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
GROUP BY
  repository,
  location
ORDER BY
  request_count DESC;

Esempio: richieste non riuscite

Questa query valuta i log della piattaforma Artifact Registry ed elenca i dettagli delle 10 richieste non riuscite più recenti nell'ultima ora:

SELECT
  timestamp,
  http_request.status,
  http_request.request_method,
  http_request.request_url,
  http_request.remote_ip,
  JSON_VALUE(resource.labels.repository_id) AS repository,
  JSON_VALUE(labels.resource_name) AS artifact_name,
  trace
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND http_request.status >= 400
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
ORDER BY
  timestamp DESC
LIMIT 10;