Configura un ambito delle metriche utilizzando l'API

Questo documento descrive come utilizzare Google Cloud CLI o l'API Cloud Monitoring per configurare l'ambito delle metriche di un progetto Google Cloud. Questa pagina è rivolta agli sviluppatori e agli amministratori di sistema.

I comandi in questa pagina fanno riferimento a un "container di risorse". Mentre un container di risorse può essere un'organizzazione, una cartella o un progetto, i comandi descritti in questa pagina supportano solo i progetti Google Cloud.

Prima di iniziare

• Se non hai dimestichezza con i termini ambito delle metriche e progetto di ambito, consulta la sezione Ambiti delle metriche.

• Assicurati che i ruoli IAM (Identity and Access Management) nel progetto di ambito e in ogni progetto che vuoi aggiungere come progetto monitorato includano tutte le autorizzazioni nel ruolo Amministratore Monitoring (roles/monitoring.admin). Per ulteriori informazioni, consulta Configurazioni dell'ambito delle metriche.

• I metodi dell'ambito delle metriche dell'API Cloud Monitoring che recuperano le informazioni sono sincroni; tuttavia, le API che cambiano stato sono asincrone. I comandi di Google Cloud CLI bloccano fino al completamento dell'operazione asincrona. Per informazioni su come determinare quando un metodo dell'API asincrono è completo e come determinarne lo stato, consulta Metodi dell'API asincrona.

• Se prevedi di richiamare l'API Cloud Monitoring utilizzando curl o se vuoi utilizzare gli esempi in questa pagina, completa i passaggi di configurazione del comando curl.

Elenco di tutti gli ambiti delle metriche che includono un progetto

gcloud

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Per ottenere un elenco degli ambiti delle metriche che possono visualizzare le metriche per un container di risorse, ad esempio un progetto Google Cloud, esegui il comando gcloud beta monitoring metrics-scopes list:

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

Prima di eseguire il comando, inserisci l'identificatore del container di risorse nella variabile MONITORED_RESOURCE_CONTAINER_NAME. Quando il container di risorse è un progetto Google Cloud, inserisci projects/PROJECT_ID_OR_NUMBER.

Ad esempio, per elencare gli ambiti delle metriche che includono il progetto my-project, esegui questo comando:

gcloud beta monitoring metrics-scopes list projects/my-project

La seguente risposta indica che il progetto my-project è incluso in due ambiti delle metriche:

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

Per ottenere informazioni dettagliate su un ambito delle metriche, esegui il comando gcloud beta monitoring metrics-scopes describe.

arricciatura

Per ottenere un elenco degli ambiti delle metriche che possono visualizzare le metriche per un progetto, invia una richiesta GET all'endpoint locations.global.metricsScopes.listMetricsScopesByMonitoredProject e includi il parametro di query che specifica il progetto.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

In caso di esito positivo, la risposta è un array di oggetti MetricsScope.

Questo metodo non comporta la scrittura di una voce negli audit log del progetto di definizione dell'ambito. Per registrare queste azioni nell'audit log, abilita Lettura dati per l'API Cloud Resource Manager. Per ulteriori informazioni, consulta Configurazione degli audit log di accesso ai dati.

Ottieni dettagli su un ambito delle metriche

gcloud

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Per ottenere informazioni dettagliate su un ambito delle metriche, esegui il comando gcloud beta monitoring metrics-scopes describe:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Prima di eseguire il comando, inserisci il nome completo del nome completo di un ambito delle metriche nella variabile METRICS_SCOPE_ID. Di seguito è riportato un esempio di nome completo:

locations/global/metricsScopes/012345012345

Di seguito è riportato un esempio di risposta. In questo esempio, l'ambito delle metriche contiene un progetto e l'ID del progetto e dell'ambito delle metriche è lo stesso:

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

Per identificare il progetto Google Cloud dal suo ID, esegui il comando gcloud projects list e filtra in base all'ID progetto. Ad esempio, per ottenere il nome del progetto 012345012345, esegui questo comando:

gcloud projects list --filter="012345012345" -format="value(NAME)"

arricciatura

Per ottenere informazioni su un ambito delle metriche, invia una richiesta GET all'endpoint locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

In caso di esito positivo, la risposta è un oggetto MetricsScope.

Questo metodo non comporta la scrittura di una voce negli audit log del progetto di definizione dell'ambito. Per registrare queste azioni nell'audit log, abilita Lettura dati per l'API Cloud Resource Manager. Per ulteriori informazioni, consulta Configurazione degli audit log di accesso ai dati.

Aggiungi un progetto a un ambito delle metriche

gcloud

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Per aggiungere un container di risorse, ad esempio un progetto Google Cloud, a un ambito delle metriche, esegui il comando gcloud beta monitoring metrics-scopes create:

gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Prima di eseguire il comando precedente:

• Inserisci il nome o l'ID del progetto Google Cloud il cui ambito delle metriche deve essere modificato nella variabile SCOPING_PROJECT_ID_OR_NUMBER.

• Inserisci l'identificatore del container di risorse nella variabile MONITORED_RESOURCE_CONTAINER_NAME. Quando il container di risorse è un progetto Google Cloud, inserisci projects/PROJECT_ID_OR_NUMBER.

Ad esempio, il seguente comando aggiunge il progetto my-monitored-project all'ambito delle metriche del progetto denominato my-staging-projects:

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

La risposta al comando precedente conferma che il comando è stato completato correttamente:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

arricciatura

Per aggiungere un progetto Google Cloud a un ambito delle metriche, invia una richiesta POST all'endpoint locations.global.metricsScopes.projects.create. Nell'esempio seguente, il progetto identificato dalla variabile di ambiente MONITORED_PROJECT_ID_OR_NUMBER viene aggiunto come progetto monitorato:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

La risposta di questo metodo asincrono è un oggetto Operation.

Le applicazioni che chiamano questo metodo dovrebbero eseguire il polling dell'endpoint operation.get finché il valore del campo Operation.done non è true. Se il campo Operation.done è impostato su false, significa che l'operazione è in corso. Per ulteriori informazioni, consulta la sezione Comandi API asincroni.

Di seguito è riportato un esempio di risposta quando l'aggiunta di un progetto monitorato ha esito positivo:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "G​C​P",
    "providerAccountId": "...",
    ...
  }
}

Nella risposta precedente, il campo Operation.done è impostato su true. Questo valore indica che il comando è completo. Poiché il comando è stato completato correttamente, il campo Operation.response è impostato e il suo valore è un oggetto MonitoredProject. Il campo response.name include l'identificatore del progetto di definizione dell'ambito e del progetto monitorato. Il campo providerAccountId elenca il nome del progetto monitorato.

La chiamata di questo metodo comporta una voce negli audit log del progetto di ambito. La console Google Cloud non richiama questo metodo API. Di conseguenza, le modifiche apportate a un ambito delle metriche quando si utilizza la console Google Cloud non vengono registrate negli audit log.

Rimuovere un progetto da un ambito delle metriche

gcloud

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Per rimuovere un container di risorse, ad esempio un progetto Google Cloud, da un ambito delle metriche, esegui il comando gcloud beta monitoring metrics-scopes delete:

gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Prima di eseguire il comando precedente:

• Inserisci il nome o l'ID del progetto Google Cloud il cui ambito delle metriche deve essere modificato nella variabile SCOPING_PROJECT_ID_OR_NUMBER.

• Inserisci l'identificatore del container di risorse nella variabile MONITORED_RESOURCE_CONTAINER_NAME. Quando il container di risorse è un progetto Google Cloud, inserisci projects/PROJECT_ID_OR_NUMBER.

Ad esempio, il comando seguente rimuove il progetto my-monitored-project dall'ambito delle metriche del progetto denominato my-staging-projects:

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

La risposta al comando precedente conferma che il comando è stato completato correttamente:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

Quando il progetto di definizione dell'ambito non monitora il progetto specificato dalla variabile MONITORED_RESOURCE_CONTAINER_NAME, viene segnalato il seguente errore:

NOT_FOUND: Requested entity was not found.

arricciatura

Per rimuovere un progetto Google Cloud da un ambito delle metriche, invia una richiesta DELETE all'endpoint locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

La risposta a questo metodo asincrono è un oggetto Operation.

Le applicazioni che chiamano questo metodo dovrebbero eseguire il polling dell'endpoint operation.get finché il valore del campo Operation.done non è true. Se il campo Operation.done è impostato su false, significa che l'operazione è in corso. Per ulteriori informazioni, consulta la sezione Comandi API asincroni.

Di seguito è riportato un esempio di risposta quando la rimozione di un progetto monitorato ha esito positivo:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Nella risposta precedente, il campo Operation.done è impostato su true. Questo valore indica che il comando è completo. Poiché il comando è stato completato correttamente, il campo Operation.response è impostato e contiene un campo @type.

La chiamata di questo metodo comporta una voce negli audit log del progetto di ambito. La console Google Cloud non richiama questo metodo API. Di conseguenza, le modifiche apportate a un ambito delle metriche quando si utilizza la console Google Cloud non vengono registrate negli audit log.

Metodi dell'API asincroni

Nota: i comandi dell'interfaccia a riga di comando di Google Cloud bloccano fino al completamento del metodo API asincrono che vengono richiamati.

Tutti i metodi basati sulle metriche dell'API Cloud Monitoring che modificano lo stato del sistema, ad esempio il comando per aggiungere un progetto monitorato a un ambito delle metriche, sono asincroni. Per questi comandi, la risposta del comando è un oggetto Operation.

Le applicazioni che chiamano un metodo API asincrono devono eseguire il polling dell'endpoint operation.get finché il valore del campo Operation.done è true:

• Quando done è false, l'operazione è in corso.

  Per aggiornare le informazioni sullo stato, invia una richiesta GET all'endpoint operation.get:

  curl -H "Authorization: Bearer ${TOKEN}" \
  https://monitoring.googleapis.com/v1/${OPERATION_NAME}
  

  Nel comando precedente, OPERATION_NAME è una variabile di ambiente che archivia il valore del campo Operation.name.

• Quando done è true, l'operazione è completata e viene impostato il campo error o response:

  • error: se impostato, l'operazione asincrona non è riuscita. Il valore di questo campo è un oggetto Status che contiene un codice di errore gRPC e un messaggio di errore.
  • response: una volta impostato, l'operazione asincrona è stata completata correttamente e il valore riflette il risultato.

Configurazione del comando curl

Questa sezione descrive la configurazione utilizzata per creare i comandi curl in questo documento. Ogni comando curl in questa pagina include un insieme di argomenti seguiti dall'URL di una risorsa API:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Imposta queste variabili di ambiente per semplificare la creazione dei comandi curl:

1. Crea la variabile di ambiente per archiviare l'ID o il numero del progetto di definizione dell'ambito:

   SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER
   

2. Facoltativo. Se prevedi di aggiungere o rimuovere progetti monitorati, configura la variabile di ambiente con l'ID o il numero del progetto monitorato:

   MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER
   

3. Esegui l'autenticazione in Google Cloud CLI:

   gcloud auth login
   

4. Facoltativo. Per evitare di dover specificare il tuo ID progetto con ogni comando gcloud, imposta l'ID progetto come predefinito utilizzando gcloud CLI:

   gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
   

5. Crea un token di autorizzazione e acquisiscilo in una variabile di ambiente:

   TOKEN=`gcloud auth print-access-token`
   

   I token sono validi per un periodo di tempo limitato. Se i comandi che hanno funzionato all'improvviso segnalano che il tuo account non è autenticato, invia di nuovo il comando.

6. Per verificare di aver ricevuto un token di accesso, esegui l'echo della variabile TOKEN:

   echo ${TOKEN}
   ya29.GluiBj8o....
   

Potrebbe anche essere necessario specificare altri argomenti, ad esempio per specificare il tipo di richiesta HTTP (ad esempio -X DELETE). La richiesta predefinita è GET, quindi gli esempi non la specificano.

Passaggi successivi

Per informazioni sull'utilizzo di Google Cloud con Terraform, consulta le seguenti risorse:

• Terraform con Google Cloud
• Registro Terraform per google_monitoring_monitored_project