Configurer l'agent pour Oracle

Vous pouvez configurer l'agent Google Cloudpour les charges de travail Compute sur l'hôte en même temps que votre base de données Oracle afin de collecter des métriques et de surveiller vos charges de travail de base de données Oracle.

Ce document explique comment installer, configurer et valider l'agent pour les charges de travail Compute sur les instances Compute Engine qui exécutent des charges de travail Oracle Database.

L'agent collecte diverses métriques Oracle en interrogeant les vues de performances de la base de données Oracle (telles que V$DATABASE, V$INSTANCE et V$DATAGUARD_STATS) et les vues du dictionnaire de données (telles que DBA_DATA_FILES et DBA_FREE_SPACE). Ces métriques sont ensuite envoyées à Cloud Monitoring, où elles peuvent être visualisées et analysées. Consultez la section Métriques acceptées.

Configuration requise

Systèmes d'exploitation Versions d'Oracle Éditions Oracle
  • Red Hat Enterprise Linux versions 7, 8 et 9
  • Oracle Linux versions 7, 8 et 9
  • Oracle Database 19c
  • Oracle Database 23ai*
  • Édition Enterprise
  • Édition Standard
  • Édition Express (gratuite)

Prérequis

Avant d'installer l'agent pour les charges de travail Compute afin de surveiller vos charges de travail Oracle Database, assurez-vous que les conditions préalables suivantes sont remplies :

Installer l'agent

Pour installer l'agent pour les charges de travail Compute, procédez comme suit :

  1. Créez un fichier de configuration du dépôt.

    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. Mettez à jour les métadonnées du gestionnaire de paquets.

    sudo yum makecache

  3. Installez le package rpm google-cloud-workload-agent.

    sudo yum install google-cloud-workload-agent

Après avoir installé l'agent pour Oracle, vérifiez son installation.

Vérifier l'installation de l'agent

Pour vérifier que l'agent est en cours d'exécution, sélectionnez votre système d'exploitation, puis procédez comme suit :

  1. Utilisez SSH pour vous connecter à votre instance de VM.

  2. Exécutez la commande suivante :

    systemctl status google-cloud-workload-agent

    Si l'agent fonctionne correctement, le résultat contient active (running). Exemple :

    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.

    Si l'agent n'est pas en cours d'exécution, essayez de le redémarrer.

Configurer l'agent

Après avoir installé l'agent pour les charges de travail Compute, vous pouvez éventuellement activer d'autres fonctionnalités de l'agent en mettant à jour son fichier de configuration. Pour obtenir la liste des paramètres que vous pouvez configurer pour les charges de travail Oracle Database, consultez Paramètres de configuration.

Après avoir configuré l'agent, vous pouvez à nouveau vérifier l'installation pour vous assurer qu'il est correctement configuré.

Paramètres de configuration

L'agent pour les charges de travail Compute est compatible avec les paramètres de configuration suivants pour Oracle :

Paramètre Description
log_level

String

Pour définir le niveau de journalisation de l'agent, ajoutez les niveaux de journalisation. Les niveaux de journalisation disponibles sont les suivants :
  • DEBUG
  • INFO
  • WARNING
  • ERROR
La valeur par défaut est INFO.
log_to_cloud

Boolean

Pour rediriger les journaux de l'agent vers Cloud Logging, spécifiez true. La valeur par défaut est true.
oracle_configuration.enabled

Boolean

Facultatif. Détermine si le service Oracle est actif. Lorsque la valeur est définie sur true ou si elle n'est pas définie et que la charge de travail est présente, vous pouvez configurer la découverte et la collecte de métriques. Si la valeur est définie sur false, le service Oracle et ses fonctionnalités associées sont désactivés.
Les paramètres enfants suivants ne s'appliquent que lorsque vous spécifiez oracle_configuration.enabled: true.
oracle_configuration.oracle_discovery.enabled

Boolean

Facultatif. Détermine si Oracle Discovery est actif.

La valeur par défaut est true.
oracle_configuration.oracle_discovery.update_frequency

Int

Facultatif. Spécifiez l'intervalle d'échantillonnage, en secondes, qui détermine la fréquence à laquelle l'agent pour les charges de travail Compute exécute le processus de découverte. La valeur par défaut est de 3 600 secondes (une heure).

Assurez-vous que la valeur se termine par un "s" minuscule pour indiquer les secondes. Par exemple : 30s.
oracle_configuration.oracle_metrics.enabled

Boolean

Facultatif. Pour permettre à l'agent pour les charges de travail Compute de collecter les métriques de surveillance Oracle, spécifiez true. La valeur par défaut est false.

Les paramètres enfants suivants ne s'appliquent que lorsque vous spécifiez oracle_metrics.enabled: true.
oracle_configuration.oracle_metrics.collection_frequency

Int

Facultatif. Spécifiez l'intervalle d'échantillonnage, en secondes, qui détermine la fréquence à laquelle l'agent pour les charges de travail Compute interroge vos instances Oracle Database pour collecter les métriques de surveillance Oracle. La valeur par défaut est de 60 secondes.

Assurez-vous que la valeur se termine par un "s" minuscule pour indiquer les secondes. Par exemple : 30s.
oracle_configuration.oracle_metrics.query_timeout

String

Facultatif. Indiquez le délai avant expiration de chaque requête adressée aux instances Oracle Database. La valeur par défaut est de 10 secondes.

Assurez-vous que la valeur se termine par un "s" minuscule pour indiquer les secondes. Par exemple : 30s.
oracle_configuration.oracle_metrics.connection_parameters.username

String

Spécifie le compte utilisateur utilisé pour interroger l'instance Oracle Database.

Assurez-vous que cet utilisateur dispose des autorisations requises pour lire les vues de performances dans votre base de données Oracle.
oracle_configuration.oracle_metrics.connection_parameters.host

String

Spécifie l'identifiant de la machine locale qui héberge votre instance de base de données.
oracle_configuration.oracle_metrics.connection_parameters.port

Int

Spécifie le port sur lequel l'instance Oracle Database accepte les requêtes.
oracle_configuration.oracle_metrics.connection_parameters.service_name

String

Spécifie le nom de service de votre instance Oracle Database que vous souhaitez que l'agent surveille.
oracle_configuration.oracle_metrics.connection_parameters.secret.project_id

String

Spécifie l'ID de projet Secret Manager permettant de récupérer le mot de passe de l'utilisateur qui interroge la base de données.
oracle_configuration.oracle_metrics.connection_parameters.secret.secret_name

String

Spécifie le nom du secret dans Secret Manager qui stocke le mot de passe du compte utilisateur.

Collecter et afficher les métriques Oracle

Vous pouvez activer la collecte de métriques pour les charges de travail Oracle Database. Consultez la section Métriques acceptées.

Activer la collecte des métriques

Pour activer la collecte des métriques Oracle à l'aide de l'agent pour les charges de travail Compute, procédez comme suit :

  1. Utilisez SSH pour vous connecter à votre instance de VM.

  2. En tant qu'utilisateur de l'OS Oracle, exécutez l'outil oraenv pour définir les variables d'environnement. Nous partons du principe que vous avez déjà défini l'utilisateur oracle et le ORACLE_SID dans le fichier /etc/oratab.

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

  3. En tant qu'utilisateur SYSDBA ou SYSOPER, dans la base de données Oracle, créez un utilisateur pour la surveillance avec un mot de passe correspondant au secret que vous avez créé dans la section Conditions requises.

    CREATE USER wlmagent IDENTIFIED BY password;

  4. En tant qu'utilisateur SYSDBA ou SYSOPER, accordez les autorisations suivantes à l'utilisateur de surveillance pour qu'il puisse interroger les vues sur les performances :

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

  5. Quittez sqlplus et l'utilisateur oracle.

  6. En tant qu'utilisateur racine, modifiez le fichier de configuration de l'agent à l'aide de l'éditeur de votre choix.

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

  7. Dans le fichier de configuration, modifiez la section oracle_metrics pour apporter les modifications suivantes :

    1. Définissez le paramètre enabled sur true.
    2. Définissez le paramètre service_name pour spécifier le nom de service de l'instance Oracle que vous souhaitez que l'agent surveille.
    3. Spécifiez le nom d'utilisateur Oracle pour que l'agent se connecte à votre base de données.
    4. Définissez les paramètres host et port pour que l'agent se connecte à votre base de données.
    5. Définissez le paramètre secret pour que l'agent récupère un mot de passe pour le nom d'utilisateur :
      • project_id : ID du projet contenant les données Secret Manager.
      • secret_name : nom du secret dans Secret Manager.

    Voici un exemple de fichier de configuration :

    {
  "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. Enregistrez le fichier de configuration.

  9. Redémarrez l'agent pour que les nouveaux paramètres prennent effet.

Afficher les métriques

Vous pouvez afficher les métriques collectées et surveiller les performances et l'état d'Oracle à l'aide de l'explorateur de métriques ou en important un tableau de bord personnalisé.

Afficher les métriques dans l'explorateur de métriques

Pour afficher les métriques Oracle dans l'explorateur de métriques, procédez comme suit :

  1. Dans la console Google Cloud , accédez à Monitoring.
  2. Cliquez sur Explorateur de métriques.
  3. Sous Find resource type and metric (Rechercher un type de ressource et une métrique), procédez comme suit :
    1. Pour Resource type (Type de ressource), sélectionnez VM Instance (Instance de VM).
    2. Pour Métrique, sélectionnez les métriques Oracle que vous souhaitez afficher.

Vous pouvez afficher les données en temps réel et historiques pour les métriques Oracle sélectionnées, en utilisant des filtres et l'agrégation si nécessaire.

Importer un tableau de bord personnalisé

Pour afficher les métriques Oracle collectées par l'agent, vous pouvez créer des tableaux de bord Cloud Monitoring personnalisés en suivant les instructions de la section Créer et gérer des tableaux de bord personnalisés.

Nous fournissons un exemple de tableau de bord oracle-status-overview.json et des instructions pour l'importer. Le tableau de bord oracle-status-overview.json affiche les graphiques de métriques Oracle suivants :

  • Répartition du temps de base de données
  • Utilisation de la mémoire de la base de données
  • Moyenne des sessions actives par classe d'attente
  • E/S disque
  • Utilisation du processeur
  • Trafic réseau

Pour importer le tableau de bord oracle-status-overview.json :

  1. Vérifiez que gcloud CLI est installé et à jour. Pour obtenir des instructions, consultez Installer gcloud CLI.

  2. Dans le dépôt GitHub de l'agent pour les charges de travail Compute, téléchargez le tableau de bord 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. Exécutez la commande suivante pour importer le tableau de bord :

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

    Une fois la commande exécutée, le tableau de bord personnalisé est créé dans Cloud Monitoring. Pour savoir comment afficher un tableau de bord, consultez Rechercher et afficher un tableau de bord.

Métriques acceptées

Toutes les métriques Oracle collectées par l'agent pour les charges de travail de calcul sont disponibles sous le chemin d'accès workload.googleapis.com/oracle.

Vous trouverez ci-dessous la liste des métriques Oracle compatibles et de leurs chemins Cloud Monitoring correspondants :

  • Mémoire du processus

    • Mémoire de processus (PGA) utilisée, en octets.

      process/pga_memory/total_used_size

    • Mémoire de processus (PGA) allouée, en octets

      process/pga_memory/total_allocated_size

  • Souvenir partagé

    • Taille de l'élément de mémoire partagée (SGA), en octets

      process/sga_memory/size

  • Événements d'attente du système

    • Nombre total d'attentes pour une classe d'attente enregistrée

      sys_wait/count

    • Temps total passé dans cette classe d'attente, en secondes

      sys_wait/time

    • Nombre total d'attentes au premier plan dans cette classe d'attente

      sys_wait/foreground/count

    • Temps d'attente au premier plan agrégé pour cette classe d'attente, en secondes

      sys_wait/foreground/time

  • Temps écoulé du système

    • Temps écoulé pour effectuer des appels au niveau de l'utilisateur de la base de données, en secondes

      sys_time/db_time

    • Temps CPU passé sur les appels au niveau de l'utilisateur de la base de données, en secondes

      sys_time/db_cpu

    • Temps écoulé pendant l'exécution des instructions SQL

      sys_time/sql_execute_elapsed_time

    • Temps écoulé passé à analyser les instructions SQL

      sys_time/parse_time_elapsed

    • Temps écoulé passé à exécuter l'interpréteur PL/SQL

      sys_time/pl_sql_execution_elapsed_time

    • Temps écoulé consommé par les processus d'arrière-plan de la base de données, en secondes

      sys_time/background_elapsed_time

  • Statistiques d'E/S

    • Nombre total d'opérations de lecture (petites et grandes)

      iostat/read_ops_count

    • Nombre total d'opérations d'écriture (petites et grandes)

      iostat/write_ops_count

    • Nombre total d'octets lus

      iostat/read_bytes_count

    • Nombre total d'octets écrits

      iostat/write_bytes_count

    • Latence moyenne par opération d'E/S

      iostat/average_latency_seconds

  • Fichiers de données

    • Taille allouée du fichier de données, en octets

      data_files/total_bytes

    • Espace utilisé par les fichiers de données, en octets

      data_files/bytes_used

    • Espace libre dans le fichier de données, en octets

      data_files/available_bytes

    • Limite d'extension automatique des fichiers de données, en octets

      data_files/max_bytes

    • Pourcentage du fichier de données utilisé

      data_files/percent_used

  • Instance de base de données

    • Temps d'activité de l'instance, en secondes

      instance/uptime

    • État de l'instance

      instance/status

      Cette métrique peut prendre les valeurs suivantes :

      UNKNOWN 0
      STARTED 1
      MOUNTED 2
      OPEN 3
      OPEN MIGRATE 4

    • Mode ouvert

      instance/db_open_mode

      Cette métrique peut prendre les valeurs suivantes :

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

  • Oracle Data Guard

    • Délai d'application du rétablissement, en secondes

      dataguard/apply_lag

    • Délai de rétablissement, en secondes

      dataguard/transport_lag

Gérer l'agent

Redémarrer l'agent

Si l'agent pour les charges de travail Compute cesse de fonctionner ou si vous mettez à jour sa configuration, redémarrez l'agent.

  1. Utilisez SSH pour vous connecter à l'instance de VM.

  2. Exécutez la commande suivante :

    sudo systemctl restart google-cloud-workload-agent

Vérifier la version de l'agent

Pour afficher la version de l'agent, procédez comme suit :

  1. Utilisez SSH pour vous connecter à l'instance de VM.

  2. Exécutez la commande suivante :

    yum info google-cloud-workload-agent

Rechercher des mises à jour

  1. Utilisez SSH pour vous connecter à l'instance de VM.

  2. Exécutez la commande suivante :

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

Mettre à jour l'agent

Pour vous assurer que vous disposez de la dernière version de l'agent, vérifiez régulièrement si des mises à jour sont disponibles et mettez à jour l'agent :

  1. Utilisez SSH pour vous connecter à l'instance de VM.

  2. Exécutez la commande suivante :

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

Afficher les journaux de l'agent

Les journaux de l'agent for Compute Workloads sont disponibles sur /var/log/google-cloud-workload-agent.log.

La verbosité des journaux est contrôlée par le paramètre log_level. La définition du niveau de journalisation DEBUG inclut des informations supplémentaires pour résoudre des problèmes spécifiques, mais génère des journaux beaucoup plus volumineux.

Par défaut, les journaux de l'agent pour les charges de travail de calcul sont redirigés depuis vos instances de VM vers Cloud Logging.

Pour afficher les journaux de l'agent dans Logging, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Explorateur de journaux.

    Accéder à l'explorateur de journaux

  2. Accédez au volet Requête.

  3. Dans le menu déroulant Ressources, sélectionnez Global, puis cliquez sur Appliquer.

  4. Dans l'éditeur de requêtes, saisissez google-cloud-workload-agent.

  5. Cliquez sur Exécuter la requête.

Vous pouvez afficher les journaux générés par l'agent s'exécutant sur toutes vos instances de VM. Vous pouvez filtrer les journaux pour une instance spécifique.

Configurer les journaux de l'agent dans Cloud Logging

Pour désactiver la redirection par défaut des journaux de l'agent vers Cloud Logging, procédez comme suit :

  1. Utilisez SSH pour vous connecter à votre instance de VM.

  2. Modifiez le fichier de configuration de l'agent :

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

  3. Pour la propriété log_to_cloud, remplacez la valeur par false.

  4. Enregistrez le fichier de configuration.

  5. Redémarrez l'agent pour que cette modification soit prise en compte.

Dépannage

Les sections suivantes fournissent des informations sur les problèmes courants liés à l'utilisation de l'agent pour les charges de travail Oracle Database, leurs causes et leur résolution.

Autorisations IAM insuffisantes

Problème : les journaux de l'agent pour les charges de travail Compute affichent une erreur d'autorisation IAM insuffisante.

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

Cause : Le compte de service utilisé par l'agent ne dispose pas des autorisations IAM requises pour accéder aux API Google Cloud ou d'un mot de passe pour l'utilisateur Oracle dans Secret Manager.

Résolution : Pour résoudre ce problème, assurez-vous que le compte de service de la VM dispose des rôles et autorisations IAM mentionnés dans Conditions préalables.

Champs d'application d'authentification insuffisants

Problème : les journaux de l'agent pour les charges de travail Compute indiquent des niveaux d'authentification insuffisants.

googleapi: Error 403: Request had insufficient authentication scopes.

Cause : le compte de service utilisé par l'agent ne dispose pas du niveau d'accès#39;application requis.

Solution : pour résoudre ce problème, configurez les champs d'application d'accès de la VM sur cloud-platform.

Les métriques n'apparaissent pas dans Cloud Monitoring

Problème : Les métriques de l'agent pour les charges de travail Compute ne sont pas visibles dans Cloud Monitoring.

Cause :

Voici les causes possibles de ce problème :

  • Le compte de service utilisé par l'agent pour les charges de travail Compute ne dispose pas des autorisations IAM nécessaires.
  • L'utilisateur Oracle utilisé par l'agent ne dispose pas des droits suffisants pour interroger les vues de performances.
  • La configuration de l'agent comporte des erreurs.

Solution :

  • Pour résoudre le problème lié aux autorisations insuffisantes du compte de service, procédez comme suit :

    1. Dans la console Google Cloud , accédez à la page Informations sur l'instance de VM et notez le compte de service utilisé par l'instance exécutant l'agent.
    2. Accédez à la page IAM et administration et assurez-vous que le compte de service dispose de tous les rôles et autorisations requis mentionnés dans les conditions préalables. Attribuez au compte de service les rôles manquants requis.

  • Pour résoudre le problème d'autorisations insuffisantes pour l'utilisateur Oracle :

    1. Vérifiez que l'utilisateur Oracle dispose des autorisations requises suivantes pour interroger les vues de performances :

      • SESSION
      • SELECT_CATALOG_ROLE
      • SYSDG

    2. Accordez les autorisations manquantes en exécutant la commande SQL suivante :

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

  • Pour résoudre le problème de configuration incorrecte de l'agent, procédez comme suit :

    1. Utilisez SSH pour vous connecter à votre instance de VM.

    2. Examinez les journaux de l'agent pour identifier les erreurs ou les problèmes qui empêchent la collecte des métriques. Vous trouverez les journaux sur /var/log/google-cloud-workload-agent.log.

      Recherchez les erreurs d'autorisation, les erreurs de configuration ou les problèmes de connectivité.

    3. Corrigez les erreurs.

    4. Redémarrez l'agent et vérifiez si la collecte de métriques commence.

Échec du chargement du fichier de configuration

Problème : si le fichier de configuration contient des valeurs non valides, l'erreur suivante s'affiche. 

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

Résolution : pour résoudre ce problème, mettez à jour le fichier de configuration en utilisant les informations de la section Paramètres de configuration.

Échec de l'initialisation de la collecte de données

Problème : Si le fichier de configuration n'est pas mis à jour après l'installation de l'agent, l'erreur suivante s'affiche : 

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

Résolution : pour résoudre ce problème, initialisez la configuration des identifiants à l'aide des paramètres de configuration.