Configura l'agente per Oracle

Puoi configurare l'agente di Google Cloudper i workload di Compute sull'host insieme al tuo database Oracle per raccogliere metriche e monitorare i tuoi workload del database Oracle.

Questo documento mostra come installare, configurare e verificare l'agente per i carichi di lavoro di Compute sulle istanze Compute Engine che eseguono carichi di lavoro Oracle Database.

L'agente raccoglie varie metriche Oracle eseguendo query sulle visualizzazioni delle prestazioni di Oracle Database (ad esempio V$DATABASE, V$INSTANCE e V$DATAGUARD_STATS) e sulle visualizzazioni del dizionario dei dati (ad esempio DBA_DATA_FILES e DBA_FREE_SPACE). Queste metriche vengono poi inviate a Cloud Monitoring, dove possono essere visualizzate e analizzate. Vedi Metriche supportate.

Requisiti di sistema

Sistemi operativi Versioni di Oracle Versioni Oracle
  • Red Hat Enterprise Linux versioni 7, 8 e 9
  • Versioni 7, 8 e 9 di Oracle Linux
  • Oracle Database 19c
  • Oracle Database 23ai*
  • Enterprise Edition
  • Standard Edition
  • Versione Express (gratuita)

Prerequisiti

Prima di installare Agent for Compute Workloads per monitorare i carichi di lavoro di Oracle Database, assicurati che siano soddisfatti i seguenti prerequisiti:

Installa l'agente

Per installare l'agente per i carichi di lavoro di Compute:

  1. Crea un file di configurazione del repository.

    sudo tee /etc/yum.repos.d/google-cloud-workload-agent.repo << EOM
[google-cloud-workload-agent]
name=Google Cloud Workload Agent
baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-workload-agent-\$basearch
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM

  2. Aggiorna i metadati del gestore di pacchetti.

    sudo yum makecache

  3. Installa il pacchetto rpm google-cloud-workload-agent.

    sudo yum install google-cloud-workload-agent

Dopo aver installato l'agente per Oracle, verifica l'installazione.

Verifica l'installazione dell'agente

Per verificare che l'agente sia in esecuzione, seleziona il tuo sistema operativo e poi segui questi passaggi:

  1. Utilizza SSH per connetterti alla tua istanza VM.

  2. Esegui questo comando:

    systemctl status google-cloud-workload-agent

    Se l'agente funziona correttamente, l'output contiene active (running). Ad esempio:

    google-cloud-workload-agent.service - Google Cloud Workload Agent
Loaded: loaded (/usr/lib/systemd/system/google-cloud-workload-agent.service; enabled; preset: disabled)
Active: active (running) since Tue 2024-09-03 22:29:57 UTC; 3s ago
Main PID: 274972 (google_cloud_wo)
 Tasks: 10 (limit: 100440)
Memory: 51.2M (max: 1.0G limit: 1.0G available: 972.7M)
   CPU: 625ms
CGroup: /system.slice/google-cloud-workload-agent.service
       └─274972 /usr/bin/google_cloud_workload_agent startdaemon

Sep 03 22:29:57 my_gce_instance systemd[1]: Started Google Cloud Workload Agent.

    Se l'agente non è in esecuzione, prova a riavviarlo.

Configura l'agente

Dopo aver installato l'agente per i workload di Compute, se vuoi, puoi attivare altre funzionalità dell'agente aggiornando il file di configurazione dell'agente. Per un elenco dei parametri che puoi configurare per i carichi di lavoro Oracle Database, consulta Parametri di configurazione.

Dopo aver configurato l'agente, puoi verificare nuovamente l'installazione per assicurarti che sia configurato correttamente.

Parametri di configurazione

Agent for Compute Workloads supporta i seguenti parametri di configurazione per Oracle:

Parametro Descrizione
log_level

String

Per impostare il livello di logging dell'agente, aggiungi i livelli di log. I livelli di log disponibili sono i seguenti:
  • DEBUG
  • INFO
  • WARNING
  • ERROR
Il valore predefinito è INFO.
log_to_cloud

Boolean

Per reindirizzare i log dell'agente a Cloud Logging, specifica true. Il valore predefinito è true.
oracle_configuration.enabled

Boolean

Facoltativo. Determina se il servizio Oracle è attivo. Se impostato su true o se non è impostato e il workload è presente, puoi configurare il rilevamento e la raccolta delle metriche. Se è impostato su false, il servizio Oracle e le relative funzionalità sono disattivati.
I seguenti parametri secondari sono applicabili solo quando specifichi oracle_configuration.enabled: true.
oracle_configuration.oracle_discovery.enabled

Boolean

Facoltativo. Determina se Oracle Discovery è attivo.

Il valore predefinito è true.
oracle_configuration.oracle_discovery.update_frequency

Int

Facoltativo. Specifica l'intervallo di campionamento, in secondi, che determina la frequenza con cui l'agente per i carichi di lavoro di Compute esegue il processo di rilevamento. Il valore predefinito è 3600 secondi (1 ora).

Assicurati che il valore termini con una "s" minuscola per indicare i secondi. Ad esempio: 30s.
oracle_configuration.oracle_metrics.enabled

Boolean

Facoltativo. Per consentire ad Agent for Compute Workloads di raccogliere le metriche di monitoraggio di Oracle, specifica true. Il valore predefinito è false.

I seguenti parametri secondari sono applicabili solo quando specifichi oracle_metrics.enabled: true.
oracle_configuration.oracle_metrics.collection_frequency

Int

Facoltativo. Specifica l'intervallo di campionamento, in secondi, che determina la frequenza con cui l'agente per i carichi di lavoro di Compute esegue query sulle istanze di Oracle Database per raccogliere le metriche di monitoraggio di Oracle. Il valore predefinito è 60 secondi.

Assicurati che il valore termini con una "s" minuscola per indicare i secondi. Ad esempio: 30s.
oracle_configuration.oracle_metrics.query_timeout

String

Facoltativo. Specifica il timeout per ogni query eseguita sulle istanze del database Oracle. Il valore predefinito è 10 secondi.

Assicurati che il valore termini con una "s" minuscola per indicare i secondi. Ad esempio: 30s.
oracle_configuration.oracle_metrics.connection_parameters.username

String

Specifica l'account utente utilizzato per eseguire query sull'istanza di Oracle Database.

Assicurati che questo utente disponga delle autorizzazioni richieste per leggere le viste del rendimento nel tuo database Oracle.
oracle_configuration.oracle_metrics.connection_parameters.host

String

Specifica l'identificatore della macchina locale che ospita l'istanza del database.
oracle_configuration.oracle_metrics.connection_parameters.port

Int

Specifica la porta su cui l'istanza di Oracle Database accetta le query.
oracle_configuration.oracle_metrics.connection_parameters.service_name

String

Specifica il nome del servizio per l'istanza del database Oracle che vuoi che l'agente monitori.
oracle_configuration.oracle_metrics.connection_parameters.secret.project_id

String

Specifica l'ID progetto di Secret Manager per recuperare la password per l'utente che esegue query sul database.
oracle_configuration.oracle_metrics.connection_parameters.secret.secret_name

String

Specifica il nome del secret in Secret Manager che memorizza la password dell'account utente.

Raccogliere e visualizzare le metriche Oracle

Puoi abilitare la raccolta delle metriche per i carichi di lavoro Oracle Database. Vedi Metriche supportate.

Abilita la raccolta delle metriche

Per abilitare la raccolta delle metriche Oracle utilizzando l'agente per i carichi di lavoro di Compute, esegui le seguenti operazioni:

  1. Utilizza SSH per connetterti alla tua istanza VM.

  2. Come utente del sistema operativo Oracle, esegui lo strumento oraenv per impostare le variabili di ambiente. Supponiamo che tu abbia già definito l'utente oracle e il ORACLE_SID nel file /etc/oratab.

    sudo su - oracle
export PATH=$PATH:/usr/local/bin
. oraenv
sqlplus / as sysdba

  3. Come utente SYSDBA o SYSOPER, in Oracle Database crea un utente per il monitoraggio con una password corrispondente al secret che hai creato nei Prerequisiti.

    CREATE USER wlmagent IDENTIFIED BY password;

  4. In qualità di utente SYSDBA o SYSOPER, concedi le seguenti autorizzazioni all'utente di monitoraggio per eseguire query sulle visualizzazioni del rendimento:

    • SESSION
    • SELECT_CATALOG_ROLE
    • SYSDG
    GRANT CREATE SESSION,SELECT_CATALOG_ROLE,SYSDG TO wlmagent;

  5. Esci da sqlplus e dall'utente oracle.

  6. In qualità di utente root, modifica il file di configurazione dell'agente utilizzando il tuo editor preferito.

    sudo nano /etc/google-cloud-workload-agent/configuration.json

  7. Nel file di configurazione, modifica la sezione oracle_metrics per apportare i seguenti aggiornamenti:

    1. Imposta il parametro enabled su true.
    2. Imposta il parametro service_name per specificare il nome del servizio dell'istanza Oracle che vuoi che l'agente monitori.
    3. Specifica il nome utente Oracle per l'agente per connettersi al tuo database.
    4. Imposta i parametri host e port affinché l'agente si connetta al tuo database.
    5. Imposta il parametro secret per l'agente in modo che recuperi una password per il nome utente:
      • project_id: l'ID del progetto che contiene i dati di Secret Manager.
      • secret_name: il nome del secret in Secret Manager.

    Di seguito è riportato un esempio di file di configurazione:

    {
  "log_level": "INFO",
  "common_discovery": {"collection_frequency": "3600s" },
  "oracle_configuration": {
    "enabled": true,
    "oracle_metrics": {
      "enabled": true,
      "collection_frequency": "30s",
      "connection_parameters": [
        {
          "host": "localhost",
          "port": 1521,
          "service_name": "orcl",
          "username": "wlmagent",
          "secret": {
            "project_id": "my-project",
            "secret_name": "wlmagent_password"
          }
        }
      ]
    }
  }
}

  8. Salva il file di configurazione.

  9. Riavvia l'agente per applicare le nuove impostazioni.

Visualizza le metriche

Puoi visualizzare le metriche raccolte e monitorare le prestazioni e lo stato di Oracle utilizzando Metrics Explorer o importando una dashboard personalizzata.

Visualizzare le metriche in Metrics Explorer

Per visualizzare le metriche Oracle in Metrics Explorer, procedi come segue:

  1. Nella console Google Cloud , vai a Monitoring.
  2. Fai clic su Esplora metriche.
  3. In Trova tipo di risorsa e metrica, segui questi passaggi:
    1. In Tipo di risorsa, seleziona Istanza VM.
    2. Per Metrica, seleziona le metriche Oracle che vuoi visualizzare.

Puoi visualizzare i dati storici e in tempo reale per le metriche Oracle selezionate, utilizzando filtri e aggregazione in base alle esigenze.

Importare una dashboard personalizzata

Per visualizzare le metriche Oracle raccolte dall'agente, puoi creare dashboard Cloud Monitoring personalizzate seguendo le istruzioni riportate in Creare e gestire dashboard personalizzate.

Forniamo una dashboard di esempio oracle-status-overview.json e istruzioni per importarla. La dashboard oracle-status-overview.json mostra i seguenti grafici delle metriche Oracle:

  • Suddivisione del tempo di database
  • Utilizzo memoria database
  • Media delle sessioni attive per classe di attesa
  • I/O disco
  • Utilizzo CPU
  • Traffico di rete

Per importare la dashboard oracle-status-overview.json:

  1. Verifica che gcloud CLI sia installato e aggiornato. Per istruzioni, vedi Installare gcloud CLI.

  2. Dal repository GitHub di Agent for Compute Workloads, scarica la dashboard oracle-status-overview.json:

    $ curl -H "Accept: application/vnd.github.v3.raw" -o oracle-status-overview.json https://api.github.com/repos/GoogleCloudPlatform/workloadagent/contents/observability/dashboards/oracle-status-overview.json

  3. Esegui questo comando per importare la dashboard:

    gcloud alpha monitoring dashboards create --config-from-file=oracle-status-overview.json

    Dopo l'esecuzione del comando, la dashboard personalizzata viene creata in Cloud Monitoring. Per scoprire come visualizzare una dashboard, vedi Trovare e visualizzare una dashboard.

Metriche supportate

Tutte le metriche Oracle raccolte da Agent for Compute Workloads sono disponibili nel percorso workload.googleapis.com/oracle.

Di seguito è riportato un elenco delle metriche Oracle supportate e dei relativi percorsi Cloud Monitoring:

  • Memoria del processo

    • Memoria del processo (PGA) in uso, in byte.

      process/pga_memory/total_used_size

    • Memoria del processo (PGA) allocata, in byte

      process/pga_memory/total_allocated_size

  • Ricordo condiviso

    • Dimensioni dell'elemento di memoria condivisa (SGA), in byte

      process/sga_memory/size

  • Eventi di attesa del sistema

    • Numero totale di attese per una classe di attesa registrata

      sys_wait/count

    • Tempo totale trascorso in questa classe di attesa, in secondi

      sys_wait/time

    • Totale attese in primo piano in questa classe di attesa

      sys_wait/foreground/count

    • Tempo di attesa in primo piano aggregato per questa classe di attesa, in secondi

      sys_wait/foreground/time

  • Tempo trascorso del sistema

    • Tempo trascorso a eseguire chiamate a livello di utente del database, in secondi

      sys_time/db_time

    • Tempo della CPU dedicato alle chiamate a livello di utente del database, in secondi

      sys_time/db_cpu

    • Quantità di tempo trascorso durante l'esecuzione delle istruzioni SQL

      sys_time/sql_execute_elapsed_time

    • Quantità di tempo trascorso nell'analisi delle istruzioni SQL

      sys_time/parse_time_elapsed

    • Quantità di tempo trascorso per l'esecuzione dell'interprete PL/SQL

      sys_time/pl_sql_execution_elapsed_time

    • Tempo trascorso consumato dai processi in background del database, in secondi

      sys_time/background_elapsed_time

  • Statistiche I/O

    • Conteggio totale delle operazioni di lettura (piccole + grandi)

      iostat/read_ops_count

    • Conteggio totale delle operazioni di scrittura (piccole + grandi)

      iostat/write_ops_count

    • Numero totale di byte letti

      iostat/read_bytes_count

    • Numero totale di byte scritti

      iostat/write_bytes_count

    • Latenza media per operazione di I/O

      iostat/average_latency_seconds

  • File di dati

    • Dimensioni allocate del file di dati, in byte

      data_files/total_bytes

    • Spazio del file di dati in uso, in byte

      data_files/bytes_used

    • Spazio libero nel file di dati, in byte

      data_files/available_bytes

    • Limite di estensione automatica dei file di dati, in byte

      data_files/max_bytes

    • Percentuale del file di dati utilizzata

      data_files/percent_used

  • Istanza di database

    • Uptime dell'istanza, in secondi

      instance/uptime

    • Stato istanza

      instance/status

      Questa metrica può avere i seguenti valori:

      UNKNOWN 0
      STARTED 1
      MOUNTED 2
      OPEN 3
      OPEN MIGRATE 4

    • Modalità aperta

      instance/db_open_mode

      Questa metrica può avere i seguenti valori:

      UNKNOWN 0
      MOUNTED 1
      READ WRITE 2
      READ ONLY 3
      READ ONLY WITH APPLY 4

  • Oracle Data Guard

    • Ritardo di applicazione del rifacimento, in secondi

      dataguard/apply_lag

    • Ripeti ritardo di trasporto, in secondi

      dataguard/transport_lag

Gestire l'agente

Riavvia l'agente

Se l'agente per i carichi di lavoro di Compute smette di funzionare o aggiorni la sua configurazione, riavvia l'agente.

  1. Utilizza SSH per connetterti all'istanza VM.

  2. Esegui questo comando:

    sudo systemctl restart google-cloud-workload-agent

Controllare la versione dell'agente

Per controllare la versione dell'agente, completa i seguenti passaggi:

  1. Utilizza SSH per connetterti all'istanza VM.

  2. Esegui questo comando:

    yum info google-cloud-workload-agent

Verifica la disponibilità di aggiornamenti

  1. Utilizza SSH per connetterti all'istanza VM.

  2. Esegui questo comando:

    sudo yum check-update google-cloud-workload-agent

Aggiorna l'agente

Per assicurarti di avere l'ultima versione dell'agente, controlla periodicamente la disponibilità di aggiornamenti e aggiorna l'agente:

  1. Utilizza SSH per connetterti all'istanza VM.

  2. Esegui questo comando:

    sudo yum --nogpgcheck update google-cloud-workload-agent

Visualizza i log dell'agente

I log di Agent for Compute Workloads sono disponibili all'indirizzo /var/log/google-cloud-workload-agent.log.

Il livello di dettaglio dei log è controllato dal parametro log_level. L'impostazione del livello di log DEBUG include informazioni aggiuntive per la risoluzione di problemi specifici, ma produce log molto più grandi.

Per impostazione predefinita, i log dell'agente per i workload di Compute vengono reindirizzati dalle istanze VM a Cloud Logging.

Per visualizzare i log dell'agente in Logging:

  1. Nella console Google Cloud , vai alla pagina Esplora log.

    Vai a Esplora log

  2. Vai al riquadro Query.

  3. Dal menu a discesa Risorse, seleziona Globale e poi fai clic su Applica.

  4. Nell'editor di query, inserisci google-cloud-workload-agent.

  5. Fai clic su Esegui query.

Puoi visualizzare i log generati dall'agente in esecuzione su tutte le tue istanze VM. Puoi filtrare i log per un'istanza specifica.

Configura i log dell'agente in Cloud Logging

Per disattivare il reindirizzamento predefinito dei log dell'agente a Cloud Logging, segui questi passaggi:

  1. Utilizza SSH per connetterti alla tua istanza VM.

  2. Apri il file di configurazione dell'agente:

    /etc/google-cloud-workload-agent/configuration.json

  3. Per la proprietà log_to_cloud, aggiorna il valore a false.

  4. Salva il file di configurazione.

  5. Riavvia l'agente affinché questa modifica abbia effetto.

Risoluzione dei problemi

Le sezioni seguenti forniscono informazioni sui problemi comuni relativi all'utilizzo dell'agente per i carichi di lavoro Oracle Database, sulle relative cause e sulla risoluzione.

Autorizzazioni IAM insufficienti

Problema: i log dell'agente per i carichi di lavoro di Compute mostrano un errore di autorizzazioni IAM insufficienti.

googleapi: Error 403: The client is not authorized to make this request.

Causa: il account di servizio utilizzato dall'agente non dispone delle autorizzazioni IAM richieste per accedere alle API Google Cloud o a una password per l'utente Oracle in Secret Manager.

Risoluzione:per risolvere il problema, assicurati che il account di servizio VM disponga dei ruoli e delle autorizzazioni IAM menzionati nei prerequisiti.

Ambiti di autenticazione insufficienti

Problema: i log di Agent for Compute Workloads mostrano ambiti di autenticazione insufficienti.

googleapi: Error 403: Request had insufficient authentication scopes.

Causa: l'account di servizio utilizzato dall'agente non dispone dell'ambito di accesso richiesto.

Soluzione:per risolvere il problema, configura gli ambiti di accesso della VM su cloud-platform.

Le metriche non vengono visualizzate in Cloud Monitoring

Problema: le metriche dell'agente per i workload di Compute non sono visibili in Cloud Monitoring.

Causa:

Di seguito sono elencate le possibili cause di questo problema:

  • Il account di servizio utilizzato dall'agente per i carichi di lavoro di Compute non dispone delle autorizzazioni IAM necessarie.
  • L'utente Oracle utilizzato dall'agente non dispone di privilegi sufficienti per eseguire query sulle viste delle prestazioni.
  • Sono presenti errori nella configurazione dell'agente.

Risoluzione:

  • Per risolvere il problema delle autorizzazioni insufficienti per il account di servizio:

    1. Nella console Google Cloud , vai alla pagina Dettagli istanza VM e annotati ilaccount di serviziot utilizzato dall'istanza che esegue l'agente.
    2. Vai alla pagina IAM e amministrazione e assicurati che il account di servizio disponga di tutti i ruoli e le autorizzazioni richiesti menzionati nei prerequisiti. Concedi all'account di servizio uno dei ruoli obbligatori mancanti.

  • Per risolvere il problema delle autorizzazioni insufficienti per l'utente Oracle:

    1. Verifica che l'utente Oracle disponga delle seguenti autorizzazioni richieste per eseguire query sulle viste delle prestazioni:

      • SESSION
      • SELECT_CATALOG_ROLE
      • SYSDG

    2. Concedi le autorizzazioni mancanti eseguendo il seguente comando SQL:

      -- Grant the "wlmagent" user the required permissions
GRANT CREATE SESSION,SELECT_CATALOG_ROLE,SYSDG TO USERNAME;

  • Per risolvere il problema di configurazione errata dell'agente:

    1. Utilizza SSH per connetterti alla tua istanza VM.

    2. Controlla i log dell'agente per identificare eventuali errori o problemi che impediscono la raccolta delle metriche. Puoi trovare i log all'indirizzo /var/log/google-cloud-workload-agent.log.

      Cerca errori di autorizzazione, errori di configurazione o problemi di connettività.

    3. Risolvi eventuali errori.

    4. Riavvia l'agente e controlla se la raccolta delle metriche viene avviata.

Impossibile caricare il file di configurazione

Problema:se il file di configurazione contiene valori non validi, viene visualizzato il seguente errore. 

"Failed to load configuration","pid":3524,"error":"proto: (line 19:42): unknown
field "{field_name}"

Risoluzione:per risolvere il problema, aggiorna il file di configurazione utilizzando i dettagli in Parametri di configurazione.

Impossibile inizializzare la raccolta dei dati

Problema:dopo l'installazione dell'agente, se il file di configurazione non viene aggiornato, viene visualizzato il seguente errore: 

"Failed to initialize guest collection","pid":2112,"error":"invalid value for "user_name" "secret_name"

Soluzione:per risolvere il problema, inizializza la configurazione delle credenziali utilizzando i parametri di configurazione.