Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定 Oracle 工作負載的代理程式

本文說明如何在執行 Oracle Database 工作負載的 Compute Engine 執行個體上，安裝、設定及驗證運算工作負載代理。

代理程式會查詢 Oracle Database 效能檢視畫面 (例如 V$DATABASE、V$INSTANCE 和 V$DATAGUARD_STATS) 和資料字典檢視畫面 (例如 DBA_DATA_FILES 和 DBA_FREE_SPACE)，藉此收集各種 Oracle 指標。這些指標隨後會傳送至 Cloud Monitoring，供您查看及分析。請參閱「支援的指標」一文。

事前準備

安裝運算工作負載代理來監控 Oracle Database 工作負載前，請確認符合下列必要條件：

如果還沒有 Compute Engine 執行個體，請先建立。將存取權範圍設定為 cloud-platform。
在 Compute Engine 執行個體上設定根存取權。
查看系統需求。
將 IAM 角色授予服務帳戶。
啟用與 Google Cloud API 端點的連線，可透過公用網路存取或私人網路存取。
如要啟用指標收集功能，請在 Secret Manager 中建立密鑰，儲存資料庫使用者的資料庫密碼，稍後會在本指南中建立該使用者。

在本指南的範例中，我們假設這個值為 wlmagent-password。

查看系統需求

下表列出可用的 Oracle 版本和支援的作業系統版本：

作業系統	Oracle 版本	Oracle 版本
Red Hat Enterprise Linux 7、8 和 9 版 Oracle Linux 7、8 和 9 版	Oracle Database 19c Oracle Database 23ai* 注意：代理程式尚未在 Red Hat Enterprise Linux 7 或 Oracle Linux 7 上執行的 Oracle Database 23ai 進行測試。	Enterprise 版 Standard 版 Express (免費) 版

將 IAM 角色授予服務帳戶

運算工作負載代理會使用連接至運算執行個體的服務帳戶進行驗證，並存取 Google Cloud 資源。

為提高安全性，建議您使用單一用途的服務帳戶，而非 Compute Engine 預設服務帳戶。

為確保服務帳戶具備必要權限，可讓 Compute Workloads 專用代理程式向Google Cloud 驗證身分並存取 Google Cloud 資源，請要求管理員在專案中授予服務帳戶下列 IAM 角色：

從運算執行個體收集指標：Compute 檢視者 (roles/compute.viewer)
將資料寫入 Workload Manager 資料倉儲： Workload Manager 深入分析資訊寫入者 (roles/workloadmanager.insightWriter)
將代理程式記錄檔傳送至 Cloud Logging：記錄檔寫入者 (roles/logging.logWriter)
如果您使用 Secret Manager 儲存密碼，以便連線至 Oracle 執行個體： Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，授予服務帳戶必要權限。

啟用 Cloud API 存取權

Compute Engine 建議您將執行個體設為允許所有存取範圍存取所有 Cloud API，並僅使用執行個體服務帳戶的 IAM 權限，控管對Google Cloud 資源的存取權。詳情請參閱「建立採使用者代管服務帳戶的 VM」。

如果限制 Cloud API 的存取權，則運算工作負載代理至少需要在主機運算執行個體上具備下列 Cloud API 存取權範圍：

https://www.googleapis.com/auth/cloud-platform

詳情請參閱「範圍最佳做法」。

如果您在沒有外部 IP 位址的運算執行個體上執行 Oracle 工作負載，則需要在執行個體的子網路上啟用 Private Google Access，這樣運算工作負載代理才能存取 Google API 和服務。如要瞭解如何啟用 Private Google Access，請參閱「設定 Private Google Access」。

使用套件管理工具安裝及設定代理程式

本節說明如何使用套件管理工具，在運算執行個體上安裝運算工作負載代理，並設定該代理程式以連線至 Oracle 執行個體。

如要安裝運算工作負載代理，請完成下列步驟：

建立存放區設定檔。

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

更新套件管理員的中繼資料：
```
sudo yum makecache
```

安裝 google-cloud-workload-agent rpm 套件：

sudo yum install google-cloud-workload-agent

為 Oracle 工作負載安裝代理程式後，請驗證代理程式安裝作業。

使用 VM 擴充功能管理工具，在 VM 機群上安裝及管理代理程式

本節說明如何使用 VM 擴充功能管理工具，在 VM 機群上安裝及管理運算工作負載代理。

VM 擴充功能管理工具政策可讓您執行下列工作：

全車隊安裝：在下列項目中安裝運算工作負載代理程式：
- 專案中的所有 VM，或是以標籤識別的部分 VM。 Google Cloud
- 可用區中的所有 VM，或透過標籤識別的 VM 子集。
設定管理：將自訂設定套用至政策管理的所有 VM 上的代理程式。

如要進一步瞭解 VM 擴充功能管理工具，請參閱「關於 VM 擴充功能管理工具」。

設定 VM 擴充功能管理工具

如要設定 VM 擴充功能管理工具，請完成下列步驟：

在 VM 擴充功能管理工具說明文件中，查看「開始前準備」一節。
設定建立及管理 VM 擴充功能管理工具政策所需的 IAM 角色。詳情請參閱下列資源：

在 VM 機群上安裝及設定代理程式

如要使用 VM 擴充功能管理工具政策，在 VM 機群上安裝最新版運算工作負載代理，請參閱下列適當章節：

在 Google Cloud 專案的 VM 上安裝及設定代理程式
在特定可用區的 VM 上安裝及設定代理程式

在專案中的 VM 上安裝及設定代理程式 Google Cloud

如要使用 VM 擴充功能管理工具政策，在專案中的所有 VM 或標籤識別的部分 VM 上安裝代理程式，請完成下列步驟： Google Cloud

控制台

前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。

前往 VM 擴充功能政策
按一下「建立擴充功能政策」。
在「Name」(名稱) 欄位中，輸入政策名稱。
選用：在「Description」(說明) 欄位中輸入政策說明。
在「Priority」欄位中，指定優先順序值，解決政策間的衝突。數字越小越優先。預設值為 1000。
在「範圍」部分，選取「全球推出」。
在「管理擴充功能」部分，按一下「新增擴充功能」，然後執行下列操作：
1. 在「擴充功能」清單中，選取「Google Cloud's Extension for Compute Workloads」。
2. 將「版本」欄位留空。
  
  這項政策會指示系統安裝最新版運算工作負載代理。
3. 在「設定檔內容」欄位中，輸入要套用至代理程式的設定。
  
  如要瞭解 Oracle 工作負載代理程式支援的設定參數，請參閱「設定參數」。
  
  注意： 如果將 VM 擴充功能管理員政策套用至已執行 Compute Workloads 代理程式的 VM，政策會覆寫現有代理程式的版本和設定。
  
  代理程式的現有設定會寫入各 VM 的 /etc/google-cloud-workload-agent/ 目錄中的 BAK 檔案。
4. 按一下「完成」。
5. 在「推出」欄位中，選取要使用的推出計畫選項：「緩慢推出 (建議)」或「快速推出」。
  
  如要瞭解推出計畫，請參閱「推出計畫簡介」。
選用：如要將政策推出範圍限制在必要 VM，請按照下列步驟操作：
1. 按一下「新增標籤」，然後加入可識別所需 VM 的標籤。
2. 按一下「完成」。
點選「建立」。

gcloud

在終端機或 Cloud Shell 中執行 gcloud compute global-vm-extension-policies create 指令：

gcloud compute global-vm-extension-policies create POLICY_NAME \
    --project=PROJECT_ID \
    --extensions=google-cloud-workload-extension  \
    --rollout-predefined-plan=ROLL_OUT_SPEED \
    [--description="<var>DESCRIPTION</var>" \]
    [--inclusion-labels=KEY1=VALUE1,KEY2=VALUE2 \]
    [--config-from-file=google-cloud-workload-extension="CONFIG_FILE_PATH" \]
    [--priority=PRIORITY]

更改下列內容：

POLICY_NAME：VM 擴充功能政策的專屬名稱。
PROJECT_ID：您要建立政策的Google Cloud 專案專案 ID
ROLL_OUT_SPEED：您希望政策的推出速度有多快。支援的值為 slow_rollout (建議) 和 fast_rollout。詳情請參閱「關於推出計畫」。
或者，您也可以指定 --rollout-custom-plan 選項，使用自訂推出計畫。詳情請參閱「關於推出計畫」。
您可以使用 --rollout-predefined-plan 或 --rollout-custom-plan，但不能在同一個指令中同時使用兩者。
DESCRIPTION：政策的選用說明。
CONFIG_FILE_PATH：JSON 檔案的本機路徑，其中包含運算工作負載代理的設定。
- 或者，如要以內嵌字串形式提供設定，請使用 --config 標記，而非 --config-from-file。例如：--config=google-cloud-workload-extension="CONFIG"。
- 您可以選擇使用 --config-from-file 或 --config，但不能在同一個指令中同時使用兩者。
- 如要瞭解代理程式支援的設定參數，請參閱「設定參數」。
注意： 如果將 VM 擴充功能管理員政策套用至已執行 Agent for Compute Workloads 的 VM，政策會以您在政策中設定的內容，覆寫現有代理程式的版本和設定。

代理程式的現有設定會寫入各 VM 的 /etc/google-cloud-workload-agent/ 目錄中的 BAK 檔案。
KEY_1=VALUE_1：以逗號分隔的清單，其中包含定義政策用來指定虛擬機的標籤的鍵/值組合。
- 如要讓政策以 VM 為目標，VM 必須具備所有指定的標籤。
- 如果您多次指定 --inclusion-labels，政策會以符合任何所提供選取器的 VM 為目標 (邏輯 OR)。如果省略這個標記，政策會以專案中的所有 VM 為目標。
PRIORITY：介於 0 到 65535 的整數，用於定義政策的優先順序。數字越小越優先。預設值為 1000。詳情請參閱「政策優先順序和衝突解決方式」。

在特定可用區的 VM 上安裝及設定代理程式

如要使用 VM 擴充功能管理工具政策，在特定可用區的 VM 機群上安裝及設定最新版運算工作負載代理，請完成下列步驟：

控制台

前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。

前往 VM 擴充功能政策
按一下「建立擴充功能政策」。
在「Name」(名稱) 欄位中，輸入政策名稱。
選用：在「Description」(說明) 欄位中輸入政策說明。
在「Priority」欄位中，指定優先順序值，解決政策間的衝突。數字越小越優先。預設值為 1000。
使用「Region」(區域) 和「Zone」(可用區) 清單，選取要套用這項政策的可用區。
在「管理擴充功能」部分，按一下「新增擴充功能」，然後執行下列操作：
1. 在「擴充功能」清單中，選取「Google Cloud's Extension for Compute Workloads」。
2. 將「版本」欄位留空。
  
  這項政策會指示系統安裝最新版運算工作負載代理。
3. 在「設定檔內容」欄位中，輸入要套用至代理程式的設定。
  
  如要瞭解 Oracle 工作負載代理程式支援的設定參數，請參閱「設定參數」。
  
  注意： 如果將 VM 擴充功能管理員政策套用至已執行 Agent for Compute Workloads 的 VM，政策會覆寫現有代理程式的版本和設定，並採用您在政策中設定的內容。
  
  代理程式的現有設定會寫入各 VM 的 /etc/google-cloud-workload-agent/ 目錄中的 BAK 檔案。
4. 按一下「完成」。
選用：如要將政策推出範圍限制在必要 VM，請按照下列步驟操作：
1. 按一下「新增標籤」，然後加入可識別所需 VM 的標籤。
2. 按一下「完成」。
點選「建立」。

gcloud

gcloud compute zone-vm-extension-policies create POLICY_NAME \
    --zone=ZONE \
    --extensions=google-cloud-workload-extension \
    --config-from-file=google-cloud-workload-extension=CONFIG_FILE_PATH \
    [--description="DESCRIPTION" \]
    [--inclusion-labels=KEY_1=VALUE_1 \]
    [--inclusion-labels=KEY_2=VALUE_2,KEY_3=VALUE_3 \]
    [--priority=PRIORITY]

更改下列內容：

POLICY_NAME：VM 擴充功能政策的名稱。

如果區域中已有指定名稱的政策，這項指令就會失敗。
ZONE：要套用這項政策的可用區。
CONFIG_FILE_PATH：JSON 檔案的本機路徑，其中包含運算工作負載代理的設定，可與 Oracle 工作負載連線。
- 或者，如要以內嵌字串形式提供設定，請使用 --config 標記，而非 --config-from-file。例如：--config=google-cloud-workload-extension="CONFIG"。Google Cloud 建議使用 --config-from-file。
- 您可以選擇使用 --config-from-file 或 --config，但不能在同一個指令中同時使用兩者。
- 如要瞭解 Oracle 工作負載代理程式支援的設定參數，請參閱「設定參數」。
注意： 如果將 VM 擴充功能管理員政策套用至已執行 Agent for Compute Workloads 的 VM，政策會以您在政策中設定的內容，覆寫現有代理程式的版本和設定。

代理程式的現有設定會寫入各 VM 的 /etc/google-cloud-workload-agent/ 目錄中的 BAK 檔案。
DESCRIPTION：政策的選用說明。
KEY_1=VALUE_1：以逗號分隔的清單，其中包含定義政策用來指定虛擬機的標籤的鍵/值組合。
- 如要讓政策以 VM 為目標，VM 必須具備所有指定的標籤。
- 如果您多次指定 --inclusion-labels，政策就會以符合任何所提供選取器的 VM 為目標 (邏輯 OR)。如果省略這個標記，政策就會以指定可用區中的所有 VM 為目標。
PRIORITY：介於 0 到 65535 的整數，用於定義政策的優先順序。數字越小越優先。預設值為 1000。

範例：

下列指令會在名為 test-project 的專案中建立名為 test-agent-policy 的政策，並在可用區 us-centrail-f 中部署的所有 VM 上安裝最新版運算工作負載代理。Google Cloud agent-config.json 中指定的設定會套用至代理程式。

gcloud compute zone-vm-extension-policies create test-agent-policy  \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=google-cloud-workload-extension \
    --config-file-path=google-cloud-workload-extension="/usr/agent-config.json"

管理 VM 機群中的代理程式

如要變更 VM 擴充功能管理工具政策管理運算工作負載代理的方式，請更新政策。更新政策後，VM 擴充功能管理工具通常會在 1 分鐘內，將變更內容套用至所有適用的 VM。如果您修改納入標籤，系統可能會根據 VM 是否符合更新後的標籤，在新 VM 上安裝運算工作負載代理，或從現有 VM 解除安裝。

以下各節說明如何管理運算工作負載代理，以執行下列操作：

在 VM 機群上修改代理程式設定
更新全域政策，納入新區域
更新全域政策，排除區域

修改 VM 機群的代理程式設定

如要修改您使用 VM 擴充功能管理工具政策，在 VM 機群上安裝的運算工作負載代理執行個體設定，請編輯該政策。

如要在 VM 叢集上修改代理程式設定，請完成下列步驟：

控制台

前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。

前往 VM 擴充功能政策
按一下要修改的政策。
在「擴充功能政策詳細資料」頁面中，按一下「編輯」。
在「管理擴充功能」部分，切換「Google Cloud 的 Compute Workloads 擴充功能」。
在「設定檔內容」欄位中，輸入要套用至代理程式的設定。

如要瞭解代理程式支援的設定參數，請參閱「設定參數」。
按一下「完成」。
按一下 [儲存]。

gcloud

如要修改 VM 叢集上 Agent for Compute Workloads 的設定，請執行 gcloud compute zone-vm-extension-policies update 指令。使用 gcloud 更新政策時，要求會完全取代現有政策。如果您省略任何選填欄位，系統會將這些欄位還原為預設值，而不是保留修改後政策的現有值。

如要修改代理程式設定，請按照下列步驟操作：

gcloud compute zone-vm-extension-policies update POLICY_NAME \
    --zone=ZONE \
    --extensions=google-cloud-workload-extension \
    --config-from-file=google-cloud-workload-extension="CONFIG_FILE_PATH" \
    [--inclusion-labels=KEY_1=VALUE_1 \]
    [--inclusion-labels=KEY_2=VALUE_2,KEY_3=VALUE_3 \]
    [--priority=PRIORITY_NUMBER \]
    [--description="DESCRIPTION"]

更改下列內容：

POLICY_NAME：要修改的 VM 擴充功能政策名稱。
ZONE：政策適用的 Google Cloud 區域。
CONFIG_FILE_PATH：JSON 檔案的本機路徑，其中包含運算工作負載代理的設定。
- 您也可以使用 --config 旗標，以內嵌字串的形式提供代理程式設定，而非使用 --config-from-file。例如：--config=google-cloud-workload-extension="CONFIG"。Google Cloud 建議使用 --config-from-file。
- 您可以選擇使用 --config-from-file 或 --config，但不能在同一個指令中同時使用兩者。
- 如要瞭解代理程式支援的設定參數，請參閱「設定參數」。
KEY_1=VALUE_1：以半形逗號分隔的鍵/值組合清單，定義政策用來指定 VM 的標籤。
- 如要讓政策以 VM 為目標，VM 必須具備所有指定的標籤。
- 如果您多次指定 --inclusion-labels，政策就會以符合任何所提供選取器的 VM 為目標 (邏輯 OR)。如果省略這個標記，政策就會以指定可用區中的所有 VM 為目標。
PRIORITY_NUMBER：要為政策設定的優先順序。您可以指定 0 到 65535 的整數。
DESCRIPTION：VM 擴充功能政策的說明。

更新全域政策，納入新區域

建立及推出全域政策後，如果您在新的可用區中建立 VM，VM 擴充功能管理工具不會自動將政策套用至新可用區中的 VM。如要在新區域中納入 VM，您必須重新啟動全域政策推出程序。

如要重新啟動全域政策推出程序，請完成下列步驟：

在終端機或 Cloud Shell 中，執行 gcloud compute global-vm-extension-policies update 指令，並提供 --rollout-entry-uuid 選項，如下所示：
```
gcloud compute global-vm-extension-policies update POLICY_NAME \
    --project=PROJECT_ID \
    --extensions=google-cloud-workload-extension  \
    --rollout-predefined-plan=ROLL_OUT_SPEED \
    --config-from-file=google-cloud-workload-extension="CONFIG_FILE_PATH" \
    --rollout-retry-uuid=UUID
```
更改下列內容：
- UUID：通用專屬 ID (UUID)，用於識別重試要求。您可以使用任何 UUID 生成器建立 UUID。詳情請參閱「重試發布」。
- ROLL_OUT_SPEED：您希望政策的推出速度有多快。支援的值為 slow_rollout (建議) 和 fast_rollout。詳情請參閱「關於推出計畫」。
- 或者，您也可以指定 --rollout-custom-plan 選項，使用自訂推出計畫。詳情請參閱「關於推出計畫」。
- 您可以使用 --rollout-predefined-plan 或 --rollout-custom-plan，但不能在同一個指令中同時使用兩者。

更新排除區域的全球政策

如要更新全域政策以排除區域，請完成下列步驟：

在終端機或 Cloud Shell 中執行 gcloud compute global-vm-extension-policies update 指令，並提供自訂推出計畫，指定要套用政策的可用區：
```
gcloud compute global-vm-extension-policies update POLICY_NAME \
    --project=PROJECT_ID \
    --extensions=google-cloud-workload-extension  \
    --rollout-custom-plan=projects/PROJECT_ID/locations/global/rolloutPlans/NEW_CUSTOM_PLAN_NAME \
    --rollout-retry-uuid=UUID
```
更改下列內容：
- NEW_CUSTOM_PLAN_NAME：新自訂推出計畫的名稱，用於識別要套用政策的區域。如要瞭解如何建立自訂推出計畫，請參閱「關於推出計畫」。
- UUID：通用專屬 ID (UUID)，用於識別重試要求。您可以使用任何 UUID 生成器建立 UUID。詳情請參閱「重試發布」。

從 VM 機群解除安裝代理程式

如要從 VM 機群解除安裝運算工作負載代理，請刪除管理 VM 機群的 VM 擴充功能管理工具政策。

刪除政策時，如果另一個優先順序較低的有效政策適用於 VM，並宣告運算工作負載代理，則該代理程式會根據優先順序較低的政策，繼續安裝在 VM 上。

VM 擴充功能管理工具會在政策刪除後一分鐘內，從所有可存取的 VM 中移除代理程式。如果 VM 無法存取 (因為客體代理程式已移除或 VM 已刪除)，VM 擴充功能管理工具會略過刪除運算工作負載代理的作業。如果這類 VM 再次可用，VM 擴充功能管理工具就會移除運算工作負載代理。

如要從 VM 機群解除安裝運算工作負載代理，請完成下列步驟：

控制台

前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。

前往 VM 擴充功能政策
按一下管理 VM 叢集上 Agent for Compute Workloads 的政策。
在「擴充功能政策詳細資料」頁面中，按一下「刪除」並確認刪除。

gcloud

gcloud compute zone-vm-extension-policies delete POLICY_NAME \
    --project=PROJECT_ID \
    --zone=ZONE

更改下列內容：

POLICY_NAME：要刪除的 VM 擴充功能政策名稱。
PROJECT_ID：政策所在的 Google Cloud 專案 ID。
ZONE：政策所在的 Google Cloud 區域。

驗證代理程式安裝作業

如要確認代理程式運作狀況符合預期，請完成下列步驟：

與運算執行個體建立 SSH 連線。

檢查代理程式套件的狀態：

systemctl status google-cloud-workload-agent

如果代理程式套件運作正常，輸出內容會包含 active (running)。例如：

google-cloud-workload-agent.service - Google Cloud Agent for Compute Workloads
Loaded: loaded (/usr/lib/systemd/system/google-cloud-workload-agent.service; enabled; vendor preset: disabled)
Active: active (running) since Sun 2025-07-30 18:59:12 UTC; 10s ago
Main PID: 14412 (google_cloud_sq)
  Tasks: 7
Memory: 12.9M (max: 1.0G limit: 1.0G available: 1011.0M)
CGroup: /system.slice/google-cloud-workload-agent.service
        └─ 14412 /usr/bin/google_cloud_sql_server_agent --action=run

設定參數

運算工作負載代理支援 Oracle 的下列設定參數：

參數		說明
`log_level`	`String` 如要設定代理程式的記錄層級，請新增記錄層級。可用的記錄層級如下： `DEBUG` `INFO` `WARNING` `ERROR` 預設值為 `INFO`。
`log_to_cloud`	`Boolean` 如要將代理的記錄重新導向至 Cloud Logging，請指定 `true`。預設值為 `true`。
`oracle_configuration.enabled`	`Boolean` 選用。判斷 Oracle 服務是否處於啟用狀態。如果設為 `true`，或未設定但工作負載存在，您可以設定探索和指標收集功能。如果設為 `false`，系統會停用 Oracle 服務和相關功能。
只有在指定 `oracle_configuration.enabled: true` 時，下列子項參數才會生效。
`oracle_configuration.oracle_discovery.enabled`	`Boolean` 選用。判斷 Oracle Discovery 是否處於啟用狀態。預設值為 `true`。
`oracle_configuration.oracle_discovery.update_frequency`	`Int` 選用。以秒為單位指定取樣間隔，決定運算工作負載代理執行探索程序的頻率。預設值為 3600 秒 (1 小時)。請務必在值結尾加上小寫的「s」，表示秒數。例如：`30s`。
`oracle_configuration.oracle_metrics.enabled`	`Boolean` 選用。如要讓運算工作負載代理程式收集 Oracle 監控指標，請指定 `true`。預設值為 `false`。
只有在指定 `oracle_metrics.enabled: true` 時，下列子項參數才適用。
`oracle_configuration.oracle_metrics.collection_frequency`	`Int` 選用。以秒為單位指定取樣間隔，這會決定運算工作負載代理查詢 Oracle Database 執行個體的頻率，以收集 Oracle 監控指標。預設值為 60 秒。請務必在值結尾加上小寫的「s」，表示秒數。例如：`30s`。
`oracle_configuration.oracle_metrics.query_timeout`	`String` 選用。為向 Oracle 資料庫執行個體發出的每項查詢指定逾時時間。預設值為 10 秒。請務必在值結尾加上小寫的「s」，表示秒數。例如：`30s`。
`oracle_configuration.oracle_metrics.connection_parameters.username`	`String` 指定用於查詢 Oracle 資料庫執行個體的使用者帳戶。請確認該使用者擁有讀取 Oracle 資料庫中效能檢視畫面的必要權限。
`oracle_configuration.oracle_metrics.connection_parameters.host`	`String` 指定代管資料庫執行個體的本機 ID。
`oracle_configuration.oracle_metrics.connection_parameters.port`	`Int` 指定 Oracle 資料庫執行個體接受查詢的通訊埠。
`oracle_configuration.oracle_metrics.connection_parameters.service_name`	`String` 指定要讓代理程式監控的 Oracle 資料庫執行個體服務名稱。
`oracle_configuration.oracle_metrics.connection_parameters.secret.project_id`	`String` 指定 Secret Manager 的專案 ID，以擷取向資料庫發出查詢的使用者密碼。
`oracle_configuration.oracle_metrics.connection_parameters.secret.secret_name`	`String` 指定 Secret Manager 中儲存使用者帳戶密碼的密鑰名稱。

收集及查看 Oracle 指標

您可以啟用 Oracle Database 工作負載的指標收集功能。請參閱「支援的指標」一文。

啟用指標收集功能

如要使用運算工作負載代理程式啟用 Oracle 指標收集功能，請執行下列操作：

使用 SSH 連線至 VM 執行個體。
以 Oracle OS 使用者身分執行 oraenv 工具，設定環境變數。我們假設您已在 /etc/oratab 檔案中定義 oracle 使用者和 ORACLE_SID。
```
sudo su - oracle
export PATH=$PATH:/usr/local/bin
. oraenv
sqlplus / as sysdba
```
以 SYSDBA 或 SYSOPER 使用者身分，在 Oracle 資料庫中建立用於監控的使用者，並設定密碼，該密碼須與您在必要條件中建立的密碼相符。

注意： 如果您有 Oracle Multitenant 容器資料庫，請在使用者名稱前加上 common_user_prefix (通常是 c##)，建立一般使用者。舉例來說，wlmagent 會變成 c##wlmagent。
```
CREATE USER wlmagent IDENTIFIED BY password;
```
以 SYSDBA 或 SYSOPER 使用者身分，將下列權限授予監控使用者，以便查詢成效檢視畫面：
- SESSION
- SELECT_CATALOG_ROLE
- SYSDG
```
GRANT CREATE SESSION,SELECT_CATALOG_ROLE,SYSDG TO wlmagent;
```
退出 sqlplus 和 oracle 使用者。
以超級使用者身分，使用偏好的編輯器編輯代理程式的設定檔。
```
sudo nano /etc/google-cloud-workload-agent/configuration.json
```

在設定檔中，編輯 oracle_metrics 區段，進行下列更新：

將參數 enabled 設為 true。
設定 service_name 參數，指定要讓代理程式監控的 Oracle 執行個體服務名稱。
指定代理程式連線至資料庫時使用的 Oracle 使用者名稱。
設定代理的 host 和 port 參數，以便連結至資料庫。
設定代理程式的 secret 參數，以擷取使用者名稱的密碼：
- project_id：包含 Secret Manager 資料的專案 ID。
- secret_name：Secret Manager 中的 Secret 名稱。

以下是設定檔範例：

{
  "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"
          }
        }
      ]
    }
  }
}

儲存設定檔。
重新啟動代理程式，新設定就會生效。

查看指標

您可以透過Metrics Explorer或匯入自訂資訊主頁，查看收集到的指標，並監控 Oracle 效能和狀態。

在 Metrics Explorer 中查看指標

如要在 Metrics Explorer 中查看 Oracle 指標，請按照下列步驟操作：

前往 Google Cloud 控制台的「Monitoring」。
按一下「Metrics Explorer」。
在「尋找資源類型和指標」下方，執行下列操作：
1. 在「資源類型」部分，選取「VM 執行個體」。
2. 在「指標」中，選取要查看的 Oracle 指標。

您可以查看所選 Oracle 指標的即時和歷來資料，並視需要使用篩選器和匯總功能。

匯入自訂資訊主頁

如要查看代理程式收集的 Oracle 指標，請按照「建立及管理自訂資訊主頁」一文的說明，建立自訂 Cloud Monitoring 資訊主頁。

我們提供範例資訊主頁 oracle-status-overview.json 和匯入方式說明。oracle-status-overview.json 資訊主頁會顯示下列 Oracle 指標圖表：

資料庫時間細目
資料庫記憶體用量
依等待類別劃分的平均有效工作階段數
磁碟 I/O
CPU 使用率
網路流量

如要匯入 oracle-status-overview.json 資訊主頁，請按照下列步驟操作：

確認 gcloud CLI 已安裝且為最新版本。如需操作說明，請參閱「安裝 gcloud CLI」。

從運算工作負載代理 GitHub 存放區下載 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

執行下列指令匯入資訊主頁：
```
gcloud alpha monitoring dashboards create --config-from-file=oracle-status-overview.json
```
指令執行完畢後，自訂資訊主頁就會在 Cloud Monitoring 中建立。如要瞭解如何查看資訊主頁，請參閱「尋找及查看資訊主頁」。

支援的指標

運算工作負載代理收集的所有 Oracle 指標，都會顯示在 workload.googleapis.com/oracle 路徑下。

以下列出支援的 Oracle 指標，以及對應的 Cloud Monitoring 路徑：

程序記憶體
- 程序 (PGA) 目前使用的記憶體，以位元組為單位。
  
  process/pga_memory/total_used_size
- 分配的程序 (PGA) 記憶體，以位元組為單位
  
  process/pga_memory/total_allocated_size
共用回憶集錦
- 共用記憶體 (SGA) 項目的大小 (以位元組為單位)
  
  process/sga_memory/size
系統等待事件
- 已註冊等待類別的等待總數
  
  sys_wait/count
- 這個等待類別的總等待時間 (以秒為單位)
  
  sys_wait/time
- 這個等待類別中的前景等待總數
  
  sys_wait/foreground/count
- 這個等待類別的前景等待時間總計 (以秒為單位)
  
  sys_wait/foreground/time
系統經過時間
- 執行資料庫使用者層級呼叫所經過的時間 (以秒為單位)
  
  sys_time/db_time
- 資料庫使用者層級呼叫所用的 CPU 時間，以秒為單位
  
  sys_time/db_cpu
- SQL 陳述式執行的經過時間量
  
  sys_time/sql_execute_elapsed_time
- 剖析 SQL 陳述式所花費的時間量
  
  sys_time/parse_time_elapsed
- 執行 PL/SQL 解譯器所耗費的時間量
  
  sys_time/pl_sql_execution_elapsed_time
- 資料庫背景程序耗費的時間 (以秒為單位)
  
  sys_time/background_elapsed_time
I/O 統計資料
- 讀取作業總數 (小型 + 大型)
  
  iostat/read_ops_count
- 寫入作業總數 (小型 + 大型)
  
  iostat/write_ops_count
- 讀取的位元組總數
  
  iostat/read_bytes_count
- 寫入的位元組總數
  
  iostat/write_bytes_count
- 每項 I/O 作業的平均延遲時間
  
  iostat/average_latency_seconds
資料檔案
- 資料檔案的配置大小 (以位元組為單位)
  
  data_files/total_bytes
- 目前使用的資料檔案空間 (以位元組為單位)
  
  data_files/bytes_used
- 資料檔案可用空間，以位元組為單位
  
  data_files/available_bytes
- 資料檔案自動擴充限制 (以位元組為單位)
  
  data_files/max_bytes
- 資料檔案的使用百分比
  
  data_files/percent_used
資料庫執行個體
- 執行個體運作時間 (以秒為單位)
  
  instance/uptime
- 執行個體狀態
  
  instance/status
  
  這項指標可能的值如下：
  
  UNKNOWN 0
  
  STARTED 1
  
  MOUNTED 2
  
  OPEN 3
  
  OPEN MIGRATE 4
- 開放模式
  
  instance/db_open_mode
  
  這項指標可能的值如下：
  
  UNKNOWN 0
  
  MOUNTED 1
  
  READ WRITE 2
  
  READ ONLY 3
  
  READ ONLY WITH APPLY 4
Oracle Data Guard
- 重新套用延遲時間 (以秒為單位)
  
  dataguard/apply_lag
- 重做傳輸延遲時間 (以秒為單位)
  
  dataguard/transport_lag

管理代理程式

重新啟動代理程式

如果運算工作負載代理停止運作或更新設定，請重新啟動代理程式。

使用 SSH 連線至 VM 執行個體。

執行下列指令：

sudo systemctl restart google-cloud-workload-agent

檢查代理程式版本

如要查看代理程式版本，請完成下列步驟：

使用 SSH 連線至 VM 執行個體。
執行下列指令：
```
yum info google-cloud-workload-agent
```

檢查是否有更新

使用 SSH 連線至 VM 執行個體。

執行下列指令：

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

更新代理程式

為確保您使用的是最新版代理程式，請定期檢查更新並更新代理程式：

使用 SSH 連線至 VM 執行個體。

執行下列指令：

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

查看代理記錄

運算工作負載代理記錄位於 /var/log/google-cloud-workload-agent.log。

記錄詳細程度是由 log_level 參數控制。設定 DEBUG 記錄層級包含其他資訊，可協助排解特定問題，但會產生大量記錄。

根據預設，運算工作負載代理的記錄會從 VM 執行個體重新導向至 Cloud Logging。

如要在 Logging 中查看代理程式的記錄，請按照下列步驟操作：

前往 Google Cloud 控制台的「Logs Explorer」頁面。

前往「記錄檔探索工具」
前往「Query」(查詢) 窗格。
從「資源」下拉式選單中選取「全域」，然後按一下「套用」。
在查詢編輯器中輸入 google-cloud-workload-agent。
點選「執行查詢」。

您可以查看在所有 VM 執行個體上執行的代理程式所產生的記錄。您可以篩選特定執行個體的記錄。

在 Cloud Logging 中設定代理程式記錄

如要停用代理程式記錄檔預設重新導向至 Cloud Logging 的功能，請按照下列步驟操作：

使用 SSH 連線至 VM 執行個體。

開啟代理程式的設定檔：

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

將屬性 log_to_cloud 的值更新為 false。
儲存設定檔。
重新啟動代理程式，變更才會生效。

疑難排解

以下各節提供使用 Oracle Database 工作負載代理程式時的常見問題、原因和解決方法。

IAM 權限不足

問題：運算工作負載代理記錄顯示 IAM 權限不足錯誤。

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

原因：代理程式使用的服務帳戶沒有必要的 IAM 權限，無法存取 Google Cloud API 或 Secret Manager 中 Oracle 使用者的密碼。

解決方法：如要解決這個問題，請確認 VM 服務帳戶具備「必要條件」中提及的 IAM 角色和權限。

驗證範圍不足

問題：運算工作負載代理記錄顯示驗證範圍不足。

googleapi: Error 403: Request had insufficient authentication scopes.

原因：代理程式使用的服務帳戶沒有必要存取權範圍。

解決方法：如要解決這個問題，請將 VM 的存取範圍設為 cloud-platform。

Cloud Monitoring 未顯示指標

問題：Cloud Monitoring 中未顯示運算工作負載代理的指標。

原因：

以下是造成這個問題的可能原因：

運算工作負載代理使用的服務帳戶缺少必要的 IAM 權限。
代理程式使用的 Oracle 使用者權限不足，無法查詢效能檢視畫面。
代理程式設定有誤。

解決方法：

如要解決服務帳戶權限不足的問題，請按照下列步驟操作：
1. 前往 Google Cloud 控制台的「VM 執行個體詳細資料」頁面，並記下執行代理程式的執行個體所使用的服務帳戶。
2. 前往「IAM & admin」(IAM 與管理) 頁面，確認服務帳戶具備必要條件中提及的所有必要角色和權限。將任何缺少的必要角色授予服務帳戶。
如要解決 Oracle 使用者權限不足的問題，請按照下列步驟操作：
1. 確認 Oracle 使用者具備下列必要權限，可查詢效能檢視畫面：
  - SESSION
  - SELECT_CATALOG_ROLE
  - SYSDG
2. 執行下列 SQL 指令，授予任何缺少的權限：
```
-- Grant the "wlmagent" user the required permissions
GRANT CREATE SESSION,SELECT_CATALOG_ROLE,SYSDG TO USERNAME;
```
如要解決代理程式設定錯誤的問題，請按照下列步驟操作：
1. 使用 SSH 連線至 VM 執行個體。
2. 查看代理程式的記錄，找出導致無法收集指標的錯誤或問題。您可以在 /var/log/google-cloud-workload-agent.log 找到記錄。
  
  找出權限錯誤、設定錯誤或連線問題。
3. 解決所有錯誤。
4. 重新啟動代理程式，並檢查指標收集作業是否已開始。

無法載入設定檔

問題：如果設定檔含有無效值，您會看到下列錯誤。

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

解決方法：如要解決這個問題，請使用「設定參數」中的詳細資料更新設定檔。

無法初始化資料收集作業

問題：安裝代理程式後，如果設定檔未更新，您會看到下列錯誤訊息：

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

解決方法：如要解決這個問題，請使用設定參數初始化憑證設定。

`UNKNOWN`	`0`
`STARTED`	`1`
`MOUNTED`	`2`
`OPEN`	`3`
`OPEN MIGRATE`	`4`

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

設定 Oracle 工作負載的代理程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

查看系統需求

將 IAM 角色授予服務帳戶

啟用 Cloud API 存取權

使用套件管理工具安裝及設定代理程式

使用 VM 擴充功能管理工具，在 VM 機群上安裝及管理代理程式

設定 VM 擴充功能管理工具

在 VM 機群上安裝及設定代理程式

在專案中的 VM 上安裝及設定代理程式 Google Cloud

控制台

gcloud

在特定可用區的 VM 上安裝及設定代理程式

控制台

gcloud

管理 VM 機群中的代理程式

修改 VM 機群的代理程式設定

控制台

gcloud

更新全域政策，納入新區域

更新排除區域的全球政策

從 VM 機群解除安裝代理程式

控制台

gcloud

驗證代理程式安裝作業

設定參數

收集及查看 Oracle 指標

啟用指標收集功能

查看指標

在 Metrics Explorer 中查看指標

匯入自訂資訊主頁

支援的指標

管理代理程式

重新啟動代理程式

檢查代理程式版本

檢查是否有更新

更新代理程式

查看代理記錄

在 Cloud Logging 中設定代理程式記錄

疑難排解

IAM 權限不足

驗證範圍不足

Cloud Monitoring 未顯示指標

無法載入設定檔

無法初始化資料收集作業

設定 Oracle 工作負載的代理程式