Configura el agente para Oracle

Puedes configurar el agente de Google Cloudpara cargas de trabajo de Compute en el host junto con tu base de datos de Oracle para recopilar métricas y supervisar tus cargas de trabajo de la base de datos de Oracle.

En este documento, se muestra cómo instalar, configurar y verificar el agente para cargas de trabajo de Compute en instancias de Compute Engine que ejecutan cargas de trabajo de Oracle Database.

El agente recopila varias métricas de Oracle consultando las vistas de rendimiento de la base de datos de Oracle (como V$DATABASE, V$INSTANCE y V$DATAGUARD_STATS) y las vistas del diccionario de datos (como DBA_DATA_FILES y DBA_FREE_SPACE). Luego, estas métricas se envían a Cloud Monitoring, donde se pueden visualizar y analizar. Consulta Métricas admitidas.

Requisitos del sistema

Sistemas operativos Versiones de Oracle Ediciones de Oracle
  • Versiones 7, 8 y 9 de Red Hat Enterprise Linux
  • Versiones 7, 8 y 9 de Oracle Linux
  • Oracle Database 19c
  • Oracle Database 23ai*
  • Edición Enterprise
  • Standard Edition
  • Edición Express (gratis)

Requisitos previos

Antes de instalar el agente para cargas de trabajo de Compute y supervisar tus cargas de trabajo de Oracle Database, asegúrate de que se cumplan los siguientes requisitos previos:

Instala el agente

Para instalar el agente para cargas de trabajo de Compute, haz lo siguiente:

  1. Crea un archivo de configuración del repositorio.

    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. Actualiza los metadatos del administrador de paquetes.

    sudo yum makecache
    
  3. Instala el paquete google-cloud-workload-agent rpm.

    sudo yum install google-cloud-workload-agent
    

Después de instalar el agente para Oracle, verifica la instalación del agente.

Verifica la instalación del agente

Para verificar que el agente esté en ejecución, selecciona tu sistema operativo y, luego, sigue estos pasos:

  1. Usa SSH para conectarte a tu instancia de VM.
  2. Ejecuta el siguiente comando:

    systemctl status google-cloud-workload-agent
    

    Si el agente funciona de forma correcta, el resultado contendrá active (running). Por ejemplo:

    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 el agente no se está ejecutando, intenta reiniciarlo.

Configura el agente

Después de instalar el agente para cargas de trabajo de Compute, de forma opcional, puedes habilitar otras funciones del agente si actualizas su archivo de configuración. Para obtener una lista de los parámetros que puedes configurar para las cargas de trabajo de Oracle Database, consulta Parámetros de configuración.

Después de configurar el agente, puedes volver a verificar la instalación para asegurarte de que el agente esté configurado correctamente.

Parámetros de configuración

El agente para cargas de trabajo de Compute admite los siguientes parámetros de configuración para Oracle:

Parámetro Descripción
log_level

String

Para configurar el nivel de registro del agente, agrega los niveles de registro. Los niveles de registro disponibles son los siguientes:
  • DEBUG
  • INFO
  • WARNING
  • ERROR
El valor predeterminado es INFO.
log_to_cloud

Boolean

Para redireccionar los registros del agente a Cloud Logging, especifica true. El valor predeterminado es true.

oracle_configuration.enabled

Boolean

Opcional. Determina si el servicio de Oracle está activo. Cuando se establece en true, o si no se establece y la carga de trabajo está presente, puedes configurar la detección y la recopilación de métricas. Si se configura como false, se inhabilitan el servicio de Oracle y sus funcionalidades relacionadas.

Los siguientes parámetros secundarios solo se aplican cuando especificas oracle_configuration.enabled: true.
oracle_configuration.oracle_discovery.enabled

Boolean

Opcional. Determina si el Oracle Discovery está activo.

El valor predeterminado es true.

oracle_configuration.oracle_discovery.update_frequency

Int

Opcional. Especifica el intervalo de muestra, en segundos, que determina la frecuencia con la que el agente para cargas de trabajo de Compute ejecuta el proceso de detección. El valor predeterminado es 3,600 segundos (1 hora).

Asegúrate de que el valor termine con una "s" en minúscula para indicar segundos. Por ejemplo: 30s.

oracle_configuration.oracle_metrics.enabled

Boolean

Opcional. Para permitir que el agente para cargas de trabajo de Compute recopile las métricas de supervisión de Oracle, especifica true. El valor predeterminado es false.

Los siguientes parámetros secundarios solo se aplican cuando especificas oracle_metrics.enabled: true.

oracle_configuration.oracle_metrics.collection_frequency

Int

Opcional. Especifica el intervalo de muestra, en segundos, que determina la frecuencia con la que el agente para cargas de trabajo de Compute consulta tus instancias de Oracle Database para recopilar las métricas de supervisión de Oracle. El valor predeterminado es 60 segundos.

Asegúrate de que el valor termine con una "s" en minúscula para indicar segundos. Por ejemplo: 30s.

oracle_configuration.oracle_metrics.query_timeout

String

Opcional. Especifica el tiempo de espera para cada consulta realizada a las instancias de la base de datos de Oracle. El valor predeterminado es 10 segundos.

Asegúrate de que el valor termine con una "s" en minúscula para indicar segundos. Por ejemplo: 30s.

oracle_configuration.oracle_metrics.connection_parameters.username

String

Especifica la cuenta de usuario que se usa para consultar la instancia de la base de datos de Oracle.

Asegúrate de que este usuario tenga los permisos necesarios para leer las vistas de rendimiento en tu base de datos de Oracle.

oracle_configuration.oracle_metrics.connection_parameters.host

String

Especifica el identificador de la máquina local que aloja la instancia de la base de datos.

oracle_configuration.oracle_metrics.connection_parameters.port

Int

Especifica el puerto en el que la instancia de Oracle Database acepta consultas.

oracle_configuration.oracle_metrics.connection_parameters.service_name

String

Especifica el nombre del servicio de la instancia de Oracle Database que deseas que supervise el agente.

oracle_configuration.oracle_metrics.connection_parameters.secret.project_id

String

Especifica el ID del proyecto de Secret Manager para recuperar la contraseña del usuario que realiza consultas a la base de datos.

oracle_configuration.oracle_metrics.connection_parameters.secret.secret_name

String

Especifica el nombre del secreto en Secret Manager que almacena la contraseña de la cuenta de usuario.

Recopila y visualiza métricas de Oracle

Puedes habilitar la recopilación de métricas para las cargas de trabajo de Oracle Database. Consulta las métricas admitidas.

Habilita la recopilación de métricas

Para habilitar la recopilación de métricas de Oracle con el agente para cargas de trabajo de Compute, haz lo siguiente:

  1. Usa SSH para conectarte a tu instancia de VM.

  2. Como usuario del SO de Oracle, ejecuta la herramienta oraenv para establecer las variables de entorno. Suponemos que ya definiste el usuario oracle y el ORACLE_SID en el archivo /etc/oratab.

    sudo su - oracle
    export PATH=$PATH:/usr/local/bin
    . oraenv
    sqlplus / as sysdba
    
  3. Como usuario SYSDBA o SYSOPER, en Oracle Database, crea un usuario para la supervisión con una contraseña que coincida con el secreto que creaste en los requisitos previos.

    CREATE USER wlmagent IDENTIFIED BY password;
    
  4. Como usuario SYSDBA o SYSOPER, otorga los siguientes permisos al usuario de supervisión para consultar las vistas de rendimiento:

    • SESSION
    • SELECT_CATALOG_ROLE
    • SYSDG
    GRANT CREATE SESSION,SELECT_CATALOG_ROLE,SYSDG TO wlmagent;
    
  5. Sal de sqlplus y del usuario oracle.

  6. Como usuario raíz, edita el archivo de configuración del agente con tu editor preferido.

    sudo nano /etc/google-cloud-workload-agent/configuration.json
    
  7. En el archivo de configuración, edita la sección oracle_metrics para realizar las siguientes actualizaciones:

    1. Establece el parámetro enabled en true.
    2. Establece el parámetro service_name para especificar el nombre del servicio de la instancia de Oracle que deseas que supervise el agente.
    3. Especifica el nombre de usuario de Oracle para que el agente se conecte a tu base de datos.
    4. Establece los parámetros host y port para que el agente se conecte a tu base de datos.
    5. Establece el parámetro secret para que el agente recupere una contraseña para el nombre de usuario:
      • project_id: Es el ID del proyecto que contiene los datos de Secret Manager.
      • secret_name: Es el nombre del secreto en Secret Manager.

    A continuación, se muestra un ejemplo de un archivo de configuración:

    {
      "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. Guarda el archivo de configuración.

  9. Reinicia el agente para que se aplique la configuración nueva.

Visualiza las métricas

Puedes ver las métricas recopiladas y supervisar el rendimiento y el estado de Oracle con el Explorador de métricas o importando un panel personalizado.

Visualiza métricas en el Explorador de métricas

Para ver las métricas de Oracle en el Explorador de métricas, haz lo siguiente:

  1. En la consola de Google Cloud , ve a Monitoring.
  2. Haz clic en Explorador de métricas.
  3. En Buscar tipo de recurso y métrica, haz lo siguiente:
    1. En Tipo de recurso, seleccione Instancia de VM.
    2. En Métrica, selecciona las métricas de Oracle que deseas ver.

Puedes ver datos históricos y en tiempo real de las métricas de Oracle seleccionadas, y usar filtros y agregaciones según sea necesario.

Cómo importar un panel personalizado

Para ver las métricas de Oracle recopiladas por el agente, puedes crear paneles personalizados de Cloud Monitoring siguiendo las instrucciones en Crea y administra paneles personalizados.

Proporcionamos un panel de ejemplo oracle-status-overview.json y las instrucciones para importarlo. En el panel de oracle-status-overview.json, se muestran los siguientes gráficos de métricas de Oracle:

  • Desglose del tiempo de la base de datos
  • Uso de memoria de la base de datos
  • Promedio de sesiones activas por clase de espera
  • E/S de disco
  • Uso de CPU
  • Tráfico de red

Para importar el panel de oracle-status-overview.json, haz lo siguiente:

  1. Verifica que gcloud CLI esté instalada y actualizada. Para obtener instrucciones, consulta Instala gcloud CLI.

  2. En el repositorio de GitHub del agente para cargas de trabajo de Compute, descarga el panel 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. Ejecuta el siguiente comando para importar el panel:

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

    Después de ejecutar el comando, se creará el panel personalizado en Cloud Monitoring. Para obtener información sobre cómo ver un panel, consulta Cómo encontrar y ver un panel.

Métricas admitidas

Todas las métricas de Oracle que recopila el agente para cargas de trabajo de procesamiento están disponibles en la ruta de acceso workload.googleapis.com/oracle.

A continuación, se incluye una lista de las métricas de Oracle admitidas y sus rutas de Cloud Monitoring correspondientes:

  • Memoria del proceso

    • Memoria del proceso (PGA) en uso, en bytes.

      process/pga_memory/total_used_size

    • Memoria del proceso (PGA) asignada, en bytes

      process/pga_memory/total_allocated_size

  • Memoria compartida

    • Tamaño del elemento de memoria compartida (SGA), en bytes

      process/sga_memory/size

  • Eventos de espera del sistema

    • Cantidad total de esperas para una clase de espera registrada

      sys_wait/count

    • Tiempo agregado dedicado a esta clase de espera, en segundos

      sys_wait/time

    • Cantidad total de esperas en primer plano en esta clase de espera

      sys_wait/foreground/count

    • Tiempo de espera en primer plano agregado para esta clase de espera, en segundos

      sys_wait/foreground/time

  • Tiempo transcurrido del sistema

    • Tiempo transcurrido dedicado a realizar llamadas a nivel del usuario de la base de datos, en segundos

      sys_time/db_time

    • Tiempo de CPU empleado en llamadas a nivel del usuario de la base de datos, en segundos

      sys_time/db_cpu

    • Cantidad de tiempo transcurrido durante la ejecución de las instrucciones de SQL

      sys_time/sql_execute_elapsed_time

    • Cantidad de tiempo transcurrido dedicado al análisis de instrucciones de SQL

      sys_time/parse_time_elapsed

    • Cantidad de tiempo transcurrido durante la ejecución del intérprete de PL/SQL

      sys_time/pl_sql_execution_elapsed_time

    • Tiempo transcurrido que consumen los procesos en segundo plano de la base de datos, en segundos

      sys_time/background_elapsed_time

  • Estadísticas de E/S

    • Recuento total de operaciones de lectura (pequeñas y grandes)

      iostat/read_ops_count

    • Recuento total de operaciones de escritura (pequeñas y grandes)

      iostat/write_ops_count

    • Cantidad total de bytes leídos

      iostat/read_bytes_count

    • Cantidad total de bytes escritos

      iostat/write_bytes_count

    • Latencia promedio por operación de E/S

      iostat/average_latency_seconds

  • Archivos de datos

    • Tamaño asignado del archivo de datos, en bytes

      data_files/total_bytes

    • Espacio de archivo de datos en uso, en bytes

      data_files/bytes_used

    • Espacio libre del archivo de datos, en bytes

      data_files/available_bytes

    • Límite de extensión automática de archivos de datos, en bytes

      data_files/max_bytes

    • Porcentaje del archivo de datos utilizado

      data_files/percent_used

  • Instancia de base de datos

    • Tiempo de actividad de la instancia, en segundos

      instance/uptime

    • Estado de la instancia

      instance/status

      Esta métrica puede tener los siguientes valores:

      UNKNOWN 0
      STARTED 1
      MOUNTED 2
      OPEN 3
      OPEN MIGRATE 4
    • Modo abierto

      instance/db_open_mode

      Esta métrica puede tener los siguientes valores:

      UNKNOWN 0
      MOUNTED 1
      READ WRITE 2
      READ ONLY 3
      READ ONLY WITH APPLY 4
  • Oracle Data Guard

    • Retraso de aplicación de rehacer, en segundos

      dataguard/apply_lag

    • Retraso de rehacer el transporte, en segundos

      dataguard/transport_lag

Administra el agente

Reinicia el agente

Si el agente para cargas de trabajo de Compute deja de funcionar o actualizas su configuración, reinicia el agente.

  1. Usa SSH para conectarte a la instancia de VM.
  2. Ejecuta el siguiente comando:

    sudo systemctl restart google-cloud-workload-agent

Verifica la versión del agente

Para ver la versión de tu agente, completa los siguientes pasos:

  1. Usa SSH para conectarte a la instancia de VM.
  2. Ejecuta el siguiente comando:

    yum info google-cloud-workload-agent
    

Busca actualizaciones

  1. Usa SSH para conectarte a la instancia de VM.
  2. Ejecuta el siguiente comando:

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

Actualiza el agente

Para asegurarte de tener la versión más reciente del agente, verifica si hay actualizaciones periódicamente y actualiza el agente:

  1. Usa SSH para conectarte a la instancia de VM.
  2. Ejecuta el siguiente comando:

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

Cómo ver los registros del agente

Los registros del agente de cargas de trabajo de procesamiento están disponibles en /var/log/google-cloud-workload-agent.log.

El parámetro log_level controla el nivel de detalle del registro. El parámetro de configuración del nivel de registro DEBUG incluye información adicional para solucionar problemas específicos, pero genera registros mucho más grandes.

De forma predeterminada, los registros del agente para cargas de trabajo de Compute se redireccionan desde tus instancias de VM a Cloud Logging.

Para ver los registros del agente en Logging, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Explorador de registros.

    Ir al Explorador de registros

  2. Ve al panel Consulta.

  3. En el menú desplegable Recursos, selecciona Global y, luego, haz clic en Aplicar.

  4. En el Editor de consultas, ingresa google-cloud-workload-agent.

  5. Haz clic en Ejecutar consulta.

Puedes ver los registros que genera el agente que se ejecuta en todas tus instancias de VM. Puedes filtrar los registros de una instancia específica.

Configura los registros del agente en Cloud Logging

Para inhabilitar el redireccionamiento predeterminado de los registros del agente a Cloud Logging, sigue estos pasos:

  1. Usa SSH para conectarte a tu instancia de VM.

  2. Reemplaza el archivo de configuración del agente:

    /etc/google-cloud-workload-agent/configuration.json
  3. Para la propiedad log_to_cloud, actualiza el valor a false.

  4. Guarda el archivo de configuración.

  5. Reinicia el agente para que se aplique este cambio.

Soluciona problemas

En las siguientes secciones, se proporciona información sobre problemas habituales relacionados con el uso del agente para cargas de trabajo de Oracle Database, sus causas y la resolución.

Permisos de IAM insuficientes

Problema: Los registros del Agente para cargas de trabajo de Compute muestran un error de permisos de IAM insuficientes.

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

Causa: La cuenta de servicio que usa el agente no tiene los permisos de IAM necesarios para acceder a las APIs de Google Cloud o una contraseña para el usuario de Oracle en Secret Manager.

Resolución: Para resolver este problema, asegúrate de que la cuenta de servicio de la VM tenga los roles y permisos de IAM que se mencionan en Requisitos previos.

Permisos de autenticación insuficientes

Problema: Los registros del Agente para cargas de trabajo de Compute muestran permisos de autenticación insuficientes.

googleapi: Error 403: Request had insufficient authentication scopes.

Causa: La cuenta de servicio que usa el agente no tiene el permiso de acceso requerido.

Resolución: Para resolver este problema, configura los permisos de acceso de la VM en cloud-platform.

Las métricas no aparecen en Cloud Monitoring

Problema: Las métricas del agente para cargas de trabajo de Compute no se ven en Cloud Monitoring.

Causa:

A continuación, se indican las posibles causas de este problema:

  • La cuenta de servicio que usa el agente para cargas de trabajo de Compute no tiene los permisos de IAM necesarios.
  • El usuario de Oracle que usa el agente no tiene privilegios suficientes para consultar las vistas de rendimiento.
  • Hay errores en la configuración del agente.

Resolución:

  • Para resolver el problema de permisos insuficientes para la cuenta de servicio, haz lo siguiente:

    1. En la Google Cloud consola, ve a la página Detalles de la instancia de VM y anota la cuenta de servicio que usa la instancia que ejecuta el agente.
    2. Ve a la página IAM y administración y asegúrate de que la cuenta de servicio tenga todos los roles y permisos necesarios que se mencionan en los requisitos previos. Otorga cualquiera de los roles faltantes requeridos a la cuenta de servicio.
  • Para resolver el problema de permisos insuficientes para el usuario de Oracle, haz lo siguiente:

    1. Verifica que el usuario de Oracle tenga los siguientes permisos necesarios para consultar las vistas de rendimiento:

      • SESSION
      • SELECT_CATALOG_ROLE
      • SYSDG
    2. Ejecuta el siguiente comando SQL para otorgar cualquiera de los permisos faltantes:

      -- Grant the "wlmagent" user the required permissions
      GRANT CREATE SESSION,SELECT_CATALOG_ROLE,SYSDG TO USERNAME;
      
  • Para resolver el problema de configuración incorrecta del agente, haz lo siguiente:

    1. Usa SSH para conectarte a tu instancia de VM.
    2. Revisa los registros del agente para identificar errores o problemas que impidan la recopilación de métricas. Puedes encontrar los registros en /var/log/google-cloud-workload-agent.log.

      Busca errores de permisos, problemas de configuración o problemas de conectividad.

    3. Resuelve cualquier error.

    4. Reinicia el agente y verifica si se inicia la recopilación de métricas.

No se pudo cargar el archivo de configuración

Problema: Si el archivo de configuración tiene valores no válidos, verás el siguiente error.

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

Resolución: Para resolver este problema, actualiza el archivo de configuración con los detalles que se indican en Parámetros de configuración.

No se pudo inicializar la recopilación de datos

Problema: Después de instalar el agente, si no se actualiza el archivo de configuración, verás el siguiente error:

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

Resolución: Para resolver este problema, inicializa la configuración de credenciales con parámetros de configuración.