Configurar o agente para Oracle

É possível configurar o agente do Google Cloudpara cargas de trabalho de computação no host junto com o Oracle Database para coletar métricas e monitorar as cargas de trabalho do Oracle Database.

Neste documento, mostramos como instalar, configurar e verificar o agente para cargas de trabalho do Compute em instâncias do Compute Engine que executam cargas de trabalho do Oracle Database.

O agente coleta várias métricas do Oracle consultando visualizações de desempenho do Oracle Database (como V$DATABASE, V$INSTANCE e V$DATAGUARD_STATS) e visualizações do dicionário de dados (como DBA_DATA_FILES e DBA_FREE_SPACE). Essas métricas são enviadas ao Cloud Monitoring, onde podem ser visualizadas e analisadas. Consulte Métricas compatíveis.

Requisitos do sistema

Sistemas operacionais Versões do Oracle Edições da Oracle
  • Red Hat Enterprise Linux versões 7, 8 e 9
  • Versões 7, 8 e 9 do Oracle Linux
  • Oracle Database 19c
  • Oracle Database 23ai*
  • Enterprise Edition
  • Standard Edition
  • Edição Express (gratuita)

Pré-requisitos

Antes de instalar o agente para cargas de trabalho do Compute para monitorar suas cargas de trabalho do Oracle Database, verifique se os seguintes pré-requisitos foram atendidos:

Instalar o agente

Para instalar o agente para cargas de trabalho do Compute, faça o seguinte:

  1. Crie um arquivo de configuração do repositório.

    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. Atualize os metadados do gerenciador de pacotes.

    sudo yum makecache

  3. Instale o pacote rpm google-cloud-workload-agent.

    sudo yum install google-cloud-workload-agent

Depois de instalar o agente para Oracle, verifique a instalação.

Verificar a instalação do agente

Para verificar se o agente está em execução, selecione seu sistema operacional e siga as etapas:

  1. Use SSH para se conectar à instância de VM.

  2. Execute este comando:

    systemctl status google-cloud-workload-agent

    Se o agente estiver funcionando corretamente, a saída vai conter active (running). Exemplo:

    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 o agente não estiver em execução, tente reiniciar o agente.

Configurar o agente

Depois de instalar o agente para cargas de trabalho do Compute, é possível ativar outros recursos do agente atualizando o arquivo de configuração dele. Para uma lista de parâmetros que podem ser configurados para cargas de trabalho do Oracle Database, consulte Parâmetros de configuração.

Depois de configurar o agente, verifique a instalação novamente para garantir que o agente esteja configurado corretamente.

Parâmetros de configuração

O agente para cargas de trabalho do Compute é compatível com os seguintes parâmetros de configuração para Oracle:

Parâmetro Descrição
log_level

String

Para definir o nível de geração de registros do agente, adicione-os. Os níveis de registro disponíveis são os seguintes:
  • DEBUG
  • INFO
  • WARNING
  • ERROR
O padrão é INFO.
log_to_cloud

Boolean

Para redirecionar os registros do agente para o Cloud Logging, especifique true. O padrão é true.
oracle_configuration.enabled

Boolean

Opcional. Determina se o serviço do Oracle está ativo. Quando definido como true ou se não estiver definido e a carga de trabalho estiver presente, você poderá configurar a descoberta e a coleta de métricas. Se definido como false, o serviço do Oracle e as funcionalidades relacionadas serão desativados.
Os parâmetros filhos a seguir são aplicáveis somente quando você especifica oracle_configuration.enabled: true.
oracle_configuration.oracle_discovery.enabled

Boolean

Opcional. Determina se a descoberta do Oracle está ativa.

O valor padrão é true.
oracle_configuration.oracle_discovery.update_frequency

Int

Opcional. Especifique o intervalo de amostra, em segundos, que determina a frequência com que o agente para cargas de trabalho do Compute executa o processo de descoberta. O valor padrão é de 3.600 segundos (1 hora).

Verifique se o valor termina com um "s" minúsculo para indicar segundos. Por exemplo: 30s.
oracle_configuration.oracle_metrics.enabled

Boolean

Opcional. Para permitir que o agente para cargas de trabalho de computação colete as métricas de monitoramento do Oracle, especifique true. O valor padrão é false.

Os parâmetros filhos a seguir são aplicáveis somente quando você especifica oracle_metrics.enabled: true.
oracle_configuration.oracle_metrics.collection_frequency

Int

Opcional. Especifique o intervalo de amostra, em segundos, que determina a frequência com que o agente para cargas de trabalho do Compute consulta as instâncias do banco de dados Oracle para coletar as métricas de monitoramento do Oracle. O valor padrão é de 60 segundos.

Verifique se o valor termina com um "s" minúsculo para indicar segundos. Por exemplo: 30s.
oracle_configuration.oracle_metrics.query_timeout

String

Opcional. Especifique o tempo limite de cada consulta feita às instâncias do Oracle Database. O valor padrão é de 10 segundos.

Verifique se o valor termina com um "s" minúsculo para indicar segundos. Por exemplo: 30s.
oracle_configuration.oracle_metrics.connection_parameters.username

String

Especifica a conta de usuário usada para consultar a instância do Oracle Database.

Verifique se esse usuário tem as permissões necessárias para ler as visualizações de desempenho no banco de dados Oracle.
oracle_configuration.oracle_metrics.connection_parameters.host

String

Especifica o identificador da máquina local que hospeda a instância do banco de dados.
oracle_configuration.oracle_metrics.connection_parameters.port

Int

Especifica a porta em que a instância do Oracle Database aceita consultas.
oracle_configuration.oracle_metrics.connection_parameters.service_name

String

Especifica o nome do serviço da instância do Oracle Database que você quer que o agente monitore.
oracle_configuration.oracle_metrics.connection_parameters.secret.project_id

String

Especifica o ID do projeto do Secret Manager para recuperar a senha do usuário que faz consultas no banco de dados.
oracle_configuration.oracle_metrics.connection_parameters.secret.secret_name

String

Especifica o nome do secret no Secret Manager que armazena a senha da conta de usuário.

Coletar e visualizar métricas do Oracle

É possível ativar a coleta de métricas para cargas de trabalho do Oracle Database. Consulte Métricas compatíveis.

Ativar a coleta de métricas

Para ativar a coleta de métricas do Oracle usando o agente para cargas de trabalho do Compute, faça o seguinte:

  1. Use SSH para se conectar à instância de VM.

  2. Como usuário do SO Oracle, execute a ferramenta oraenv para definir as variáveis de ambiente. Supomos que você já tenha definido o usuário oracle e o ORACLE_SID no arquivo /etc/oratab.

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

  3. Como usuário SYSDBA ou SYSOPER, no Oracle Database, crie um usuário para monitoramento com uma senha que corresponda ao secret criado nos pré-requisitos.

    CREATE USER wlmagent IDENTIFIED BY password;

  4. Como usuário SYSDBA ou SYSOPER, conceda as seguintes permissões ao usuário de monitoramento para consultar visualizações de desempenho:

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

  5. Saia do sqlplus e do usuário oracle.

  6. Como usuário root, edite o arquivo de configuração do agente usando seu editor preferido.

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

  7. No arquivo de configuração, edite a seção oracle_metrics para fazer as seguintes atualizações:

    1. Defina o parâmetro enabled como true.
    2. Defina o parâmetro service_name para especificar o nome do serviço da instância do Oracle que você quer que o agente monitore.
    3. Especifique o nome de usuário do Oracle para que o agente se conecte ao seu banco de dados.
    4. Defina os parâmetros host e port para que o agente se conecte ao seu banco de dados.
    5. Defina o parâmetro secret para que o agente recupere uma senha para o nome de usuário:
      • project_id: o ID do projeto que contém os dados do Secret Manager.
      • secret_name: o nome do secret no Secret Manager.

    Confira a seguir um exemplo de arquivo de configuração:

    {
  "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. Salve o arquivo de configuração.

  9. Reinicie o agente para que as novas configurações entrem em vigor.

Ver as métricas

É possível conferir as métricas coletadas e monitorar o desempenho e o status do Oracle usando o Metrics Explorer ou importando um painel personalizado.

Ver métricas no Metrics Explorer

Para conferir as métricas do Oracle no Metrics Explorer, faça o seguinte:

  1. No console Google Cloud , acesse Monitoring.
  2. Clique em Metrics Explorer.
  3. Em Encontrar tipo de recurso e métrica, faça o seguinte:
    1. Em Tipo de recurso, selecione Instância de VM.
    2. Em Métrica, selecione as métricas do Oracle que você quer ver.

É possível conferir dados em tempo real e históricos das métricas do Oracle selecionadas, usando filtros e agregação conforme necessário.

Importar um painel personalizado

Para conferir as métricas do Oracle coletadas pelo agente, crie painéis personalizados do Cloud Monitoring seguindo as instruções em Criar e gerenciar painéis personalizados.

Fornecemos um exemplo de painel oracle-status-overview.json e instruções sobre como importá-lo. O painel oracle-status-overview.json mostra os seguintes gráficos de métricas do Oracle:

  • Detalhamento do tempo de banco de dados
  • Uso da memória do banco de dados
  • Média de sessões ativas por classe de espera
  • E/S de disco
  • Uso da CPU
  • Tráfego de rede

Para importar o painel oracle-status-overview.json, faça o seguinte:

  1. Verifique se a CLI gcloud está instalada e atualizada. Para instruções, consulte Instalar a CLI gcloud.

  2. No repositório do GitHub do Agent for Compute Workloads, faça o download do painel 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. Execute o comando a seguir para importar o painel:

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

    Depois que o comando for executado, o painel personalizado será criado no Cloud Monitoring. Para saber como acessar um painel, consulte Encontrar e acessar um painel.

Métricas compatíveis

Todas as métricas do Oracle coletadas pelo agente para cargas de trabalho de computação estão disponíveis no caminho workload.googleapis.com/oracle.

Confira a seguir uma lista das métricas do Oracle compatíveis e os respectivos caminhos do Cloud Monitoring:

  • Memória do processo

    • Memória de processo (PGA) em uso, em bytes.

      process/pga_memory/total_used_size

    • Memória do processo (PGA) alocada, em bytes

      process/pga_memory/total_allocated_size

  • Recordação compartilhada

    • Tamanho do item de memória compartilhada (SGA), em bytes

      process/sga_memory/size

  • Eventos de espera do sistema

    • Número total de esperas para uma classe de espera registrada

      sys_wait/count

    • Tempo total gasto nessa classe de espera, em segundos

      sys_wait/time

    • Total de esperas em primeiro plano nesta classe de espera

      sys_wait/foreground/count

    • Tempo agregado de espera em primeiro plano para essa classe de espera, em segundos.

      sys_wait/foreground/time

  • Tempo decorrido do sistema

    • Tempo decorrido gasto na execução de chamadas no nível do usuário do banco de dados, em segundos.

      sys_time/db_time

    • Tempo de CPU gasto em chamadas no nível do usuário do banco de dados, em segundos

      sys_time/db_cpu

    • Quantidade de tempo decorrido em que as instruções SQL estão sendo executadas

      sys_time/sql_execute_elapsed_time

    • Quantidade de tempo decorrido gasto analisando instruções SQL

      sys_time/parse_time_elapsed

    • Quantidade de tempo decorrido gasto executando o interpretador PL/SQL.

      sys_time/pl_sql_execution_elapsed_time

    • Tempo decorrido consumido por processos em segundo plano do banco de dados, em segundos

      sys_time/background_elapsed_time

  • Estatísticas de E/S

    • Contagem total de operações de leitura (pequenas + grandes)

      iostat/read_ops_count

    • Contagem total de operações de gravação (pequenas + grandes)

      iostat/write_ops_count

    • Número total de bytes lidos

      iostat/read_bytes_count

    • Número total de bytes gravados

      iostat/write_bytes_count

    • Latência média por operação de E/S

      iostat/average_latency_seconds

  • arquivos de dados

    • Tamanho alocado do arquivo de dados, em bytes

      data_files/total_bytes

    • Espaço em uso do arquivo de dados, em bytes

      data_files/bytes_used

    • Espaço livre do arquivo de dados, em bytes

      data_files/available_bytes

    • Limite de extensão automática de arquivo de dados, em bytes

      data_files/max_bytes

    • Porcentagem do arquivo de dados usado

      data_files/percent_used

  • Instância de banco de dados

    • Tempo de atividade da instância, em segundos

      instance/uptime

    • Status da instância

      instance/status

      Essa métrica pode ter os seguintes valores:

      UNKNOWN 0
      STARTED 1
      MOUNTED 2
      OPEN 3
      OPEN MIGRATE 4

    • Modo aberto

      instance/db_open_mode

      Essa métrica pode ter os seguintes valores:

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

  • Oracle Data Guard

    • Atraso para refazer a ação, em segundos

      dataguard/apply_lag

    • Refazer o atraso do transporte, em segundos

      dataguard/transport_lag

Gerenciar o agente

Reinicie o agente.

Se o agente para cargas de trabalho do Compute parar de funcionar ou você atualizar a configuração, reinicie o agente.

  1. Use SSH para se conectar à instância de VM.

  2. Execute este comando:

    sudo systemctl restart google-cloud-workload-agent

Verificar a versão do agente

Para acessar a versão do agente, siga estas etapas:

  1. Use SSH para se conectar à instância de VM.

  2. Execute este comando:

    yum info google-cloud-workload-agent

Verificar se há atualizações

  1. Use SSH para se conectar à instância de VM.

  2. Execute este comando:

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

Atualizar o agente

Para garantir que você tenha a versão mais recente do agente, verifique se há atualizações periodicamente e atualize o agente:

  1. Use SSH para se conectar à instância de VM.

  2. Execute este comando:

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

Ver registros do agente

Os registros do agente para cargas de trabalho de computação estão disponíveis em /var/log/google-cloud-workload-agent.log.

A verbosidade do registro é controlada pelo parâmetro log_level. Definir o nível de registro DEBUG inclui mais informações para resolver problemas específicos, mas produz registros muito maiores.

Por padrão, os registros do agente para cargas de trabalho do Compute são redirecionados das instâncias de VM para o Cloud Logging.

Para ver os registros do agente no Logging, siga estas etapas:

  1. No console Google Cloud , acesse a página Explorador de registros.

    Acessar o "Explorador de registros"

  2. Acesse o painel Consulta.

  3. No menu suspenso Recursos, selecione Global e clique em Aplicar.

  4. No editor de consultas, insira google-cloud-workload-agent.

  5. Clique em Executar consulta.

É possível conferir os registros gerados pelo agente em execução em todas as instâncias de VM. É possível filtrar os registros de uma instância específica.

Configurar registros de agente no Cloud Logging

Para desativar o redirecionamento padrão dos registros do agente para o Cloud Logging, siga estas etapas:

  1. Use SSH para se conectar à instância de VM.

  2. Abra o arquivo de configuração do agente:

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

  3. Para a propriedade log_to_cloud, atualize o valor para false.

  4. Salve o arquivo de configuração.

  5. Reinicie o agente para que essa alteração entre em vigor.

Solução de problemas

As seções a seguir fornecem informações sobre problemas comuns relacionados ao uso do agente para cargas de trabalho do Oracle Database, suas causas e resolução.

Permissões do IAM insuficientes

Problema:os registros do agente para cargas de trabalho do Compute mostram um erro de permissões de IAM insuficientes.

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

Causa:a conta de serviço usada pelo agente não tem as permissões do IAM necessárias para acessar as APIs Google Cloud ou uma senha para o usuário do Oracle no Secret Manager.

Resolução:para resolver esse problema, verifique se a conta de serviço da VM tem os papéis e as permissões do IAM mencionados em Pré-requisitos.

Escopos de autenticação insuficientes

Problema:os registros do agente para cargas de trabalho do Compute mostram escopos de autenticação insuficientes.

googleapi: Error 403: Request had insufficient authentication scopes.

Causa:a conta de serviço usada pelo agente não tem o escopo de acesso necessário.

Resolução:para resolver esse problema, configure os escopos de acesso da VM como cloud-platform.

As métricas não aparecem no Cloud Monitoring

Problema:as métricas do agente para cargas de trabalho do Compute não estão visíveis no Cloud Monitoring.

Causa:

Confira as possíveis causas desse problema:

  • A conta de serviço usada pelo agente para cargas de trabalho do Compute não tem as permissões necessárias do IAM.
  • O usuário do Oracle usado pelo agente não tem privilégios suficientes para consultar visualizações de desempenho.
  • Há erros na configuração do agente.

Resolução:

  • Para resolver o problema de permissões insuficientes da conta de serviço, faça o seguinte:

    1. No console Google Cloud , acesse a página Detalhes da instância de VM e anote a conta de serviço usada pela instância que executa o agente.
    2. Acesse a página IAM e administrador e verifique se a conta de serviço tem todos os papéis e permissões necessários mencionados nos Pré-requisitos. Conceda à conta de serviço qualquer um dos papéis necessários que estão faltando.

  • Para resolver o problema de permissões insuficientes para o usuário do Oracle, faça o seguinte:

    1. Verifique se o usuário do Oracle tem as seguintes permissões necessárias para consultar visualizações de performance:

      • SESSION
      • SELECT_CATALOG_ROLE
      • SYSDG

    2. Conceda as permissões ausentes executando o seguinte comando SQL:

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

  • Para resolver o problema com a configuração incorreta do agente, faça o seguinte:

    1. Use SSH para se conectar à instância de VM.

    2. Analise os registros do agente para identificar erros ou problemas que impeçam a coleta de métricas. Os registros podem ser encontrados em /var/log/google-cloud-workload-agent.log.

      Procure erros de permissão, configurações incorretas ou problemas de conectividade.

    3. Resolva os erros.

    4. Reinicie o agente e verifique se a coleta de métricas começa.

Falha ao carregar o arquivo de configuração

Problema:se o arquivo de configuração tiver valores inválidos, você vai receber o seguinte erro. 

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

Resolução:para resolver esse problema, atualize o arquivo de configuração usando os detalhes em Parâmetros de configuração.

Falha ao inicializar a coleta de dados

Problema:depois de instalar o agente, se o arquivo de configuração não for atualizado, você vai receber o seguinte erro: 

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

Resolução:para resolver esse problema, inicialize a configuração de credenciais usando Parâmetros de configuração.